MCP Transports and Connecting Servers to Claude Code and the Agent SDK

1.The stdio transport

With stdio, the client launches the server as a child process. The server reads JSON-RPC messages from stdin and writes them to stdout. Each message is a single request, notification, or response, delimited by a newline, and a message must not contain embedded newlines. The server may write UTF-8 text to stderr for logging. The client may capture, forward, or ignore that output, and should not assume that stderr output means something went wrong.

Shutdown is driven by the client. It closes the server's input stream, waits for the process to exit, and forcibly terminates the process if it does not exit within a reasonable time.

Sources1

2.Streamable HTTP, sockets, and remote deployment

A remote server uses Streamable HTTP. It exposes a single MCP endpoint that accepts POST, and the client sends every JSON-RPC request or notification as its own POST. The client's Accept header must list both application/json and text/event-stream. The server answers a request either with a single JSON object or with an SSE stream scoped to that request. That stream can carry related notifications, such as progress, before the final response. The server must not send independent requests on the stream. Instead, server-to-client interactions like sampling and elicitation are embedded in results as input requests. If the client posts a notification and the server accepts it, the server returns 202 Accepted with no body. Each POST also carries metadata headers: Mcp-Method on every request, and Mcp-Name on tools/call, resources/read, and prompts/get.

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: get_weather

For deployment, the sources give three security rules. Servers must validate the Origin header on every incoming connection, to prevent DNS rebinding, and must respond 403 Forbidden when it is present and invalid. A server running locally should bind to 127.0.0.1 rather than 0.0.0.0. And servers should authenticate all connections. Beyond HTTP, Claude Code can also connect to older SSE endpoints (--transport sse) and to WebSocket endpoints ("type":"ws" with a wss:// URL). The provided sources do not go further into hosting or scaling.

Sources2

3.Authoring with the official SDKs

You rarely write JSON-RPC by hand. In Python, the mcp package provides FastMCP. In a sample server from the MCP tunnels quickstart, a function decorated with @mcp.tool(), with type hints and a docstring, becomes a tool, and mcp.run(transport="streamable-http") serves it over HTTP. The client side looks similar in TypeScript. With @modelcontextprotocol/sdk, you create a transport, create a Client, and connect. Anthropic's TypeScript SDK then provides helpers (mcpTools, mcpMessages, mcpResourceToContent) that convert the server's tools, prompts, and resources into Claude API types.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

Sources34

4.Connecting a server to Claude Code

How you register a server with claude mcp add depends on what you were given. A URL means a remote server, so use --transport http (or sse). A launch command means a local server, so use --transport stdio, put the command after --, and pass any secrets with --env. For anything else, such as a WebSocket endpoint, use claude mcp add-json with a JSON config.

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

In JSON, a url entry needs an explicit type of http, sse, or ws. Claude Code treats an entry without a type as a stdio server, so the connection fails. Server names may contain only letters, numbers, hyphens, and underscores. To manage servers, use claude mcp list, claude mcp get <name>, and claude mcp remove <name>; inside a session, /mcp shows server status. Project-scoped servers from .mcp.json show as pending until you approve them in an interactive claude session. Claude Code also warns about hidden whitespace in config values and about the same server name being defined in more than one scope.

claude mcp add --transport  ?  notion https://mcp.notion.com/mcp

Sources5

5.Connecting a server to the Agent SDK

In the Agent SDK, you pass servers in the mcpServers option (mcp_servers in Python). These use the same shapes as before: type and url for a remote server, or command and args for a stdio server. The same JSON can live in a .mcp.json file. Configuring a server does not by itself give the agent permission to use its tools. You grant that in allowedTools, where each tool has the name mcp__<server>__<tool>, so a wildcard like mcp__claude-code-docs__* allows every tool on that server.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
  options: {
    mcpServers: {
      "claude-code-docs": {
        type: "http",
        url: "https://code.claude.com/docs/mcp"
      }
    },
    allowedTools: ["mcp__claude-code-docs__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

How quickly servers connect at startup affects the first turn. With tool search, which is on by default, the first turn waits only for servers marked alwaysLoad: true, and the others keep connecting in the background.

Sources6

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A stdio server can print debug output to stdout, and the client will filter it out.Why is that wrong?

   stdout may carry only valid MCP messages. Logging belongs on stderr, which clients should not treat as a sign of errors.

   Covered in The stdio transport

2. 2.A JSON server entry with just a url is enough, because Claude Code infers HTTP from the URL.Why is that wrong?

   An entry without a type is read as stdio, so a url entry must set type to http, sse, or ws.

   Covered in Connecting a server to Claude Code

3. 3.A locally running HTTP MCP server should bind to 0.0.0.0 so every client can reach it.Why is that wrong?

   Local servers should bind only to localhost, and must validate the Origin header to prevent DNS rebinding.

   Covered in Streamable HTTP, sockets, and remote deployment

Practise it for real

Register a local stdio MCP server in Claude Code, check that it connects, and remove it again.

1. 1.Run: claude mcp add --transport stdio myserver -- npx server (replace npx server with the launch command of a server you have)

   Why: A launch command means the server runs on your machine, so it is registered as stdio with the command after --.

   You should see: Claude Code saves a server named myserver that will run your command.

2. 2.Run: claude mcp list, then claude mcp get myserver

   Why: These commands show the configured servers along with their status and any warnings, such as hidden whitespace.

   You should see: myserver appears with its command and connection status.

3. 3.Start claude and type /mcp

   Why: /mcp shows the status of each server from inside a session.

   You should see: myserver shows as connected, along with its tools.

4. 4.Run: claude mcp remove myserver

   Why: This cleans up the test registration.

   You should see: myserver no longer appears in claude mcp list.