MCP Server Specification: [Server name]

Specification for a Model Context Protocol (MCP) server: what it exposes to AI applications (tools, resources, prompts), over which transport, with which authorization, and how it is secured, tested and versioned. Written against MCP specification revision 2026-07-28 (the latest revision on modelcontextprotocol.io when this template was written; previous revision 2025-11-25). Check the current revision before you start. Replace every [bracketed] value and every row marked Example.

1. Purpose and context

[Describe the system the server wraps and who will connect to it.] Example: Exposes read access to invoices and a limited credit operation from the billing service, for use by the internal support assistant and by engineers in their IDE assistants. It does not expose payment card data, refunds or account deletion.

2. Transport and protocol

Transport requirements to verify:

• stdio: newline-delimited JSON-RPC on stdin and stdout; logs go to stderr only; credentials come from the environment, not from MCP authorization.
• Streamable HTTP: validate the Origin header on every request and answer 403 when it is present and invalid (DNS rebinding protection); bind to 127.0.0.1 when running locally; require the MCP-Protocol-Version, Mcp-Method and (for tools/call, resources/read, prompts/get) Mcp-Name headers and reject header-body mismatches with 400.
• Statelessness: no per-connection state. Where a tool needs state across calls, return an explicit opaque handle and accept it as an argument, checking authorization on every call.

3. Capabilities

4. Tools

Defaults in the schema, if a hint is omitted: readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true. Set every hint explicitly so clients do not assume the worst or the best.

4.1 Tool definition: apply_credit

{
  "name": "apply_credit",
  "title": "Apply account credit",
  "description": "Add a credit in USD to a customer account. Use only after confirming the charge is a duplicate or caused by an outage. Maximum 50 USD. Creates a ledger entry that finance can reverse within 30 days.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "account_id": {"type": "string", "pattern": "^acc_[a-z0-9]{12}$"},
      "amount_usd": {"type": "number", "minimum": 0.01, "maximum": 50},
      "reason_code": {"type": "string", "enum": ["DUPLICATE_CHARGE", "SERVICE_OUTAGE"]}
    },
    "required": ["account_id", "amount_usd", "reason_code"],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "properties": {"credit_id": {"type": "string"}, "balance_usd": {"type": "number"}},
    "required": ["credit_id", "balance_usd"]
  },
  "annotations": {"readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false}
}

Results with an outputSchema return structuredContent that conforms to it, plus the same JSON serialised in a text content block for older clients.

5. Resources and prompts

5.1 Resources

List and read results carry ttlMs and cacheScope; use private for anything user-specific.

5.2 Prompts

6. Authorization

7. Security considerations

8. Error handling

9. Logging and observability

[Example: Structured logs to stderr (stdio) or the platform log pipeline (HTTP) with request ID, method, tool name, user ID, latency and outcome. Arguments are logged with account IDs hashed. Trace context propagated through _meta (traceparent) into OpenTelemetry. Audit log of every apply_credit call kept for [7] years.]

10. Versioning and compatibility

• Server version follows semantic versioning; a breaking change to any tool's input schema or behaviour is a major version.
• Tools are added rather than changed; deprecated tools keep working for [90] days and say so in their description.
• Supported MCP revisions: [2026-07-28]; [2025-11-25 via fallback].
• listChanged notifications are sent when the tool set changes at runtime.

11. Testing

Standard and licence note

Based on the Model Context Protocol specification, revision 2026-07-28, published at modelcontextprotocol.io; structure and requirement names summarised in original wording. Check the specification for the current revision and normative text. Template licence: MIT.