Mcp Audit

MCP Audit

Audit an MCP server against the current released MCP specification and any repo-specific compatibility constraints.

Read references/spec-baseline.md and references/checklist.md before making changes. Use references/version-watchpoints.md when spec drift, draft features, or older protocol targets may matter. references/common-findings.md captures recurring failure patterns. SOURCES.md is provenance, not the audit checklist.

Workflow

1. Pin the protocol baseline.

• Default to the latest released MCP spec revision unless the repo explicitly targets another version.
• Treat draft and SEP content as watchpoints, not release-blocking requirements, unless the user or repo explicitly asks for draft compatibility.
• Identify which MCP primitives and utilities the server actually implements: prompts, resources, tools, completions, logging, tasks, or experimental extensions.

2. Audit lifecycle and capability negotiation.

• Verify initialize and notifications/initialized behavior, negotiated protocol version, and claimed capabilities.
• Check that the server only advertises capabilities and sub-capabilities it actually supports, such as listChanged, subscribe, or task-related capability blocks.
• For HTTP transports, verify behavior around MCP-Protocol-Version after initialization if the repo owns transport handling directly.

3. Audit tools if present.

• Verify tools/list pagination, notifications/tools/list_changed if claimed, and client-visible metadata from the exported server surface.
• Check tool definitions: name, title, description, icons, inputSchema, outputSchema, annotations, and execution.taskSupport.
• Check tool result semantics: content, structuredContent, isError, embedded resources, resource links, and the split between protocol errors and tool execution errors.
• Review safety hints conservatively: readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.
• Build the explicit upstream-mutation inventory for write-capable tools.

4. Audit prompts and resources if present.

• Prompts: capability declaration, prompts/list pagination, prompts/get, notifications/prompts/list_changed, argument handling, and prompt message content types.
• Resources: capability declaration, resources/list pagination, resources/read, resources/templates/list, resources/subscribe, notifications/resources/list_changed, notifications/resources/updated, URI scheme usage, MIME types, and text/blob encoding.
• Preserve the spec control hierarchy: prompts are user-controlled, resources are application-controlled, and tools are model-controlled.

5. Audit transports, auth, and security.

• stdio: newline-delimited JSON-RPC over stdin and stdout, no non-protocol stdout, stderr-only logging, and environment-based credential handling rather than HTTP OAuth flows.
• HTTP/Streamable HTTP: origin validation, localhost-binding guidance for local deployments, session and protocol-version handling, and HTTP-only auth flows when the server actually supports HTTP.
• Authorization: protected resource metadata discovery, WWW-Authenticate challenges, scope guidance, resource indicators, bearer-token handling, audience validation, and no query-string tokens.
• Security: input and URI validation, access controls, output sanitization, rate limits and timeouts, consent or sandbox expectations for local servers, and DNS-rebinding or SSRF risk surfaces.

6. Audit version and compatibility drift.

• Separate true spec violations from intentional older-version targeting or host-specific behavior.
• Check newer released-spec features that may be missing or mis-modeled, such as icons, tool name guidance, execution or task support, and structured tool output.
• Note draft-only or SEP-only expectations separately so the audit does not over-enforce unreleased behavior.
• Check repo-specific compatibility constraints such as tool-count limits, generated definitions, inspector or SDK quirks, and Warden rules.

7. Run validation.

• Prefer existing integration tests against the exported server surface.
• If none exist, add or update the narrowest automated check that proves the claimed protocol behavior.
• Refresh generated definitions or catalogs if the repo uses them.
• Finish with the repo's normal validation commands when appropriate.

8. Report the result.

• State the protocol baseline audited.
• List every primitive and capability the server implements.
• List every upstream-mutating tool.
• Separate confirmed violations, compatibility risks, and watchpoints.
• Call out what was validated via source inspection versus real server behavior.
• Note any assumptions about older spec targets, client quirks, or host-specific extensions.

Failure Handling

• If the repo targets an older MCP revision, audit against that version first and record the delta to latest separately.
• If framework adapters transform schemas or annotations, trust the exported wire surface over local declarations.
• If HTTP auth or transport behavior is owned by upstream infrastructure, audit the repo-owned boundary and explicitly mark the remainder as inherited or out of scope.
• If a requirement appears only in a draft or SEP, do not fail the server on it unless the user asked for draft compatibility.
• If a check passes structurally but the real server response differs, treat the wire behavior as authoritative.

MCP Audit Checklist

Use this checklist for repeatable MCP protocol and compatibility audits in any repository.

Baseline and scope

