Last reviewed: 2026-08-10

Direct answer

Treat every MCP tool catalog as a versioned contract, not as harmless setup metadata. Before a coding agent can act, initialize the server, retrieve every page of tools/list, and save a normalized snapshot of the server identity, tool names, descriptions, input schemas, output schemas, annotations, and execution metadata. Compute a digest for that snapshot and compare it with a baseline that a named owner approved. If the baseline is missing, the digest changes, or a changed field crosses your risk threshold, keep the affected tools disabled and request a human decision. Only expose the approved contract to the model call routed through CometAPI.

This approach follows the structure of the Model Context Protocol tools specification , which defines tool discovery, schemas, annotations, capability negotiation, and the notifications/tools/list_changed event. It also keeps two control planes separate: CometAPI selects and serves the model request, while your MCP gateway decides which external actions that model is allowed to see. A fresh model catalog does not make a changed tool safe, and a stable tool catalog does not make an unavailable model usable.

Use this operator workflow:

  1. Discover. Start the pinned MCP server build, complete its handshake, and fetch tools/list until there is no next cursor. Record the server identifier and the configuration revision used to start it.
  2. Normalize. Remove presentation-only noise only when your policy says it is non-semantic. Sort object keys, preserve array order where order matters, make omitted-versus-explicit defaults visible, and retain the exact JSON Schema and annotations in the stored snapshot. Never normalize away a required property or a permission boundary.
  3. Compare. Diff the new snapshot against the approved baseline. Classify additions, removals, renamed tools, required-property changes, output-schema changes, annotation changes, and server command or URL changes separately.
  4. Decide. Automatically allow an unchanged digest. Route low-risk documentation-only edits to review, and block unknown tools, widened inputs, changed side-effect metadata, or a new server identity until an owner approves them.
  5. Apply. Keep the previous approved snapshot active while the new one is under review. After approval, replace the baseline atomically and reset any per-tool approval that no longer matches the new definition.
  6. Observe. Repeat the fetch after a declared list_changed notification and at the beginning of each run. Keep the decision and the snapshot digest beside the CometAPI request metadata.

The happy path is simple. A server called repo-tools starts at the expected configuration revision, returns the same complete list, and produces the same digest as its baseline. The gateway records decision=allow, makes only the approved tools available, and still asks for confirmation before a sensitive invocation. The error path is equally explicit: a previously read-only search_issues tool gains a new required repository field, or an apply_patch schema adds a broad file selector. The gateway records a high-severity diff, leaves the old baseline untouched, returns a clear “tool contract changed” status to the agent, and waits for a reviewer. A model can then explain the pause instead of guessing at the new contract.

Who this is for

This guide is for platform engineers, repository maintainers, and security reviewers who run coding agents with MCP servers and route model traffic through CometAPI. It is useful when servers are installed from a registry, checked into a repository, launched locally, or shared by several agent surfaces. It is not a replacement for MCP authorization or a full threat model. It is a control for detecting unexpected changes before a model turns a changed definition into an external action.

If your team already writes a tool manifest, this adds a runtime freshness check and an approval record. If you are starting from zero, begin with one low-risk server and make the decision visible before expanding access.

Key takeaways

  • Snapshot the complete tool contract, including schemas and annotations, rather than hashing only tool names.
  • Fetch all pages of a paginated list; a partial snapshot can produce a false “unchanged” result.
  • Treat a digest as a change detector, not as proof that the new server is trustworthy.
  • Block new, removed, renamed, or side-effect-changing tools until an owner reviews the diff.
  • Revoke or reset prior approvals when the server definition or tool list changes.
  • Keep model selection and tool authorization independent. Refresh the CometAPI model catalog separately and match the selected model to the request capability.
  • Log identifiers, classifications, and outcomes, never prompts, tool arguments, or credentials by default.

Sources checked

