Home / Extending: skills, MCP, subagents, hooks, plugins

Connecting an MCP server, and what changed

An MCP server connects via OAuth or a key, is verified with claude mcp list, and the protocol itself changed at its core on 28 July 2026, a fact independent of any Claude Code version.

A remote MCP server connects in one command: claude mcp add --transport http server-name https://exemple.example.com/mcp declares the entry, and Claude Code itself detects whether authentication is required. When the server responds with 401 or 403, Claude Code marks the entry as needing authentication and offers claude mcp login to open the OAuth flow, or the --header "Authorization: Bearer ..." option for a fixed token passed by hand.

Verify before trusting

claude mcp list shows the real status of each declared server, with at least six possible statuses: connected, needs authentication, connection failed, pending approval, rejected under the disabledMcpjsonServers setting, or disabled for this project and re-enabled through /mcp; an HTTP or SSE server already in use may also show as cached. A connection failure signals that Claude Code failed to reach that particular server, not that the list command itself failed, a nuance that avoids blaming the wrong link.

$ claude mcp list
depot-tickets       Connected
facturation-api      Needs authentication
brouillon-crm        Pending approval

The scope chosen at the time of adding determines who sees this server. In decreasing order of priority: local scope (--scope local, the default, private, stored in ~/.claude.json), then project scope (--scope project, the .mcp.json file shared through git, described in the previous lesson), then user scope (--scope user, available across every project on the machine). When two scopes declare the same server name, the entire configuration of the stronger scope is used, nothing merges field by field between the two.

The protocol changed at its core on 28 July 2026

Independently of Claude Code, the MCP specification itself changed shape. The revision published on 28 July 2026 replaces a stateful core, where client and server first opened an initialize handshake before any exchange, with a stateless core where each request carries its own version information in a _meta parameter. The Mcp Session Id header disappears from the HTTP transport. The Tasks feature, which allowed tracking long running work without blocking the response, moves out of the protocol core and becomes a separate official extension, with a tasks/get poll replacing a blocking wait. An extensions field is also added to client and server capabilities, to carry any future extensions beyond the protocol core.

Since version 2.1.232, Claude Code picks an MCP runtime at startup and keeps it until exit. The v1 runtime remains in use on Bedrock, Claude Platform on AWS, Vertex, Foundry, behind a Claude apps gateway, or when feature flag retrieval is disabled. Elsewhere, the v2 runtime automatically negotiates, with HTTP servers and claude.ai connectors, the most recent protocol revision each one accepts, but for a stdio server, exactly the kind of server the next lesson teaches you to write, this negotiation only happens if the MCP_PROTOCOL_NEGOTIATION variable is set to auto: otherwise the connection is made as in v1. An older server, written before July 2026, therefore keeps working in every case, the negotiation, when it happens, choosing the revision it understands. This section describes the state of the protocol as of 2 September 2026, a subject that moves at the pace of its own versions, not that of the course. The next lesson shows how to write, on the server side, the program that this claude mcp add command has just declared.