---
name: mcp-server-verification
description: Prove an MCP server actually works end-to-end for a consuming agent — enumerate every tool with its input schema, exercise the read path, then exercise a WRITE and confirm the change is visible on the *user-facing* surface, revert it, and re-confirm the revert. Also covers handing a server to a REMOTE consumer (claude.ai connector / Claude Code over Streamable HTTP, token-in-URL, proving reachability from outside the host). Use when asked "is the MCP working?", "does it really change the data on the site?", "can the agent use it to add content?", "give me the MCP link and how to add it to Claude", after building or changing an MCP server, before handing an MCP to an agent or client, or when a smoke test reports PASS but nobody has ever watched a write land.
---

# Verifying an MCP server (half a test is not a test)

An MCP server is a **write-capable interface to somebody's live data**. "It starts and lists 17
tools" is not verification — it is the first of five stages, and the four that matter are the ones
that touch real records. Sohail's ask lands in exactly this shape:

> *«ال mcp شغال يسطا؟؟؟ خلى كلود يتأكد انه شغال وبيغير البيانات اللى ف الموقع فعلا والايجنت يقدر
> يستخدمه ويضيف محتوى عالداتا بيز بتاعت موقع الديمو ولا لا؟»*

Two questions hide inside that sentence: **does it read?** and **does it write, in a way a human
looking at the site can see?** Answer both with evidence, and clean up after yourself.

## The five stages

### 1. Enumerate — names *and input schemas*

`tools/list` giving a count proves registration, not usability. Pull the schema and classify each
tool read vs write; the write set is your test surface.

```bash
node scripts/mcp_probe.mjs            # every tool + required props + enums + a WRITE/read tag
```

`scripts/mcp_probe.mjs` is a dependency-free stdio JSON-RPC client — spawn the server, initialize,
`tools/list`, optionally `--call <tool> '<json>'`. Use it instead of hand-writing a client per
project. Server output arrives as JSON inside `result.content[0].text`; **parse that string**, don't
assume the result is an object.

### 2. Read — one real call, with the numbers quoted back

Call the most load-bearing read tool and write the returned values into the report verbatim
(`cash = 180000`, first customer name). If a read tool errors, stop here; nothing downstream is
meaningful.

### 3. Write — a marked record, through the MCP, never through SQL

Pick a write tool, create one record whose name/title contains a **unique marker**
(`فحص-كلود-مستقل`, `hermes-write-probe-<epoch>`). Record the returned id. See
`scripts/mcp_write_test.mjs` for the shape: baseline read → create → re-read by marker → report.

**Read the enum from the schema, not from the seed data.** A `create_customer` call was rejected with
`Invalid enum value. Expected 'active' | 'lead' | 'inactive', received 'prospect'` — while the seeded
dataset itself contained a customer with `status: "prospect"`. The tool schema and the domain
vocabulary had drifted apart. That mismatch is a finding to report, not a reason to give up; re-call
with a legal value.

### 4. Confirm it on the surface the *user* looks at

This is the stage everyone skips. An API returning the new record proves the API works — not that the
site changed. Fetch the **public URL** and grep for the marker:

```bash
curl -s --max-time 60 "https://<public-host>/customers" | grep -c 'MARKER'   # expect ≥ 1
curl -s --max-time 60 "https://<public-host>/tasks"     | grep -c 'MARKER'   # expect ≥ 1
```

Only a hit here answers "بيغير البيانات اللي في الموقع فعلاً". A public hit also proves the proxy /
gateway / tunnel path, not just localhost.

### 5. Revert — and prove the revert on the same surface

```bash
cp <db-file> /tmp/backup/before-write      # BEFORE any write. Non-negotiable on a shared demo DB.
# ... write test ...
# cleanup, then:
curl -s "https://<public-host>/customers" | grep -c 'MARKER'   # expect 0
curl -s "https://<public-host>/" | grep -oE '180,000|110,000|141,000' | sort -u   # invariants intact
```

**Prefer the app's own reset/cleanup endpoint over raw SQL.** An app that owns its data will
invalidate its own caches; your SQL will not (see the cache pitfall below).

## Pitfalls — each one cost a real cycle