1. Identify the protocol revision being audited. 2. Default to the latest released MCP spec when the repo does not pin an older revision. 3. Identify which server primitives are implemented:

• prompts
• resources
• tools
• completions
• logging
• tasks or experimental extensions

4. Identify which transports are supported:

• stdio
• HTTP or Streamable HTTP
• hosted or reverse-proxied transport owned outside the repo

5. Separate released-spec requirements from draft-only or SEP-only watchpoints.

Lifecycle and capabilities

1. Verify initialize and notifications/initialized behavior. 2. Verify protocol-version negotiation and any required transport headers after initialization. 3. Verify the server advertises only capabilities it actually supports. 4. Verify capability sub-flags such as listChanged, subscribe, or task-related blocks are accurate. 5. Verify unsupported primitives are omitted rather than stubbed or falsely advertised.

Tools

1. Verify tools/list behavior, including pagination if the server can emit large tool sets. 2. Verify notifications/tools/list_changed only if the capability is claimed. 3. Verify exported tool definitions from the real server surface, not only source declarations. 4. Check tool metadata:

• name
• title
• description
• icons
• inputSchema
• outputSchema
• annotations
• execution.taskSupport

5. Check tool result behavior:

• content
• structuredContent
• isError
• resource links or embedded resources

6. Verify tool execution failures are distinguished from protocol-level JSON-RPC failures. 7. Build an explicit list of tools that mutate upstream state. 8. Classify each mutation:

• additive write
• destructive update

9. Treat orchestration tools conservatively based on the strongest child tool they can reach. 10. Treat conditional writes as mutating even if the write happens only on some code paths. 11. Verify safety hints:

• every tool defines readOnlyHint
• every tool defines openWorldHint
• every write-capable tool defines destructiveHint
• only truly repeatable no-extra-effect tools define idempotentHint
• read-only tools are never marked destructive

12. Verify structuredContent matches outputSchema when outputSchema is declared. 13. Verify tool naming rules against the targeted spec revision.

Prompts and resources

1. If prompts are implemented:

• verify prompts capability declaration
• verify prompts/list and pagination behavior
• verify prompts/get
• verify notifications/prompts/list_changed only if claimed
• verify prompt argument handling and prompt message content types

2. If resources are implemented:

• verify resources capability declaration
• verify resources/list and pagination behavior
• verify resources/read
• verify resources/templates/list if templates exist
• verify resources/subscribe and notifications/resources/updated only if claimed
• verify notifications/resources/list_changed only if claimed
• verify URI handling, MIME types, and text/blob encoding

3. Preserve the control hierarchy:

• prompts are user-controlled
• resources are application-controlled
• tools are model-controlled

Transport, auth, and security

1. For stdio:

• stdout is reserved for protocol messages
• logs and diagnostics stay on stderr
• credentials come from environment or local config, not HTTP auth redirects

2. For HTTP or Streamable HTTP:

• verify origin validation
• verify local deployments bind safely and do not expose a permissive local server by default
• verify session and protocol-version handling if the repo owns transport code

3. For authorization:

• verify protected resource metadata discovery
• verify WWW-Authenticate challenges include the right metadata or scope guidance
• verify resource indicators or audience binding where applicable
• verify bearer tokens are not accepted through query parameters

4. For security:

• validate external input and URIs
• check access controls and least-privilege defaults
• check output sanitization for tool or resource content
• check rate limits, timeouts, and SSRF or DNS-rebinding exposure where relevant

Version drift and compatibility

1. Check the latest released spec for newer fields or behaviors that the repo may have missed. 2. Record older-target behavior separately from actual violations. 3. Record draft-only watchpoints separately from released-spec violations. 4. Check repo or host compatibility constraints:

• tool count limits
• description-length limits
• generated definitions
• Inspector, SDK, or IDE quirks
• Warden or CI rules

Automation expectations

1. Prefer an existing repo-local integration test or metadata audit command if one exists. 2. If no focused audit exists, add or update the narrowest automated check that:

• captures the mutating-tool inventory when tool hints are involved
• validates claimed protocol metadata
• verifies exported wire behavior when frameworks can transform definitions

3. Refresh generated definitions or catalogs after metadata changes if the repo uses them. 4. Finish with the repo's normal validation commands when appropriate.

Reporting

1. State the audited protocol baseline. 2. List every primitive and capability the server implements. 3. List every upstream-mutating tool. 4. List every confirmed incompatibility with file references. 5. Separate released-spec violations, compatibility risks, and draft watchpoints. 6. State what was verified through source inspection versus the real server surface. 7. State whether generation and validation checks passed.

Common Findings

