MCP Capabilities Negotiation — protocol handshake, feature detection, and version compatibility

The initialize / initialized flow

The MCP handshake is a two-step exchange that happens before any tool, resource, or prompt request:

// Step 1: Client sends initialize
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": {
      "name": "Claude Desktop",
      "version": "1.2.3"
    },
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    }
  }
}

// Step 2: Server responds
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "my-mcp-server",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "subscribe": true, "listChanged": true },
      "prompts": { "listChanged": true },
      "logging": {}
    }
  }
}

// Step 3: Client sends initialized notification (no response expected)
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

After receiving notifications/initialized, the session is live. The server must not send any other requests before notifications/initialized arrives — this includes sampling/createMessage, roots requests, or elicitation requests. The three-step handshake is mandatory even if both sides already know what capabilities they support.

Declaring server capabilities

Declare capabilities in the Server constructor. The capability object tells clients what they can do with your server:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';

const server = new Server(
  {
    name: 'my-mcp-server',
    version: '1.0.0'
  },
  {
    capabilities: {
      // Tools — declare if your server exposes tools
      tools: {
        listChanged: true // emit notifications/tools/list_changed when tool catalog changes
      },

      // Resources — declare if your server exposes resources
      resources: {
        subscribe: true,    // clients can subscribe to individual resource URIs
        listChanged: true   // emit notifications/resources/list_changed when catalog changes
      },

      // Prompts — declare if your server exposes prompts
      prompts: {
        listChanged: true   // emit notifications/prompts/list_changed when catalog changes
      },

      // Logging — declare if your server handles logging/setLevel requests
      logging: {},

      // Completions — declare if your server handles completion/complete requests
      completions: {},

      // Experimental — namespace for unreleased protocol features
      experimental: {
        'my-company/feature-v0': {}
      }
    }
  }
);

Only declare capabilities you implement. A client that sees resources: { subscribe: true } will send resources/subscribe requests. If your handler throws MethodNotFound, the client treats your server as broken, not as gracefully degraded.

Reading client capabilities in handlers

After initialization, use server.getClientCapabilities() to check what the connected client supports. Call it lazily — it returns null before initialization completes:

// In a tool handler — check before using sampling
server.tool('classify_ticket', { text: z.string() }, async ({ text }) => {
  const clientCaps = server.getClientCapabilities();

  if (clientCaps?.sampling) {
    // Safe to use sampling — client declared it
    return await classifyViaSampling(text);
  } else {
    // Fallback — client doesn't support sampling
    return await classifyWithKeywords(text);
  }
});

// Check roots capability before requesting filesystem context
server.tool('analyse_workspace', {}, async (_, { meta }) => {
  const clientCaps = server.getClientCapabilities();

  if (!clientCaps?.roots) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ error: 'Client does not support roots — cannot determine workspace boundary' })
      }]
    };
  }

  const roots = await server.requestRoots();
  // ... analyse files within declared roots
});

Protocol version compatibility

The current MCP protocol version is 2024-11-05. The server responds with the version it supports; if there is a mismatch the client decides whether to proceed. Handle mismatches defensively rather than hard-crashing:

import { InitializeRequestSchema } from '@modelcontextprotocol/sdk/types.js';

const SUPPORTED_VERSIONS = ['2024-11-05', '2025-03-26'];
const CURRENT_VERSION = '2024-11-05';

server.setRequestHandler(InitializeRequestSchema, async ({ params }) => {
  const requestedVersion = params.protocolVersion;

  if (!SUPPORTED_VERSIONS.includes(requestedVersion)) {
    console.warn(
      `Client requested protocol version ${requestedVersion}, ` +
      `server supports ${SUPPORTED_VERSIONS.join(', ')}. ` +
      `Responding with ${CURRENT_VERSION} — client may disconnect.`
    );
    // Per spec: respond with your supported version; client decides
  }

  return {
    protocolVersion: CURRENT_VERSION,
    serverInfo: { name: 'my-mcp-server', version: '1.0.0' },
    capabilities: { tools: { listChanged: true } }
  };
});

The MCP spec states the server should respond with the version it actually supports even if the client asked for a different one. The client is then responsible for deciding whether to proceed with the mismatched version or disconnect. Never reject the initialize request outright based on version alone — the client's disconnect path is cleaner than an error response at the initialize level.