The MCP tools specification is the protocol reference for tools/list, pagination, listChanged, JSON Schema fields, output validation, and the recommendation to keep a human able to deny invocations. The MCP security best-practices guide describes confused-deputy, prompt-injection, SSRF, session, local-server, and scope risks, along with mitigations such as per-client consent and exact redirect validation.

The GitHub Copilot MCP guide documents connecting MCP servers to a coding assistant, configuring servers on supported surfaces, discovering tools, and using permissioned tool access. Microsoft Learn’s MCP server guide describes server configuration locations, handshake and tool-list discovery, list_changed subscriptions, trust prompts for changed definitions, and confirmation controls. These implementation details show why a baseline belongs at the client or gateway boundary, not only in a prose README.

For the broader risk context, consult OWASP’s Agentic AI - Threats and Mitigations , a threat-model-based reference for emerging autonomous-system risks. For the model side of the bridge, the CometAPI model catalog guide recommends querying the catalog, checking capabilities and pricing, and refreshing it at deployment or startup so stale model identifiers do not silently enter a run.

Contract details to verify

Server identity and launch configuration. Give each server a stable internal identifier and record the source revision, transport, executable or remote endpoint identity, and configuration digest. A configuration change can replace the process that supplies the tools even when the tool names look familiar. Microsoft documents repository, solution, user, and editor configuration locations and explains that an edited definition can restart the server and trigger a fresh query. Decide which locations are allowed for production and make the selected location part of the baseline.

The full tool definition. The MCP specification describes a tool with a name, optional title and description, an input schema, an optional output schema, annotations, and optional execution properties. Include all of those in the snapshot. Validate that input and output schemas are valid JSON Schema objects before diffing them. Keep names case-sensitive and preserve the distinction between a missing field and an explicit value. Treat a description change as relevant to model selection even when the executable behavior is unchanged.

A deterministic diff policy. Canonicalize JSON for comparison, then assign a severity to each field change. A removed tool, a new tool, a renamed tool, a newly required argument, a widened path or query scope, or a change to side-effect or task-execution metadata should default to block. An output-schema change should at least fail contract tests before it reaches an agent. A description, title, or icon change can enter a review queue if the server is otherwise pinned. Record the old and new values in a restricted review artifact, but expose only the classification and digest to routine logs.

Notifications and approvals. A server may advertise listChanged; when it does, subscribe and refetch rather than trusting the notification payload. Microsoft describes resetting prior tool acceptances when that event fires and prompting again when a server’s configuration or capabilities change. Implement the same invariant even on clients that do not provide a visual trust dialog: an approval belongs to a specific server identity and exact tool definition, not merely to a tool name. Keep an explicit expiry or reapproval rule for long-lived baselines.

Human confirmation at the action boundary. Discovery approval is not execution approval. The MCP specification recommends clear indicators and confirmation for invocations, especially sensitive operations. Keep write, deployment, credential-management, and data-export tools behind a second confirmation or a narrower policy. A schema diff can tell you that a tool changed; it cannot decide whether the requested operation is appropriate for the current repository.

CometAPI model freshness. Treat model routing as a parallel contract. Query the public catalog during startup or deployment, select an identifier whose capability matches the request, and store the chosen model ID with the run. The CometAPI guide distinguishes the public catalog from the authenticated OpenAI-compatible model-list shape and warns against reusing stale IDs. Do not “fix” an MCP drift block by silently switching models. After any deliberate model change, rerun representative tool-call contract tests rather than assuming identical behavior.

Sanitized evidence. A useful record lets an operator reproduce the decision without copying user content. For example:

{
  "run_id": "run-2026-08-10-041",
  "server_id": "repo-tools",
  "server_revision": "rev-42",
  "baseline_id": "mcp-baseline-2026-08",
  "previous_snapshot_sha256": "sha256:old-digest",
  "snapshot_sha256": "sha256:new-digest",
  "diff_kind": "required-input-added",
  "severity": "high",
  "decision": "block",
  "model_id": "coding-model-id",
  "route": "cometapi",
  "request_id": "request-041",
  "status": "awaiting-review",
  "latency_ms": 184,
  "observed_at": "2026-08-10T00:00:00Z"
}

