MCP Capability Negotiation Tests Across Protocol Versions

MCP compatibility is established during a connection, not inferred from package names or a successful socket open. The client proposes a protocol version and its capabilities, the server responds with a selected version and its capabilities, and both peers must restrict normal operation to the negotiated contract.

Test that lifecycle as a state machine across every supported client-server pair. Validate message order, version decisions, capability shapes, legal feature use, reconnect behavior, timeouts, and shutdown. A happy-path tool call alone cannot prove compatibility.

Model the Protocol Lifecycle Explicitly

The versioned MCP lifecycle specification divides a connection into initialization, operation, and shutdown. It requires initialization to be the first interaction, describes version and capability exchange, and places normal feature traffic after the client's initialized notification.

Implement the test oracle as states such as connected, initialize_sent, initialize_accepted, operational, closing, and closed. Record every inbound and outbound JSON-RPC message, transport event, selected version, capability set, and timer decision. This makes an ordering failure distinguishable from a feature failure.

Build a Client-Server-Transport Matrix

List every client and server release inside the support window, then cross them with transport and required feature profile. A server used only for tools has a different acceptance contract from one requiring resource subscriptions. Include deployment configuration because proxies, headers, and process management can alter lifecycle behavior.

Give each matrix cell an expected result: fully supported, supported with reduced features, intentionally unsupported, or experimental. Do not convert an expected incompatibility into a test failure if the peer rejects it cleanly and diagnostically. Do fail any pair that enters operation under an unsupported interpretation.

Keep implementation version separate from protocol version. Two application releases can implement the same protocol contract differently, and one application can support several protocol versions. The matrix should record both identities.

Validate Initialize Ordering and Message Shape

Test a valid initialize request, missing required fields, wrong JSON-RPC version, duplicate request IDs, malformed capability objects, unknown metadata, and an initialize request sent twice. Before the response, attempt a normal feature request and verify the peer follows the lifecycle rules rather than processing it opportunistically.

After a successful response, send notifications/initialized and confirm operation begins. Also omit the notification, duplicate it, close before sending it, and send server-initiated feature traffic too early. The expected behavior should come from the protocol version under test, not a generic JSON-RPC assumption.

A fixture should preserve the entire transcript:

{
  "caseId": "tools-no-list-change",
  "clientProtocol": "2025-11-25",
  "clientCapabilities": {"roots": {"listChanged": true}},
  "serverProtocol": "2025-11-25",
  "serverCapabilities": {"tools": {"listChanged": false}},
  "requiredFeatures": ["tools/list", "tools/call"],
  "forbiddenEvents": ["notifications/tools/list_changed"]
}

This is a version-specific test fixture, not a claim that every MCP connection uses that protocol version.

Test Version Selection and Rejection

For each client proposal, configure servers that accept the proposed version, select a different supported version, return an unsupported version, return malformed version text, or fail initialization explicitly. Verify that both sides agree on one contract before operation.

When HTTP is in scope, test the protocol-version header behavior required by the selected specification on subsequent requests. Include missing, stale, and conflicting header values. For stdio, test process exit during negotiation and ensure the client reports initialization failure rather than a mysterious tool outage.

Do not implement silent downgrade by parsing whichever messages happen to work. A reduced version can omit or reinterpret features. The client must know that the selected version is supported and then use the corresponding schemas and lifecycle rules.

Derive and Enforce the Capability Intersection

Capabilities are directional. Client capabilities describe features the server may request from the client; server capabilities describe services the client may use. Build a session object from the negotiated declarations and route every feature through it.

type ServerCaps = {
  tools?: { listChanged?: boolean };
  resources?: { subscribe?: boolean; listChanged?: boolean };
};

export function sessionFeatures(caps: ServerCaps) {
  return {
    canCallTools: caps.tools !== undefined,
    canReceiveToolListChanges: caps.tools?.listChanged === true,
    canSubscribeResources: caps.resources?.subscribe === true
  };
}

Test absent capability, empty capability object, explicit false sub-capability, and unknown extension keys. Verify that a false or missing listChanged does not register notification handlers as though updates were promised. Conversely, when a feature is declared, test its actual behavior.

