Capabilities Negotiation

Establishing a connection between an MCP client and server requires more than just a transport layer. Because the protocol allows for independent evolution of clients (like an IDE or an AI desktop app) and servers (like a database connector), the two parties often possess different feature sets. One server might support active resource subscriptions, while another only supports static reads. One client might allow the server to request sampling (generating content via the LLM), while another might restrict this for security reasons.

To manage this variance, the protocol mandates a strict initialization phase. This phase serves as a contract negotiation where both parties declare their functionality. Until this handshake completes, no functional requests, such as listing tools or reading resources, can occur.

The Initialization Sequence

The lifecycle of an MCP connection begins immediately after the transport link (Stdio or SSE) is established. The handshake consists of a synchronous request-response pair followed by a notification. This strictly ordered sequence ensures that the configuration is locked in before the application logic begins.

1. Request: The client sends an initialize request containing its protocol version and its capabilities.
2. Response: The server replies with its protocol version and its own capabilities.
3. Notification: The client sends a notifications/initialized message to signal that it has accepted the server's response and is ready to operate.

If any step in this sequence fails or if the protocol versions are incompatible, the connection terminates.

The three-step initialization sequence required to establish an active MCP session.

Declaring Capabilities

The capabilities property within the initialization payload is the central mechanism for feature discovery. It is a JSON object where keys represent standardized features. The presence of a key implies support for that feature. If a key is missing, the other party must assume the feature is unavailable and disable the corresponding logic.

Client Capabilities

When a client initiates a connection, it declares what it can handle. This prevents the server from sending notifications or requests that the client cannot process. Common client capabilities include:

• sampling: Indicates the client allows the server to request LLM completions (using the client's inference provider) via sampling/createMessage.
• roots: Indicates the client can provide filesystem roots to the server, useful for servers that need to know which directories they are allowed to access.
• experimental: A reserved bucket for non-standard features that are being tested.

Server Capabilities

The server's response dictates the API surface area available to the LLM. Standard server capabilities include:

• logging: Signals that the server emits log messages that the client should capture and display.
• prompts: Indicates the server provides prompt templates (e.g., prompts/list).
• resources: Indicates the server exposes data resources. This object can further specify if subscribe (active updates) is supported.
• tools: Indicates the server exposes executable functions (e.g., tools/call).

Capability Data Structure

The structure of the capabilities object is hierarchical. A simple boolean is rarely sufficient because specific features often have their own sub-configurations.

Consider this example of a JSON-RPC payload sent by a server during the handshake:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "tools": {},
      "logging": {}
    },
    "serverInfo": {
      "name": "sqlite-explorer",
      "version": "1.0.2"
    }
  }
}

In this response, the server explicitly declares support for Resources, Tools, and Logging. Note that prompts is absent. The client must logically infer that this server offers no prompt templates. Furthermore, inside the resources capability, the server sets "subscribe": true. This informs the client that it is valid to send resources/subscribe requests. If this flag were false or missing, the client would treat the resources as static.

Version Negotiation

The MCP specification evolves over time. To maintain stability, the initialization request includes a version negotiation mechanism.

1. The client sends its supported version in the protocolVersion field (e.g., "2024-11-05").
2. The server compares this against its own implementation.
3. The server responds with the negotiated version.

Mathematically, if $V_c$ is the client's version and $V_s$ is the server's max supported version, the agreed protocol version $V_{final}$ is usually determined by:

$V_{final} = \text{select\_compatible}(V_c, V_s)$

Typically, the server accepts the connection if it can support the client's requested version. If the client requests a version newer than what the server knows, the server may reject the connection or respond with its highest known version, relying on the client to handle backward compatibility.

Handling Feature Mismatches

Robust MCP implementations must handle "graceful degradation." You cannot assume a capability exists just because your code expects it.

For example, if you are building a client that visualizes server logs, you must first check if the logging capability exists in the server's handshake response.

# Pseudo-code logic for a client handling negotiation
server_caps = response.result.capabilities

if "logging" in server_caps:
    enable_log_panel()
else:
    hide_log_panel()

if "resources" in server_caps and server_caps["resources"].get("subscribe"):
    enable_live_updates()
else:
    enable_poll_button()

This pattern decouples the UI/UX from the backend implementation. It ensures that a sophisticated client can still extract value from a simple server, and a powerful server can still function (albeit with limited features) when connected to a basic client.

Failure Modes

The initialization phase is the primary filter for connection issues. Common failure scenarios during this phase include:

• Transport Timeout: The client connects via Stdio but receives no response to the initialize request within a set window (typically 10-30 seconds). This often indicates the server process crashed on startup or is waiting for input that never arrives.
• JSON-RPC Parse Error: The server emits non-JSON debug text to stdout before the handshake completes. This corrupts the transport stream, causing the client to fail parsing.
• Version Incompatibility: The client requires a newer protocol feature that the server implementation does not support.

By strictly enforcing this negotiation phase, MCP ensures that subsequent interactions, which may involve passing sensitive data or executing side effects, occur within a defined and agreed-upon context.