Use this reference to avoid overly narrow audits and to separate common MCP failure modes from true repo-specific edge cases.

Lifecycle and capability drift

1. The server claims a primitive or sub-capability that it does not actually implement. 2. listChanged is declared but no corresponding notification is ever emitted. 3. subscribe is declared for resources but subscriptions are not supported end to end. 4. The transport or framework exports different capability data than the local source definitions imply.

Tool definition and result problems

1. A mutating tool is marked readOnlyHint: true. 2. A networked or externally dependent tool is marked openWorldHint: false. 3. destructiveHint is missing on write-capable tools. 4. idempotentHint is applied to tools whose repeated calls have additional effect. 5. The exported tools/list metadata differs from the local source declaration. 6. outputSchema is declared but structuredContent is absent or does not match it. 7. Business-logic failures are surfaced as protocol errors instead of tool-call failures. 8. Tool names or titles drift from the targeted spec revision. 9. The server claims task support in tool metadata without the broader task flow it depends on.

Prompt and resource problems

1. Prompt or resource capabilities are claimed but their list or get or read methods are missing. 2. Pagination behavior is not implemented even though catalogs can grow materially. 3. Resource templates exist but are not exposed through template-listing APIs. 4. URI handling is ad hoc, ambiguous, or unsafe. 5. MIME type, text encoding, or blob handling is inconsistent with actual payloads.

Transport, auth, and security problems

1. A stdio server writes logs or banners to stdout. 2. A local HTTP server does not validate Origin headers. 3. Tokens are accepted through query parameters. 4. HTTP auth guidance is copied into a pure stdio server where it does not apply. 5. Protected-resource metadata or WWW-Authenticate guidance is incomplete for HTTP servers. 6. Local servers assume trusted clients without documenting consent or sandbox expectations. 7. Input, URI, or resource fetch paths create avoidable SSRF or DNS-rebinding exposure.

Compatibility and drift problems

1. The audit applies the latest spec to a repo that intentionally targets an older revision, but does not separate true violations from version delta. 2. Draft-only or SEP-only expectations are enforced as if they were released requirements. 3. Repo-specific compatibility constraints such as tool-count limits, generated definitions, or Warden rules are skipped because the audit stops at the protocol spec. 4. The audit checks local source declarations but never verifies what a real client sees through the exported MCP surface.

Spec Baseline

Use this reference to anchor mcp-audit on the current released MCP specification before applying repo-specific rules.

Released baseline

• Latest released MCP spec at retrieval time: 2025-11-25
• Audit default:
• Use the latest released spec when the repo does not pin an older revision.
• If the repo explicitly targets an older revision, audit against that revision first and report the delta to latest separately.
• Treat draft and SEP material as watchpoints unless the repo or user explicitly asks for draft compatibility.

Control hierarchy

The server primitives are not interchangeable. Preserve the intended control plane:

• Prompts are user-controlled.
• Resources are application-controlled.
• Tools are model-controlled.

If a server blurs those boundaries, call it out explicitly because it affects security and UX expectations.

Lifecycle and capabilities

Audit these first:

1. initialize request and response behavior 2. notifications/initialized 3. Negotiated protocol version 4. Claimed capabilities and sub-capabilities 5. Transport-specific post-init behavior when the repo owns transport details

Common failures:

• advertising listChanged or subscribe without the corresponding behavior
• claiming a primitive the server does not actually implement
• checking only local declarations while the framework exports different wire metadata

Tools baseline

The current released spec expects tool definitions to be treated as wire-visible protocol objects, not just internal metadata.

Check:

1. tools/list, including pagination when tool sets can grow 2. notifications/tools/list_changed when the server claims it 3. top-level metadata:

• name
• title
• description
• icons
• inputSchema
• outputSchema
• annotations
• execution.taskSupport

4. tool results:

• content
• structuredContent
• isError
• resource links or embedded resources when used

Important result rules:

• structuredContent should match outputSchema when outputSchema is declared.
• Business or execution failures should generally surface as tool-call results, while JSON-RPC errors are reserved for protocol-level failures.
• Safety hints are advisory to clients, so the exported wire value matters more than the source declaration if a framework rewrites it.

Prompts and resources baseline

If the server implements prompts, audit:

1. prompt capability declaration 2. prompts/list 3. prompts/get 4. pagination if the prompt catalog can grow 5. notifications/prompts/list_changed if claimed

If the server implements resources, audit:

1. resource capability declaration 2. resources/list 3. resources/read 4. resources/templates/list if templates exist 5. resources/subscribe and notifications/resources/updated if claimed 6. notifications/resources/list_changed if claimed 7. URI usage, MIME types, and text/blob encoding

