MCP Server Capability Version Mapping Prompt

Use this prompt when you are an MCP server builder or platform engineer who needs to generate a machine-readable capability map from your server's internal tool implementations. The primary job-to-be-done is translating concrete tool versions—each with specific schemas, endpoints, and behaviors—into a structured capability advertisement that agents can consume during tool discovery. This is not a prompt for agents themselves; it is a build-time or registration-time prompt for the server side, ensuring that what your server claims matches what it actually implements.

The ideal user is a developer maintaining an MCP server that exposes multiple versions of the same tool or a family of related tools. You have access to your server's internal tool registry, version tags, schema definitions, and deprecation timelines. Required context includes: a list of implemented tools with their version identifiers, the capability schema your server advertises to agents, and any known gaps where a capability is claimed but not fully implemented or where a tool exists but is not yet advertised. Do not use this prompt when the tool inventory is unknown or when you are on the agent side trying to select a tool version—that is a separate runtime negotiation problem covered by the Agent Tool Version Negotiation Prompt Template.

The prompt is designed to catch capability gaps and misleading version claims before they reach production agents. It forces explicit mapping between what is implemented and what is advertised, flagging cases where a server claims a capability at a version that does not exist or where an implemented tool version is missing from the advertisement. After running this prompt, validate the output against your server's actual tool registry with a deterministic schema comparison. For high-risk production systems, add a human review step before publishing the capability map to agent-facing discovery endpoints. If your server has more than twenty tools, batch them by capability family to keep the mapping output manageable and auditable.

This prompt template is designed for MCP server builders who need to produce structured capability advertisements from their actual tool implementations. It forces the model to reconcile what the server claims to support with what the implementation actually provides, catching version mismatches, missing capabilities, and misleading advertisements before agents consume them. The template expects you to supply the server's tool manifest, implementation details, and any existing capability claims. It then produces a normalized mapping with gap analysis and confidence scores.

textCopy
You are an MCP server capability auditor. Your task is to produce a version-to-capability mapping that agents can trust.

## INPUTS
Server Tool Manifest (JSON): [TOOL_MANIFEST]
Implemented Tool Versions (JSON): [IMPLEMENTED_VERSIONS]
Current Capability Advertisements (JSON, optional): [CAPABILITY_ADS]
Server Version: [SERVER_VERSION]

## CONSTRAINTS
- Do not assume a capability exists unless you find explicit implementation evidence in [IMPLEMENTED_VERSIONS].
- Flag any capability advertised in [CAPABILITY_ADS] that has no matching implementation.
- Flag any implemented tool version that is not represented in [CAPABILITY_ADS].
- For each tool, note the minimum and maximum supported version.
- If a tool has breaking changes between versions, mark the version boundary.
- Use confidence scores: HIGH (direct implementation match), MEDIUM (inferred from partial evidence), LOW (speculative or contradictory).

## OUTPUT SCHEMA
Return a JSON object with this structure:
{
  "server_version": "string",
  "audit_timestamp": "ISO 8601",
  "capabilities": [
    {
      "tool_name": "string",
      "advertised_versions": ["string"],
      "implemented_versions": ["string"],
      "version_boundaries": [
        {
          "version": "string",
          "change_type": "BREAKING | NON_BREAKING | ADDITIVE",
          "description": "string"
        }
      ],
      "gap_type": "NONE | MISSING_IMPLEMENTATION | MISSING_ADVERTISEMENT | VERSION_MISMATCH",
      "gap_detail": "string or null",
      "confidence": "HIGH | MEDIUM | LOW",
      "recommended_agent_action": "USE_AS_ADVERTISED | PIN_VERSION | PROBE_FIRST | AVOID"
    }
  ],
  "summary": {
    "total_tools_advertised": 0,
    "total_tools_implemented": 0,
    "gaps_found": 0,
    "breaking_boundaries": 0,
    "overall_trust_score": "HIGH | MEDIUM | LOW"
  }
}

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

## INSTRUCTIONS
1. Parse [TOOL_MANIFEST] and [IMPLEMENTED_VERSIONS] completely.
2. Cross-reference every advertised capability against implementation evidence.
3. For each gap found, populate gap_type and gap_detail with specific, actionable information.
4. Assign confidence scores conservatively. Prefer LOW over MEDIUM when evidence is ambiguous.
5. If [CAPABILITY_ADS] is empty or missing, treat all implemented tools as unadvertised gaps.
6. If [RISK_LEVEL] is HIGH, add a "human_review_required": true field to any capability with LOW confidence or BREAKING boundaries.