- **A smoke test that SKIPs is not a PASS.** The project's own smoke script probed `/health`
  unauthenticated; when that probe failed it printed
  `API CHECK: SKIP — no API at … (tools/list path only)` and then `RESULT: PASS`. The one stage that
  would have exercised the key-gated path was silently optional. **Always read the skipped stage
  aloud** — `PASS (1 skip)` is not "it works", and reporting it as green is how an unverified auth
  path ships.
- **Find the source of truth before you trust a cleanup.** The write landed in a single JSON document
  row (`naeb_state.data`); the relational `customers` / `tasks` tables were legacy leftovers. So
  `DELETE FROM customers WHERE id='C5'` removed **0 rows**, `SELECT count(*)` came back with the
  original 4 (looked clean), and the live site went on showing the test record. Before believing any
  revert: grep the *state blob* and the live page, not just the table you assumed was authoritative.
- **Pages cache; `force-dynamic` API routes don't.** The API read straight from the store, so it was
  always fresh — while the rendered pages were ISR-cached and only refreshed through the app's own
  write actions (`revalidatePath`). A raw DB edit therefore leaves the public page stale for as long
  as the cache lives. Clean up through the app, or re-trigger one of its own write paths.
- **Know the blast radius before you write.** A write test against a shared demo DB changes what the
  client sees on the next refresh. Take the file copy, use a marker nobody could mistake for real
  data, and revert in the same session — not "later".
- **Don't report PII masking as data loss.** A response echoed the phone back as `+971****0000`. That
  is a privacy guard doing its job; note it as a feature.
- **Confirm the consumer can actually connect before running a long verification.** A one-line probe
  (`claude -p "how many mcp__<name> tools do you have, and call <read tool>" --mcp-config <file>`)
  costs seconds and rules out config errors; only then launch the full multi-minute verification.
- **A server that fails to connect removes its tools silently — absence, not an error.** When a whole
  server's tools are missing from the agent's list, the reflex is to keep re-guessing tool names; the
  failure is upstream of naming. Check the layers in order before touching any name:

  ```bash
  hermes mcp list                    # is the server configured and enabled at all?
  hermes mcp test <server>           # does it actually CONNECT? (a 30s hang means no)
  <server-venv>/bin/python <server>/main.py    # run the entrypoint by hand — the real error is here
  ```

  `tool_describe` on a name you have *seen work before* answering **"not a deferrable tool"** is the
  tell: the tool is not renamed, the server is not up. The historical names are still recoverable —
  `grep -rhoE 'mcp__[a-z_]+__[a-z_]+' ~/.hermes/logs | sort -u` — and that is also how you establish
  the server once *did* work, so it is worth repairing rather than routing around.
- **A dead long-lived session is the usual cause for a user-account (non-token) server, and it names
  itself.** An authenticated server keeps a session/credential on disk; when the same one is consumed
  from two places, the provider invalidates it rather than sharing it:

  ```
  AuthKeyDuplicatedError: session in use from another IP
  ```

  Retrying never fixes this — it needs a **new** session minted for this box, which usually means an
  interactive re-login the owner completes (a QR scan; Phase 2h of `headless-cli-auth`, script ready at
  `scripts/qr-login-by-proxy.py`). Until that happens the honest report is *"the server is configured but
  its session is dead"* — not *"the MCP is broken"*, and not a silent drop from the verification you were
  asked to run.

## Independent verification by a second agent

The owner will often ask for a *different* agent to confirm — which is also the honest way to check
your own work. Wire it up with a real MCP config and require a machine-readable verdict:

```jsonc
// /tmp/<name>-mcp.json
{ "mcpServers": { "<name>": {
    "command": "node", "args": ["/abs/path/mcp/dist/index.js"],
    "env": { "API_URL": "http://127.0.0.1:3100/api/v1", "API_KEY": "…" } } } }
```

```bash
claude -p "$(cat verify_prompt.txt)" --mcp-config /tmp/<name>-mcp.json \
       --dangerously-skip-permissions < /dev/null > /tmp/verify.out 2>&1
```

The brief must end with a **fixed first-ish line** a script can branch on, so the verification itself
is auditable:

```
MCP-VERDICT: WORKS      (or)      MCP-VERDICT: BROKEN
```

