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.
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.
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.
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.
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.
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:
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.
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).
/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.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.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.+971****0000. That
is a privacy guard doing its job; note it as a feature.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.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.
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:
// /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": "…" } } } }
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.
«هات لينك الـ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.
https://<host>/mcp/<token>), /mcp bare answers 404, and the URL itself is the secret.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"./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.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).data:
prefix or you will parse nothing), then one real tools/call with its numbers quoted.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.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.
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).