Do not place prompts, file contents, tool arguments, access headers, or credential material in this record. If an incident requires payload inspection, put a separately access-controlled artifact behind a retention policy and reference it by an opaque case ID.

Failure modes

  1. Only the first page is compared. A server adds a tool on page two, but the gateway reports “unchanged.” Always follow the cursor until the complete list is collected and store the page count.
  2. The notification is treated as the diff. list_changed is a signal, not an authenticated replacement catalog. Refetch, validate, and compare the result; if refetch fails, keep tools disabled.
  3. A schema is widened quietly. Changing an optional path filter to accept arbitrary paths can expand impact without changing the tool name. Compare property types, required arrays, enum values, defaults, and additional-property rules.
  4. Annotations are trusted because they look official. The specification says clients must treat annotations as untrusted unless they come from trusted servers. Use an allowlisted server identity and independent policy classification; never let a new annotation grant authority by itself.
  5. The baseline is overwritten on startup. An attacker who changes the server before startup can make the first snapshot look legitimate. Store the approved baseline outside the mutable server directory, require an owner and revision, and alert when no baseline exists.
  6. A configuration change escapes the tool diff. A new command, URL, package version, or environment setting can point the same catalog at a different implementation. Include launch metadata in the identity digest and review it with the tool diff.
  7. A proxy confuses consent. The MCP security guide calls out confused-deputy conditions around static client IDs, dynamic registration, cookies, and redirects. Keep per-client consent, validate exact redirect values, and reject a changed authorization state before enabling a remote server.
  8. The model catalog is stale. A removed or incompatible CometAPI model ID can look like an MCP failure. Refresh the catalog, verify capability, and classify model errors separately from tool-contract errors.
  9. Logs become a second leak. Full arguments and result text can contain source code or credentials. Default to the sanitized fields above, redact at collection time, and make payload capture an explicit incident action.
  10. A blocked run loops forever. Returning the same generic error encourages repeated retries. Return the diff class, baseline identifier, and next human action, then stop automatic retries until the decision changes.

FAQ

Is a snapshot hash enough? No. It detects that bytes changed, but it does not establish who changed them or whether the new contract is safe. Pair the digest with a pinned server revision, an owner, a diff, and an approval record.

Should every documentation edit stop production? Not necessarily. Define a policy that can route title or description-only changes to review while blocking new tools, removed tools, schema widening, and side-effect changes. Keep the classification visible so a later incident can explain why a change was allowed.

Why do this if CometAPI only provides the model? Model routing and tool authorization are different trust decisions. CometAPI can make model selection and request delivery consistent, while your gateway still controls which MCP definitions enter the model context and which calls reach external systems.

What if the server does not advertise listChanged? Fetch and compare at startup and at a cadence suitable for the run. Absence of a notification capability is not evidence that the catalog is immutable.

Can I reuse an approval after changing the model? Treat it as a new run decision. A different model may interpret descriptions, schemas, or optional fields differently. Confirm the model’s current catalog entry and rerun a representative tool-call contract test.

Where should I start? Pick one read-only server, capture a baseline, simulate a required-field change, and verify that the gateway blocks it without exposing payloads. Then add write tools one class at a time.

Reader next step

Choose one MCP server used by your coding agents today. Pin its launch revision, capture every tool page, normalize the definition, and have an owner approve the resulting digest. Trigger a controlled schema change and confirm that the happy path still reaches the model while the error path stops before invocation. For the surrounding setup, read Declare MCP Tool Manifests Before Coding Agents Call CometAPI and Test Coding Agent Tool Calls Before Switching Models Through CometAPI . When the contract gate is in place, Start with CometAPI with a model whose capability you have just verified.