…plus an explicit step ordering: enumerate → read → **write → confirm on the live site → run the
app's reset → confirm the marker is gone → confirm the acceptance numbers are intact**. Telling the
verifier to clean up after itself is what stops an "independent verification" from becoming a second
contamination of the client's demo. Use `templates/mcp-verify-brief.md`.

## Handing it to a REMOTE consumer (different question, same server)

«هات لينك الـMCP وطريقة وضعه في كلود شات» is not a verification task — it is a hand-off, and it fails
in ways verification never touches: the client runs on **somebody else's servers**, so `localhost`
working means nothing.

- claude.ai / ChatGPT connectors cannot send headers → the credential goes **in the path**
  (`https://<host>/mcp/<token>`), `/mcp` bare answers **404**, and the URL itself is the secret.
- **When the source tool is secrets-adjacent, publish a read-only *projection*, not the server.**
  Do not wrap the whole stdio program: import the module once, build a fresh `FastMCP`, register
  only the safe callables (`getattr(orig, "tool_read_only")`) on it, and serve that with
  `app.streamable_http_app()`. Then the check is **absence**: `tools/list` must return exactly the
  intended subset and the dangerous tool (`vault_run`-style exec) must not be listed at all. "It
  returns 403" is a weaker claim than "it does not exist on this surface".
- **Verify the denial path as a matrix, not one bad request**: valid token → 200; wrong token →
  404; `/mcp` with no token → 404; an unrelated path → 404. 404 (not 401) is right for both
  layers — the reverse proxy rejects before the app sees the request, so a scanner learns nothing.
- **Keep the secret out of `systemctl cat` and the logs**: point the unit at a file
  (`Environment=…_TOKEN_FILE=…`) instead of embedding the value, and turn **off** the HTTP
  server's access log when the token lives in the URL path — otherwise the log is a transcript of
  the secret. Assert both as negatives in your script (`grep -c "$TOKEN" <unit>` and the journal → 0).
- Prove it with the **MCP handshake over the public URL** (the reply is **SSE** — strip the `data: `
  prefix or you will parse nothing), then one real `tools/call` with its numbers quoted.
- Prove **reachability from outside** with `check-host.net` (multi-country). Public CORS proxies
  (`allorigins`, `corsproxy`, `codetabs`) return 500/403/522 for URLs that are demonstrably up from
  three countries — they measure themselves, and are a **false-negative generator**. Never conclude
  "not publicly reachable" from one.
- Report `systemctl is-enabled` alongside `is-active`, or the link may die at the next reboot.

Full recipe, the exact curl/check-host commands and the paste-ready hand-off message shape:
`references/remote-mcp-exposure.md`. The read-only projection recipe (FastMCP re-registration of a
tool subset, the systemd unit + reverse-proxy block, the 200/404 verification matrix, and the
secret-hygiene checks) is in `references/read-only-mcp-publishing.md`.

## Support files

- `scripts/mcp_probe.mjs` — stdio JSON-RPC probe: list every tool with schema/kind, or call one.
- `scripts/mcp_write_test.mjs` — marked-write harness: baseline → create → re-read by marker, prints
  the ids you need for cleanup.
- `templates/mcp-verify-brief.md` — brief for the independent verifying agent, ending in the
  `MCP-VERDICT:` line and the mandatory cleanup + invariant checks.
- `references/naeb-mcp-case-study.md` — the full worked example: 17 tools, the JSON-blob store, the
  silent SKIP, the enum drift, and what the live-site proof looked like.
- `references/remote-mcp-exposure.md` — exposing a server to a remote consumer: Streamable HTTP,
  token-in-URL, the SSE handshake probe, `check-host.net` multi-country reachability, why CORS
  proxies lie, and the paste-ready hand-off message.
- `references/read-only-mcp-publishing.md` — publishing a *read-only subset* of a local stdio MCP
  as Streamable HTTP behind a token-in-path proxy: the FastMCP re-registration pattern, the
  systemd unit + Caddy block, the 200/404 verification matrix, and the secret-hygiene checks
  (worked case: the vault MCP on `vault.sohail-remote.top`, 14/14 ad-hoc checks).

Related skills: `ask-claude-when-stuck` (running `claude -p` as a second opinion at all),
`delegated-work-evaluation` (§5 — commissioning an independent reviewer and relaying its fix list),
`web-visual-qa` (browser-side measurement when the write has to appear on a rendered page).
