Home Glossary
HomeGlossaryMCP Initialize
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.

Related terms

MCP SessionMCP CapabilityModel Context Protocol (MCP)MCP ServerMCP Client

See also

  • MCP Lifecycle

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 MarketplaceAll terms