Transport, auth, and security baseline

stdio

• Protocol messages stay on stdout.
• Logging and diagnostics stay on stderr.
• Authentication is typically environment- or local-config-driven, not OAuth redirect-driven.

HTTP and Streamable HTTP

• Validate Origin headers to reduce DNS-rebinding risk.
• Use safe binding defaults for local servers.
• Honor the released spec's version-negotiation and transport expectations when the repo owns them directly.

Authorization

When HTTP auth applies, check:

1. protected resource metadata discovery 2. WWW-Authenticate challenges 3. scope and resource-indicator behavior 4. bearer-token handling 5. audience binding where applicable 6. no query-string tokens

Security

Check:

1. input and URI validation 2. least-privilege access controls 3. output sanitization 4. SSRF and DNS-rebinding exposure 5. timeouts, limits, and abuse controls 6. consent and sandbox expectations for local servers

Released-version watchpoints

The latest released spec added or clarified several areas that older server implementations may miss:

• richer tool metadata such as icons
• tool execution metadata such as execution.taskSupport
• structured tool output expectations around outputSchema and structuredContent
• newer authorization discovery and challenge guidance
• updated tool naming guidance

Use references/version-watchpoints.md to keep these changes separate from draft-only expectations.

Version Watchpoints

Use this reference to keep released-spec requirements separate from newer or unreleased MCP changes.

Audit stance

1. Default enforcement target:

• the latest released MCP spec when the repo does not pin a version

2. If the repo pins an older released version:

• audit that version first
• report the delta to latest separately

3. If a behavior exists only in a draft or SEP:

• treat it as a watchpoint, not a release-blocking failure, unless the user or repo explicitly asks for draft compatibility

Released baseline at retrieval time

• Latest released spec: 2025-11-25

Key areas worth re-checking on older servers:

1. richer tool metadata such as icons 2. tool execution metadata such as execution.taskSupport 3. structured tool output expectations around outputSchema and structuredContent 4. updated authorization discovery and challenge guidance 5. newer tool naming guidance 6. experimental tasks support and adjacent task-related metadata

Prior released baseline likely to appear in older repos

• 2025-06-18

Key compatibility deltas from older implementations:

1. structured tool output became a first-class released concept 2. OAuth and protected-resource guidance became more explicit 3. protocol-version handling became more important for HTTP transports 4. JSON-RPC batching was removed from the released transport model

Draft watchpoints at retrieval time

The current draft stream includes changes that are useful to monitor but should not be enforced by default on a released-spec audit:

1. extensions fields in client or server capabilities 2. _meta trace-context conventions for OpenTelemetry propagation 3. host- or SDK-specific transport conventions not required by the released spec

Reporting rule

Always separate findings into:

1. confirmed violation of the targeted released spec 2. compatibility risk against the latest released spec 3. draft or SEP watchpoint

This prevents the audit from overstating unreleased behavior as a current protocol failure.

Sources

This file records the source material synthesized into mcp-audit.

Selected profile

• workflow-process
• Selected example profile: skill-writer/references/examples/workflow-process-skill.md

Current source inventory

Coverage matrix

Decisions

1. Keep the skill generic and portable; do not hardcode project-specific commands, paths, or mutation inventories into SKILL.md. 2. Expand the audit from tool hints alone to the full MCP surface the repo may expose: lifecycle, capabilities, tools, prompts, resources, transports, auth, security, and version drift. 3. Default to the latest released MCP spec when a repo does not pin an older version. 4. Treat draft and SEP content as watchpoints unless the repo explicitly opts into draft compatibility. 5. Prefer exported wire behavior over local declarations whenever frameworks can transform metadata before clients see it.

Open gaps

1. The security best-practices guide is not version-pinned, so re-check it when the MCP site updates its threat model guidance. 2. Prompt- and resource-specific released spec pages can be added on the next revision if this skill needs even deeper prompt or resource troubleshooting examples.

Stopping rationale

Additional retrieval would have been low-yield for this revision. The current source pack covers:

1. the latest released MCP wire contract 2. release and draft version drift 3. security and authorization guidance 4. repo-local compatibility rules 5. workflow-process authoring requirements

That was enough to rewrite mcp-audit into a broader protocol audit without inventing non-authoritative requirements.

Changelog

• 2026-04-21: Created mcp-audit as a generic workflow-process skill for MCP metadata and compatibility audits.
• 2026-04-21: Expanded the skill from a narrow hint audit into a broader released-spec protocol audit covering lifecycle, capabilities, tools, prompts, resources, transports, auth, security, and version drift.