Fast health checks
Check public discovery:HEAD /mcp confirms endpoint, credential, and origin reachability. It does not initialize an MCP session.
HTTP outcomes
JSON-RPC errors
JSON-RPC errors normally arrive in an HTTP200 response:
Common symptoms
The client connects but shows no or very few tools
The client connects but shows no or very few tools
Run
tools/list directly and read revo://context/effective. The key may have only read roles, the requested capability may be unavailable to that identity, or the client may be displaying a cached catalogue. Reconnect after changing roles; do not grant administrator access only to make setup easier.Every call says the session id is missing
Every call says the session id is missing
Confirm that the client can read the
Mcp-Session-Id response header from initialize and sends it on all later POST and GET requests. Do not look for the id inside the JSON-RPC result body.A previously working session returns 404
A previously working session returns 404
The session expired or no longer matches the credential. Initialize again and replace the locally stored session id. If the key was rotated, always establish a fresh session with the new key.
The listening stream closes but POST calls still work
The listening stream closes but POST calls still work
The SSE connection is a heartbeat/listening channel, not the result transport. Reconnect it with the same valid session id. Tool results continue to return from
POST /mcp.A tool call returns invalid arguments
A tool call returns invalid arguments
Refresh
tools/list, compare the submitted object with inputSchema, include required properties, and remove undeclared fields. A synchronized tool contract may have changed since the client cached it.A tool appears read-only but selected arguments can mutate
A tool appears read-only but selected arguments can mutate
Inspect
classificationMode, possibleSafetyTiers, and mutationIntent. An argument-dependent tool can expose both read and mutation operations. Present confirmation based on the selected operation and target.A remote MCP plugin cannot synchronize
A remote MCP plugin cannot synchronize
Test the remote HTTPS endpoint and its Secret bindings, then review transport type and connection timeout. A connection test and manifest synchronization are separate lifecycle steps. Keep the plugin disabled if the current remote contract cannot be reviewed.
Safe retry rules
- Retry
initialize, discovery, resource reads, prompts, and other confirmed reads with bounded exponential backoff. - Honor
Retry-Afteron429. - On
404, create a new session rather than retrying the old id. - On an uncertain write failure, inspect the returned execution identifier or affected resource before issuing the call again.
- Do not automatically retry destructive or external operations unless their documented contract is idempotent.
- Keep batch size and parallel calls bounded; rate policy counts contained tool and mutation calls.
Evidence to collect
When escalating an MCP problem, provide:- timestamp and environment;
- client name and version;
- HTTP status and JSON-RPC error code;
- JSON-RPC method name;
- whether failure occurred before or after initialization;
- RevoEngine execution or operation identifier when returned;
- redacted request shape and tool name;
- whether a fresh session reproduces the issue.