MCP Capability Negotiation: Versions, Features, and Initialization

Capability negotiation is the part of MCP initialization where a client and server agree on the protocol version and optional features they can use together. It prevents one side from assuming that the other side supports a feature it never advertised.

Version agreement comes first

The client begins by sending an initialize request with a protocol version it supports. The server responds with the version that will govern the session. If the two sides cannot agree, the session should not proceed to normal operations.

Capabilities describe optional features

Capabilities are grouped by client and server responsibilities. A server can advertise tools, resources, prompts, logging, completions, or other supported features. A client can advertise support for roots, sampling, elicitation, tasks, or other features. Optional sub-capabilities can describe things such as list-change notifications or resource subscriptions.

Negotiated does not mean universal

The server may implement a feature in its codebase but still need to advertise it for the client to use it. After initialization, both sides must respect the negotiated set. A client should not send a request for an unadvertised capability, and a server should not emit feature-specific notifications without declaring the relevant support.

Diagnosing negotiation problems

• Capture the client and server protocol versions without guessing from a product name.
• Compare the advertised capability object with the method or notification that failed.
• Check whether the issue is version mismatch, missing capability, invalid parameters, or a server runtime error.
• Test more than one client when the server behaves differently across hosts.

Operational telemetry for compatibility

Version and capability dimensions can have high diagnostic value, but they should remain bounded and low-cardinality. A server team can use them to find clients that still use an older transport or a feature set that the current release no longer exercises. They should not collect raw message bodies when a small set of validated fields answers the question.