Capability-conditional feature registration

Some server features only make sense when the client supports certain capabilities. Register them conditionally after the session is initialized rather than at server startup:

// Register sampling-dependent tools only when client supports sampling
server.on('initialized', () => {
  const caps = server.getClientCapabilities();

  if (caps?.sampling) {
    // Register tools that require sampling for core functionality
    server.tool('analyse_with_ai', { data: z.string() }, handleAnalyseWithAi);
    server.tool('generate_summary', { uri: z.string() }, handleGenerateSummary);

    // Notify client that the tool list has changed
    server.sendToolListChanged();
  }

  if (caps?.roots) {
    // Register workspace-aware tools only when client declares workspace roots
    server.tool('analyse_workspace', {}, handleAnalyseWorkspace);
    server.sendToolListChanged();
  }
});

This pattern keeps your tool catalog clean — clients that don't support sampling don't see sampling-dependent tools in their tools/list response, avoiding confusing failures when those tools are called without their prerequisite capability.

Experimental capabilities

The experimental namespace lets servers and clients negotiate features that aren't in the published spec yet. Use it for early-adoption features, private protocol extensions, or unreleased spec drafts. Both sides must declare the experimental key for it to mean anything:

// Server declares experimental support
const server = new Server(
  { name: 'my-server', version: '1.0.0' },
  {
    capabilities: {
      tools: {},
      experimental: {
        // Namespaced to avoid collisions with the spec and other vendors
        'my-company/batch-tools': { version: '0.2' },
        'my-company/streaming-results': { version: '0.1' }
      }
    }
  }
);

// Check in a handler
server.tool('run_batch', { operations: z.array(z.string()) }, async ({ operations }) => {
  const caps = server.getClientCapabilities();
  const batchCap = caps?.experimental?.['my-company/batch-tools'] as { version: string } | undefined;

  if (!batchCap) {
    // Client doesn't support the batch protocol extension
    // Fall back to single-operation execution
    return await runSingleOperation(operations[0]);
  }

  return await runBatchOperations(operations, batchCap.version);
});

Monitoring the initialization path

A standard HTTP uptime check (ping the TCP port, verify HTTP 200) tells you nothing about whether MCP initialization is succeeding. A server can accept a TCP connection and return HTTP 200 on /health while consistently hanging on the MCP handshake — the JSON-RPC initialize request never completes because the handler is deadlocked, a database call inside initialization is timing out, or a missing async await causes the response to be sent before the handler has run.

The correct probe for MCP servers is a full protocol-layer check that completes the initialize/initialized handshake. This is exactly what AliveMCP's MCP-aware probe does — it connects, runs the handshake, and verifies the server returns a valid capabilities response before declaring the endpoint healthy.

Expose a companion HTTP endpoint for your monitoring stack to use alongside the protocol probe:

// Track initialization metrics
let initializationCount = 0;
let lastInitializedAt: Date | null = null;
let initializationErrorCount = 0;

server.on('initialized', () => {
  initializationCount++;
  lastInitializedAt = new Date();
});

server.on('close', (error) => {
  if (error) initializationErrorCount++;
});

app.get('/health/init', (req, res) => {
  const secondsSinceInit = lastInitializedAt
    ? (Date.now() - lastInitializedAt.getTime()) / 1000
    : null;

  res.json({
    status: 'ok',
    total_sessions: initializationCount,
    last_initialized_seconds_ago: secondsSinceInit,
    error_count: initializationErrorCount,
    server_capabilities: server.capabilities
  });
});

Wire AliveMCP to both the protocol probe and /health/init. Protocol-layer failures — negotiate timeout, capability mismatch causing client disconnect, initialized notification never arriving — don't generate HTTP errors that standard monitors catch. They only appear as a missing or stalled protocol handshake.

Frequently asked questions

Further reading

• MCP Server Resources — declaring resource and subscription capabilities
• MCP Server Prompts — declaring prompt and listChanged capabilities
• MCP Server Sampling — checking client sampling support before use
• MCP Server Roots — checking client roots support before requesting workspace context
• MCP Server Health Checks — protocol-layer probes that verify initialize completes