Probe Positive and Negative Feature Behavior

For every negotiated feature, run a minimal valid request, boundary inputs, malformed input, cancellation, concurrency, and an implementation error. For every unnegotiated feature, attempt use from the relevant peer and assert a controlled protocol outcome with no unintended side effect.

Tool capability tests should cover listing, pagination where applicable, calling with schema-valid and invalid arguments, structured errors, and list-change notifications only when advertised. Resource tests should distinguish listing from subscription support. Do not infer one sub-capability from another.

The MCP Inspector guide describes interactive connection, resource, prompt, tool, and notification views and recommends checking capability negotiation during development. Use it to inspect transcripts and reproduce cases, while keeping the release matrix automated and deterministic.

Exercise Notifications and Dynamic Changes

Capability negotiation establishes what notifications may occur, but dynamic lists still need lifecycle tests. Change the server's tool or resource inventory, verify notification eligibility, refetch behavior, pagination consistency, and client cache replacement. Send duplicate and burst notifications to expose races.

Test a notification arriving during an in-flight call, after transport close begins, and immediately after initialization. A client should not apply an event from an old connection to a new session. Tag observations with connection identity and clear negotiated state on disconnect.

If a server changes capabilities that require renegotiation, establish a new lifecycle rather than mutating the original initialize result in place. Tests should catch clients that retain tools from a prior session when the reconnect advertises fewer capabilities.

Test Reconnect, Timeout, and Shutdown

Drop the transport during initialize, immediately after initialized, during a feature request, and while notifications are queued. Reconnect must perform initialization again and must not assume the previous version or capabilities. Pending requests need explicit failure or recovery behavior.

Test request deadlines, cancellation, late responses, and continuous progress that would otherwise keep a request alive indefinitely. Any numeric timeout in the suite is an illustrative environment policy unless it comes from a product contract. The assertion is bounded, diagnosable behavior and resource cleanup.

For stdio, verify stream closure and child-process cleanup. For HTTP, verify connection and session cleanup according to the selected transport contract. After shutdown begins, reject new work and ignore or classify late messages without resurrecting the session.

Report Compatibility as Evidence, Not a Boolean

For each matrix cell, report negotiated version, initialize result, capability intersection, feature probe outcomes, invalid-order outcomes, reconnect result, timeout result, shutdown result, and transcript location. A single compatible: true hides reduced capability and lifecycle gaps.

Separate protocol conformance from product support. A pair may negotiate correctly but lack a feature the product requires; that cell is protocol-compatible and product-ineligible. Conversely, a connection that happens to complete one tool call while violating initialization order is not conformant.

Define release gates from required profiles. An illustrative policy might require all supported pairs to complete lifecycle tests, all required capabilities to pass positive probes, and all unadvertised mutation probes to cause zero side effects. Mark tolerance for flaky infrastructure separately from protocol behavior.

Negotiation Checklist

• Enumerate supported client, server, protocol, transport, and feature profiles.
• Treat implementation and protocol versions as separate identities.
• Assert initialize is first and normal traffic waits for lifecycle completion.
• Test accepted, alternate, unsupported, and malformed version responses.
• Derive directional capabilities into one connection-scoped session object.
• Probe every declared feature and reject every unnegotiated feature path.
• Exercise sub-capabilities, pagination, notifications, and dynamic lists.
• Reinitialize after every reconnect and clear stale negotiated state.
• Inject timeouts, late responses, cancellation, and transport loss.
• Preserve transcripts and report capability-level compatibility.

Action Plan: Turn the Support Table Into Executable Tests

Start with the oldest and newest supported client and server releases, one transport, and one required profile. Encode initialize transcripts and state transitions, then add version alternatives plus capability-present, capability-absent, and sub-capability-false cases. Run positive and negative probes only after the session reaches operation.

Expand the matrix across transports and intermediate releases, add reconnect and shutdown faults, and reproduce discrepancies with Inspector. Publish capability-level results beside the support policy. A pair earns release support only when it negotiates a known protocol, uses no unadvertised feature, and can end or rebuild the connection without carrying stale state forward.