Go from a report code to the affected contract
Match the exact code from your report. The reported location and evidence show which item is affected. The entry below explains the general condition and the safest usual correction.
This reference covers codes emitted by mcp-doctor 0.4.2. A code describes scoped diagnostic evidence for one target and run. It is not certification, a security audit, or proof of universal MCP conformance.
Startup and STDIO
MCP-TRANSPORT-001
The MCP server process could not be started.
Next step
Check the executable path and permissions, then rerun the same command.
MCP-TRANSPORT-002
The STDIO channel failed before diagnosis completed.
Next step
Fix the server's STDIO lifecycle and rerun the same command.
MCP-TRANSPORT-003
The server wrote an invalid STDIO message.
Next step
Write only newline-delimited JSON-RPC messages to STDOUT; send logs to STDERR.
MCP-TRANSPORT-004
The server process exited before returning a response.
Next step
Keep the server alive long enough to answer the request.
Remote connections
MCP-TARGET-001
The remote MCP endpoint is not safe to use.
Next step
Correct the endpoint structure and rerun with the same intended destination.
MCP-TARGET-002
The invocation does not authorize this remote network activity.
Next step
Review the destination and add only the required exact endpoint gate.
MCP-NETWORK-001
The remote endpoint could not be resolved safely.
Next step
Correct DNS or reduce the answer set, then rerun without widening destination authority.
MCP-NETWORK-002
A resolved address is outside the permitted destination classes.
Next step
Use an eligible destination; prohibited special-purpose addresses cannot be authorized.
MCP-NETWORK-003
The connected peer is outside the one validated pinned address set.
Next step
Correct the resolver or route so the peer matches the validated pinned set.
MCP-TLS-001
The remote endpoint did not complete verified TLS.
Next step
Correct the certificate chain and identity, or provide the intended CA with --tls-ca-file.
MCP-HTTP-001
The bounded HTTP exchange did not complete.
Next step
Correct the direct endpoint or server lifecycle, then rerun the same single operation.
MCP-HTTP-002
The HTTP response does not match the bounded Streamable HTTP contract.
Next step
Return the selected revision's bounded identity-encoded JSON, request-scoped SSE, header, and session behavior.
MCP-HTTP-AUTH-001
The remote endpoint rejected the pre-provisioned authentication.
Next step
Provision the intended credential and rerun; mcp-doctor will not start an OAuth flow.
MCP-HTTP-HEADER-001
A remote request header mapping is invalid or unsafe.
Next step
Correct or remove the unsafe header mapping before replaying the tool.
Protocol and limits
MCP-PROTOCOL-001
The requested protocol revision is supported.
Next step
No correction is needed.
MCP-PROTOCOL-002
The server does not support the required protocol revision.
Next step
Add MCP 2026-07-28 support, then rerun the same diagnosis without falling back.
MCP-PROTOCOL-003
The protocol revision value is missing or has the wrong JSON type.
Next step
Correct the revision field at the reported structural location and rerun the same explicit selection.
MCP-PROTOCOL-004
The server advertises a feature deprecated by this protocol revision.
Next step
Remove or replace the deprecated capability.
MCP-PROTOCOL-005
The server negotiated a different protocol revision than the explicit selection.
Next step
Return the selected revision exactly, or rerun with an explicit supported selection; mcp-doctor will not fall back.
MCP-PROTOCOL-006
The server rejected the selected revision's lifecycle method.
Next step
Confirm the intended revision, then rerun with the exact selection; supported alternatives are --protocol-version 2025-11-25 and --protocol-version 2025-06-18. mcp-doctor did not infer or fall back to another revision.
MCP-LIMIT-001
A configured diagnostic safety limit was exceeded.
Next step
Reduce the reported data or work below the maximum, then rerun the same command.
Cleanup and safety
MCP-SAFETY-001
The managed target could not be fully cleaned up.
Next step
Make the server and descendants exit when STDIN closes or termination is requested.
MCP-SAFETY-002
The remote MCP session could not be terminated within its cleanup bound.
Next step
Make session DELETE complete within the bound, or return 405 when termination is unsupported.
MCP-SAFETY-003
An explicitly declared workflow cleanup step did not complete successfully.
Next step
Inspect the disposable target, correct the cleanup tool behavior, and rerun the same reviewed workflow.
Discovery and tool guidance
MCP-CATALOG-001
An advertised MCP catalog does not match its protocol contract.
Next step
Correct the value at the reported structural location, then rerun inspect.
MCP-CATALOG-002
An advertised catalog contains a duplicate identifier.
Next step
Rename or remove the later duplicate so each identifier is unique.
MCP-CATALOG-003
A catalog repeated a pagination cursor and inspection stopped.
Next step
Return a new cursor for the next page or omit nextCursor on the final page.
MCP-CATALOG-004
The server rejected a catalog method required by the selected revision.
Next step
Implement or correct the reported selected-revision catalog method, then rerun the same explicit selection.
MCP-QUALITY-001
An advertised tool has no usable description.
Next step
Provide a concise description of what the tool does and when to select it.
MCP-QUALITY-002
A required advertised tool input has no usable description.
Next step
Describe the accepted value and any important constraints for this required input.
MCP-QUALITY-003
An advertised tool description provides no selection guidance.
Next step
Replace the placeholder or name-only description with what the tool does and when to select it.
MCP-QUALITY-004
An advertised tool description reuses another tool's selection guidance.
Next step
Distinguish what this tool does, when it should and should not be selected, and how it differs from the tool at first_matching_tool_index.
Schemas and exposed credentials
MCP-SECURITY-001
An advertised input schema embeds a credential-like string literal.
Next step
Remove the literal from the schema and obtain the credential through authorized server runtime configuration.
MCP-SCHEMA-001
A local JSON Schema contract is invalid.
Next step
Correct the schema at the reported structural location and validate it as Draft 2020-12; use the supported linear-time subset for patterns.
MCP-SCHEMA-002
A local schema uses an unsupported JSON Schema dialect.
Next step
For MCP 2025-06-18, declare the Draft 2020-12 URI. Otherwise, remove an unsupported declaration only when the selected revision defines that default, or declare Draft 2020-12 explicitly.
MCP-SCHEMA-003
A schema requires prohibited external reference retrieval.
Next step
Inline the referenced schema or move it into local $defs and use a fragment reference.
MCP-SCHEMA-004
The selected revision does not define a default JSON Schema dialect.
Next step
Declare the exact Draft 2020-12 $schema URI to enable full local semantic validation.
MCP-SCHEMA-005
mcp-doctor could not complete local schema validation within its work bound.
Next step
Provide a minimized, wholly synthetic reproducer through the private project support route, then rerun with a release that can complete validation within the same bound.
Scenarios and authorization
MCP-SCENARIO-001
The check scenario does not match its versioned contract.
Next step
Correct the reported scenario structure and rerun check.
MCP-SCENARIO-002
A scenario environment reference could not be resolved safely.
Next step
Correct the environment reference or null placeholder, provide the value, and rerun check.
MCP-SCENARIO-003
A scenario-provided output schema is not a valid bounded local contract.
Next step
Correct or bound the local output schema, including any unsupported pattern, then rerun check.
MCP-GENERATION-001
Bounded boundary inputs could not be generated from the selected tool schema.
Next step
Expose a bounded object schema with usable const, enum, default, or structural boundaries, or replay reviewed arguments with check.
MCP-AUTH-001
The invocation does not authorize the selected exact tool.
Next step
Pass the selected exact tool name independently through --allow-tool.
MCP-AUTH-002
The invocation does not authorize this side-effecting active run.
Next step
Use a disposable target and add --allow-side-effects only after reviewing the exact tool, seed, and case bound.
Active tool checks
MCP-ACTIVE-001
The exactly authorized tool was not advertised uniquely.
Next step
Advertise one exact matching tool or correct the selection and authorization together.
MCP-ACTIVE-002
The active case arguments do not match the advertised input schema.
Next step
Correct the case arguments or the advertised input schema; the case was not called.
MCP-ACTIVE-003
The server rejected the active tool request.
Next step
Correct the server-side rejection and rerun the same case seed or reviewed case.
MCP-ACTIVE-004
The completed tool result does not match the active case expectation.
Next step
Correct the tool behavior, then rerun the same generated seed or reviewed scenario.
MCP-ACTIVE-005
The structured tool output does not match its required local schema contract.
Next step
Correct structuredContent or the applicable local output schema, then rerun the active command.
MCP-ACTIVE-006
The tool response does not match the selected MCP revision's result contract.
Next step
Return a valid result for the selected MCP revision before running later active cases.
MCP-ACTIVE-007
The selected tool requires task execution that this active run does not perform.
Next step
Advertise optional, forbidden, or omitted task support for this run, or use a task-capable client.
MCP-ACTIVE-008
The server accepted schema-invalid tool arguments instead of rejecting them.
Next step
Validate arguments against the advertised input schema before invoking tool logic, return JSON-RPC -32602, and rerun the same seed.
MCP-WORKFLOW-001
A workflow step did not produce one declared structural capture.
Next step
Correct the producing tool or capture pointer, then rerun the same reviewed workflow.
Contract snapshots
MCP-SNAPSHOT-001
The snapshot is not a valid bounded contract artifact.
Next step
Create a new snapshot with a supported mcp-doctor release instead of editing the artifact by hand.
MCP-SNAPSHOT-002
The snapshot artifact version is unsupported.
Next step
Regenerate the snapshot with this mcp-doctor release, or use the CLI release that created it.
MCP-SNAPSHOT-003
The snapshot protocol revision is unsupported.
Next step
Capture the snapshot with a protocol revision supported by this mcp-doctor release.
MCP-SNAPSHOT-004
The snapshot exceeds a finite artifact or schema bound.
Next step
Reduce the catalog, artifact, or schema below the reported bound, then capture it again.
MCP-SNAPSHOT-005
The snapshot contains a prohibited external JSON Schema reference.
Next step
Inline the external schema or move it into local $defs and use a fragment reference before capturing again.
MCP-SNAPSHOT-006
The snapshot ordinal correlation is invalid.
Next step
Regenerate the snapshot from the source server; do not reorder its contracts or correlation entries by hand.
MCP-SNAPSHOT-007
The snapshot revision identities do not match the required scope.
Next step
Compare snapshots captured for the same MCP protocol revision.
MCP-SNAPSHOT-008
The snapshot revision-specific artifact contract is incompatible.
Next step
Regenerate the snapshot with the correct selected revision and a compatible mcp-doctor release.
Contract changes
MCP-DIFF-001
A contract was added. This change is classified as compatible.
Next step
Review the new contract and update consumers that should use it; no existing contract was removed.
MCP-DIFF-002
A contract was removed. This change may break consumers.
Next step
Restore the contract or coordinate and version the removal before release.
MCP-DIFF-003
A capability was enabled. This change is classified as compatible.
Next step
Review the new capability and confirm its methods and catalogs are ready.
MCP-DIFF-004
A capability was disabled. This change may break consumers.
Next step
Restore the capability or coordinate and version the removal before release.
MCP-DIFF-005
A required input was added. Existing callers may now fail.
Next step
Make the input optional, provide a backward-compatible default, or coordinate a breaking change.
MCP-DIFF-006
A required input was removed. This change is classified as compatible.
Next step
Review callers that may still send the field and confirm the server continues to handle them safely.
MCP-DIFF-007
An input schema constraint was narrowed. Existing accepted values may now fail.
Next step
Keep the previous accepted values or coordinate and version the breaking change.
MCP-DIFF-008
An input schema constraint was widened. This change is classified as compatible.
Next step
Confirm the server safely handles every newly accepted value before release.
MCP-DIFF-009
A contract structure or output changed and requires human review.
Next step
Compare the before and after contracts and decide their compatibility before release.
MCP-DIFF-010
A tool behavior hint changed and requires human review.
Next step
Verify that the read-only, destructive, idempotent, and open-world hints match real behavior, then notify affected consumers.