Keep assistants connected across protocol revisions
Assistants do not all update together. Wildo’s MCP endpoint selects transport behavior for the revision used by each request, allowing supported clients to share the same application endpoint.
Compatibility belongs to the transport, while your resource operations keep their application contracts.
Example — Upgrade one assistant at a time
An existing client can continue using its supported handshake flow while a newer integration uses the other transport path implemented by the server.
For engineers
Configure the application endpoint and the token audience in your MCP client. Its negotiated revision determines the required request metadata and response envelope; do not add one newest-version header policy to every caller.
The current implementation names its served revisions in MCP_SUPPORTED_PROTOCOL_VERSIONS:
export const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = [
'2026-07-28',
'2025-11-25',
'2025-06-18',
'2025-03-26',
];
This is the local implementation’s supported set, not a claim about future versions or independently certified conformance.
Follow the negotiated handshake path
For the locally supported 2025-06-18 path, send this body to the MCP endpoint with Content-Type: application/json and Accept: application/json. Initialization is public; tool discovery and calls still need the caller’s token.
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": { "name": "integration-example", "version": "1.0.0" }
}
}
For that supported request, the controller returns:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-06-18",
"capabilities": { "tools": { "listChanged": false } },
"serverInfo": { "name": "wildo-mcp", "version": "1.0.0" }
}
}
Check the returned revision, then send {"jsonrpc":"2.0","method":"notifications/initialized"} without an ID. The endpoint accepts this notification with HTTP 202 and no response body. Subsequent requests carry MCP-Protocol-Version: 2025-06-18; authenticated discovery adds the audience-bound Bearer token. A supported requested revision is echoed; an unsupported request can receive another served revision, which the client must check before continuing.
Declare the stateless revision on each request
The local 2026-07-28 path uses per-request metadata instead. After discovering support with server/discover, this example asks for the caller’s tools. Replace the address and token with the chosen endpoint and its credential:
POST /api/v1/mcp HTTP/1.1
Host: application.example.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer <endpoint-access-token>
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}
The header revision mirrors the body metadata, and Mcp-Method mirrors the method. For tools/call, also send Mcp-Name matching the discovered params.name. Mismatches are rejected before dispatch. Stateless success results carry resultType: "complete"; tools/list also carries cache hints appropriate to its caller-specific catalogue. Those fields do not belong to the older handshake example above.
An anonymous tools/list request is challenged rather than receiving the authenticated catalogue. Public transport discovery does not authorize tool use. These exchanges describe the local controller’s served paths, not an independent protocol-conformance result.
Keep version selection distinct from authorization
The controller separates a declared revision from the default used to interpret an undeclared request. Handshake negotiation chooses a compatible handshake-era response. Its stateless path validates per-request revision and method metadata.
| Concern | Application integration consequence |
|---|---|
| Revision discovery | Learn the supported transport before constructing calls |
| Tool catalogue | Treat it as caller-specific information, not a public cache entry |
| Token authentication | Obtain authority for the MCP resource separately from negotiation |
Browser Origin header | Direct browser-origin requests are refused by this endpoint |
Use an MCP client to manage these details instead of reproducing the transport in product code. The server is a tools surface; protocol compatibility does not imply support for every optional MCP feature.