MCP Glossary

MCP Initialize

TL;DR

`initialize` is the first JSON-RPC method called on every MCP session. The client sends its protocol version, capabilities, and client info; the server responds with its version, capabilities, and server info. Tool calls and resource reads only work after a successful initialize + `notifications/initialized` handshake.

In depth

Every MCP session begins with a three-step handshake. Step 1: client sends `initialize` with its supported protocol version, declared capabilities, and identifying info (name + version). Step 2: server responds with the agreed protocol version, its own capabilities, and server info. Step 3: client sends `notifications/initialized` to confirm the handshake is complete. Only then can tool calls flow.

During initialize, protocol version negotiation happens. If the client asks for `2025-03-26` but the server only supports `2024-11-05`, the server downgrades — or returns an error if it can't meet the client's minimum. This keeps old clients and new servers (and vice versa) interoperable.

Capabilities declared here are fixed for the session. A server can't acquire `sampling` mid-session; the client can't start supporting `roots/listChanged` after the fact. Declare everything up front.

Initialize is also where auth typically happens. The client sends its auth context (Bearer token, OAuth session), and the server validates before proceeding. A failed initialize means the session never starts.

Code example

// Step 1: Client → Server
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "roots": { "listChanged": true }, "sampling": {} },
    "clientInfo": { "name": "claude-code", "version": "0.6.0" }
  },
  "id": 1
}

// Step 2: Server → Client
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": {}, "resources": { "subscribe": true } },
    "serverInfo": { "name": "my-server", "version": "1.0.0" }
  },
  "id": 1
}

// Step 3: Client → Server
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Examples

1
Claude Code initializing against `@modelcontextprotocol/server-filesystem` on startup
2
A remote MCP initialization including `Authorization: Bearer` for auth
3
A test harness in mcp-inspector running initialize to verify a new server
4
CI pipeline running initialize + tools/list to smoke-test an MCP deploy
5
Version downgrade: client asks for 2025-03-26, server responds with 2024-11-05

What it's NOT

✗Initialize is NOT just for authentication — it's full capability negotiation.
✗Initialize is NOT optional — no tool calls work before it completes.
✗Initialize is NOT repeated during a session — only at the start.
✗The `notifications/initialized` step is NOT a typo — it's a separate notification after initialize response.

Frequently asked questions

What happens if initialize fails?

The session never starts. The client logs the error and typically retries or surfaces it to the user.

Can I call tools before initialize completes?

No — servers will reject any non-initialize method until the handshake is done.

How often does the protocol version change?

Roughly every 6 months. Each version adds features; backward compatibility is the norm.

Build with MCP

Browse 300+ MCP servers, explore recipes, or continue learning the MCP vocabulary.

Browse the directory All terms