To adapt this template, start by replacing [TOOL_MANIFEST] with the actual JSON output from your MCP server's tools/list endpoint. [IMPLEMENTED_VERSIONS] should come from your build system, package registry, or runtime introspection—not from documentation. If you don't have existing capability advertisements, leave [CAPABILITY_ADS] as an empty array and the prompt will treat every implemented tool as a gap that needs advertisement generation. For [EXAMPLES], include 2-3 representative tool mappings showing correct gap detection, especially cases where an advertised version has no implementation or where a breaking change boundary exists. Set [RISK_LEVEL] to HIGH if agents in production depend on these capability mappings for tool selection decisions; this triggers the human-review flag on low-confidence or breaking-change entries.

Before shipping this prompt into a production pipeline, validate the output against a golden set of known capability mappings. Common failure modes include: the model accepting documentation claims as implementation evidence (mitigate by requiring explicit code-path or endpoint evidence in [IMPLEMENTED_VERSIONS]), missing breaking change boundaries when version numbers use non-standard formats (add version normalization rules to [CONSTRAINTS] if needed), and overconfident MEDIUM scores when implementation evidence is partial (tighten the confidence criteria in the prompt or add a post-processing validator that downgrades MEDIUM to LOW when gap_detail contains hedging language). Wire the output through a schema validator before any agent consumes it, and log every audit result with the server version and timestamp for traceability.

This prompt is designed to run inside an MCP server's capability advertisement pipeline or an agent gateway's tool discovery layer. It is not a one-off chat prompt. The primary integration point is a server-side registration hook that fires when a server starts, when its tool set changes, or when an agent requests a capability refresh. The prompt consumes the server's internal tool manifest (name, version, input/output schemas, and deprecation flags) and produces a structured capability map that agents can consume. Wire it so that the output is cached in the server's capabilities response and re-generated only when the underlying tool manifest changes, not on every agent request.

Validation and retry logic is critical here because a malformed capability map will silently break every downstream agent that relies on it. After the model returns the capability map, run a schema validator that checks: (1) every declared tool has a non-empty name, version, and capabilities array; (2) no capability string appears under two different tools unless it is intentionally shared; (3) every version string matches a recognized pattern (semver or the server's internal convention); and (4) deprecated tools are explicitly marked with a deprecated boolean and an optional sunset_date. If validation fails, retry once with the validation errors injected into the [CONSTRAINTS] block. If the second attempt also fails, log the raw model output and the validation errors, then fall back to the last known good capability map. Never serve an unvalidated capability map to agents.

Model choice and latency matter because this prompt runs in a cold-start or refresh path, not on the hot path of every tool call. Use a fast, instruction-following model (GPT-4o-mini, Claude 3.5 Haiku, or equivalent) rather than a large reasoning model. The task is structured extraction and mapping, not deep reasoning. Set temperature=0 to maximize output stability across regenerations. If your MCP server supports streaming capability updates, consider running this prompt asynchronously on a background thread so that server startup is not blocked. Cache the validated output with a TTL that matches your tool manifest change frequency—typically hours or days, not seconds.

Observability and audit are non-negotiable. Log every invocation of this prompt with: the input manifest hash, the model used, the raw output, the validation result (pass/fail), and the final capability map served to agents. This trace is essential for debugging agent failures that trace back to incorrect capability advertisements. If your platform supports it, attach the capability map version to every agent tool call log so that operators can correlate agent behavior with the exact capability snapshot the agent received. For high-assurance deployments, consider running a second, independent validation prompt that checks the capability map for internal consistency and flags gaps—such as a tool that claims a capability but whose schema lacks the required fields to fulfill it.

When not to use this prompt: Do not run it on every agent tool invocation. It is a registration-time prompt, not a runtime prompt. Do not use it if your MCP server has a static, hand-authored capability map that is already correct—this prompt adds value when tool manifests are dynamic or versioned. Do not skip the validation step; raw model output in this path is a single point of failure for every agent that depends on the server. If your server supports multiple simultaneous tool versions, ensure the prompt's [TOOLS] input includes all active versions, not just the latest, so that the capability map accurately reflects what agents can call.