Chapter 8: MCP Transports and Pluggable Servers

Transport Options

A transport is the concrete channel and framing rules that carry MCP's JSON-RPC 2.0 messages between a client and a server. MCP is deliberately transport-agnostic: every message is UTF-8-encoded JSON-RPC 2.0, and any channel that preserves that framing plus the MCP lifecycle can serve as a transport. The spec even says clients SHOULD support stdio whenever possible. Think of the transport like the delivery method for a letter: the contents (JSON-RPC) are identical whether you hand it over in person (stdio) or mail it across the country (HTTP), but the speed, reach, and security trade-offs differ wildly.

stdio for local processes

With stdio, the client launches the MCP server as a subprocess on the same machine and talks to it through the standard streams. The mechanics are simple: the server reads JSON-RPC from stdin and writes to stdout; messages are delimited by newlines and MUST NOT contain embedded newlines (one line, one message); the server MAY write UTF-8 logs to stderr; and neither side may write anything to stdout/stdin that is not a valid MCP message. A stray print() to stdout will corrupt the protocol stream and break the connection.

Figure 8.1: stdio transport topology — client and server as parent/child on one machine

Two consequences follow. First, there is no transport-layer authentication—no network, no header, no place for a bearer token—so a stdio server takes credentials from the environment. Second, stdio uses a process-per-user model: 50 developers each running 8 servers implies roughly 400 concurrent processes spread across 50 laptops—fine locally, unworkable as a shared service. The payoff is low latency and simplicity: no network hop, no TLS handshake. stdio is ideal for local, single-user, minimal-latency integrations: CLI tools, local file access, and developer tooling.

Streamable HTTP and SSE for remote

When your assistant must reach a server that lives elsewhere—a cloud service, a shared gateway, a multi-tenant SaaS—you use Streamable HTTP, which replaced the older HTTP+SSE transport from 2024-11-05. The server is an independent, long-running process serving many clients at once, and it MUST provide a single HTTP endpoint (e.g. https://example.com/mcp) supporting both POST and GET. It may layer in Server-Sent Events (SSE)—a one-way, long-lived HTTP stream that lets the server push multiple messages back over one connection.

Every client message is a new HTTP POST; the client MUST include an Accept header listing both application/json and text/event-stream. Responses/notifications alone earn an HTTP 202 Accepted with no body; a POST carrying requests gets back either a single JSON object or an SSE stream. To cancel work a client sends an explicit MCP CancelledNotification—a dropped connection is not a cancellation. The client MAY also issue a GET (Accept: text/event-stream) to open a server-to-client stream, or receive HTTP 405 if no SSE is offered.

Resumability: servers MAY attach an id to each SSE event; to resume, the client re-issues a GET with a Last-Event-ID header and the server replays messages on that same stream. Session management: the server MAY assign a cryptographically secure Mcp-Session-Id on the InitializeResult; the client must then include it on every request (HTTP 400 if missing, HTTP 404 if terminated), and SHOULD send an HTTP DELETE to end the session explicitly.

Figure 8.2: Streamable HTTP transport topology — one remote server serving many clients

The deprecated (2024-11-05) transport used two separate endpoints—a dedicated SSE endpoint opened via GET plus a POST endpoint. Streamable HTTP collapses this into one endpoint where SSE is optional. For backward compatibility a server can host both; clients probe by POSTing an InitializeRequest first and, on a 4xx like 405/404, fall back to the legacy GET/endpoint SSE flow.

Choosing a transport

The decision usually comes down to where the server lives and who needs to reach it. The table distills the trade-offs.

A useful heuristic: start with stdio for anything on the same machine, and reach for Streamable HTTP the moment a network boundary appears. If you want to authenticate users, share one server among many, or stream long-running results, you have outgrown stdio. The spec's "support stdio whenever possible" is about client capability, not a mandate to avoid HTTP for remote work.

Pluggable Server Ecosystem

The word "pluggable" is the whole point of MCP. Rather than baking every integration into your assistant, you plug in servers—each a self-contained bundle of tools, resources, and prompts—and the host wires them together at runtime.

Local vs. remote servers

A local server runs on the user's own machine and is almost always reached over stdio: the client spawns it with a command and args and talks over stdin/stdout. A filesystem server exposing a couple of folders, or a SQLite server pointed at a local database, are canonical examples—and they run with the user's own account permissions, which is both convenient and dangerous. A remote server runs elsewhere and is reached over Streamable HTTP, using a URL endpoint, supporting many concurrent clients, and carrying an Authorization header for OAuth. Think of a local server as a desk drawer—instantly accessible but only to you—and a remote server as a shared filing room down the hall—reachable by many, but requiring a key and a walk.

Composing many servers in one host

The host aggregates the tools from all connected servers and presents them to the model as one combined toolbox; each server runs as its own process (stdio) or independent HTTP service. When the model calls a tool, the host routes that call to the specific server that exposes it and returns the result.

Figure 8.3: One host aggregating multiple pluggable servers into a single toolbox

Picture the host as a universal remote control: your TV, sound bar, and streaming box are three separate devices, but the remote presents one unified set of buttons and knows which device should receive each press. This composition has a critical corollary: because the descriptions of tools from all connected servers are presented to the model at once, a multi-server setup creates a combined attack surface—one poisoned server can influence how the model treats every other server's tools. This is exactly why tool namespacing and per-server isolation matter (see Security and Trust).

Server discovery and configuration

Clients learn which servers to plug in from a configuration file. In Claude Desktop this is claude_desktop_config.json: on macOS at ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows at %APPDATA%\Claude\claude_desktop_config.json. You reach it through Claude menu → Settings… → Developer → Edit Config. Its heart is a top-level mcpServers object whose keys are friendly server names; you can add as many servers as you want. Each stdio entry specifies command (the executable), args (an array of arguments), and optional env (environment variables like API keys).

Here is a worked example connecting three servers at once—a filesystem server exposing two folders, a Brave web-search server carrying an API key, and a SQLite server pointed at a local database:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
        "BRAVE_API_KEY": "..."
      }
    },
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/Users/username/assistant.db"]
    }
  }
}

Reading it: "filesystem" is the friendly name; "command": "npx" runs the server via Node's npx with "-y" to auto-confirm the install; the trailing directory arguments are the folders this server is allowed to access (least privilege you control in config); and the env block on brave-search injects the BRAVE_API_KEY—the stdio pattern for supplying credentials, since there is no transport-layer auth. Three operational rules matter:

1. Paths must be absolute, not relative—a relative path fails because the server's working directory is not what you might assume.
2. Completely quit and restart the client so it re-reads the config and spawns the servers.
3. Verify the connection—a hammer/MCP indicator appears in the input box; if a server fails to appear, the logs (~/Library/Logs/Claude/mcp.log and per-server mcp-server-SERVERNAME.log on macOS) tell you why.

Because each server exposes tools the model can invoke with the user's approval, and runs with the user's account permissions, grant only what you are genuinely comfortable exposing. Remote entries use a URL and typically OAuth rather than a local command.

Building and Running Servers

Anatomy of a minimal MCP server

At its core, a minimal MCP server is a program that (1) speaks JSON-RPC 2.0 over a chosen transport—for a local server, stdio, reading newline-delimited messages from stdin and writing to stdout while keeping stdout pristine and logging to stderr; (2) implements the MCP lifecycle—answering an InitializeRequest, declaring capabilities, then serving request/response and notification traffic; and (3) exposes capabilities: tools (functions the model can call), and optionally resources and prompts, each with metadata the host relays to the model. Conceptually a filesystem server looks like this:

server = MCPServer(name="filesystem", version="1.0.0")

@server.tool(
    name="read_file",
    description="Read a text file within an allowed directory",
    schema={ "type": "object",
             "properties": { "path": { "type": "string" } },
             "required": ["path"],
             "additionalProperties": false }
)
def read_file(path):
    assert is_within_allowed_dirs(path)   # enforce least privilege
    return open(path).read()

server.run(transport="stdio")             # launched by the host as a subprocess

Two design choices here are not cosmetic. The strict JSON Schema (additionalProperties: false plus tight required fields) constrains what the model can send, and the explicit is_within_allowed_dirs check enforces the least-privilege boundary declared in the config. When the host launches the server with command/args, server.run(transport="stdio") wires the program to the stdin/stdout streams the client is already reading and writing.

Lifecycle and process management

For a stdio server the lifecycle is a parent/child story: the client (1) launches the subprocess using the configured command and args, (2) the two exchange messages over stdin/stdout (with optional stderr logs) for as long as the session lasts, and (3) the client closes stdin and terminates the subprocess when finished. The upshot: the server's lifetime is the session's lifetime. There is no separate service to monitor, no port to keep alive; when the host exits, the child dies with it.

For a Streamable HTTP server, process management is a different discipline. The server is an independent, long-running process that outlives any single client and serves many at once. It must handle session tracking (issuing and validating Mcp-Session-Id), gracefully answer session termination (HTTP DELETE, or HTTP 404 for a gone session), and support resumability (replaying by Last-Event-ID). Operationally it looks like any web service: run it behind a supervisor or in a container, scale it horizontally behind a load balancer, and keep it healthy independent of who is connected.

Versioning and compatibility

MCP is a versioned protocol; the transports here belong to 2025-03-26, which replaced the HTTP+SSE transport of 2024-11-05. Protocol version compatibility: a server can host the deprecated two-endpoint HTTP+SSE alongside the new single MCP endpoint, and clients probe by POSTing an InitializeRequest first, falling back to the legacy GET/endpoint SSE flow on a 4xx—so a mixed fleet keeps working through a migration. Tool-definition compatibility is subtler and more security-relevant: because users typically approve a tool once and rarely re-review it, any later change to a tool's definition is invisible unless something actively watches for it. This is the seam rug-pull attacks exploit, and the reason a robust host will pin and hash tool definitions and re-prompt the user whenever a definition changes. Treat your tool schemas as a versioned public contract.

Security and Trust

MCP makes a profound trade: it shifts control from developers to the LLM. The model, not a hand-written program, decides which tools to call and with what arguments. The correct mindset is to treat every tool description and every return value as a potential injection vector, enforce integrity checks, and require human oversight for sensitive actions. The most cited issues are over-privileged access, indirect prompt injection, tool poisoning and rug pulls, credential sprawl, and audit blind spots.

Authentication and authorization

Authentication splits cleanly along the transport line. stdio has no transport-layer authentication—no network, no header—so it draws credentials from the env block; security reduces to what you launch and what you grant it. Streamable HTTP can and should authenticate: it carries an Authorization header, and the recommended mechanism is OAuth for delegated, scoped access, with a gateway able to validate the credential before it reaches the server. Best practice is scoped, per-server, short-lived tokens (never one shared token), requesting the narrowest scope that works—mail.readonly rather than mail.full_access. Two failure modes matter: the confused deputy problem (a server executing with its own broad privileges rather than the user's restricted ones) and credential sprawl (shared tokens and over-scoped permissions across ungoverned servers creating aggregation risk).

Sandboxing untrusted servers

If you cannot fully trust a server—and with third-party servers you generally cannot—you contain it: run local servers in containers with restricted filesystem and network access; prefer stdio for local connections to limit network exposure; for HTTP/SSE servers, bind to 127.0.0.1, never 0.0.0.0, and validate the Origin header on every connection; and separate sensitive servers (payments, auth) from general-purpose tools. The Origin and localhost-binding rules are not folklore—the spec mandates them for Streamable HTTP to prevent DNS rebinding attacks, where a malicious website tricks a browser into interacting with a local MCP server the user never intended to expose.

Tool poisoning and supply-chain risk

The most distinctive MCP threat is tool poisoning, hinging on a fundamental asymmetry: the model sees the complete tool description and metadata, while the user sees only a simplified UI representation. Malicious instructions embedded in a tool's description or parameters are invisible to users but fully visible to the model—and an agent does not even need to use a poisoned tool to be affected; it only needs to read its description. "One drop of poison can infect every session where that tool is interacted with." The documented Invariant Labs / Cursor example: an innocent-looking add tool concealed directives to read ~/.cursor/mcp.json (other servers' credentials) and ~/.ssh/id_rsa and smuggle them out through function parameters, while the user saw only a simplified confirmation dialog.

Figure 8.4: A tool-poisoning attack path — hidden instructions exfiltrate secrets

Three related patterns round out the family: tool shadowing (a malicious server injects instructions that alter the behavior of other, trusted tools—the "combined attack surface" hazard); rug pull (a tool is legitimate when approved, then the server silently changes its definition weeks later); and indirect (data) prompt injection (instructions hidden inside externally sourced data the agent reads through a server). The defenses layer up: tool integrity (pin and hash definitions, verify before execution, re-prompt on change, maintain an allowlist, run scanners like mcp-scan); least privilege and credential hygiene (scoped, per-server, short-lived credentials); input/output validation (treat all LLM-generated parameters as untrusted, strict JSON Schema, and validate tool outputs too since one tool's output can become another's input); human-in-the-loop approval that displays the full tool-call parameters, not a summary; and supply-chain and monitoring (trusted sources, checksums, typosquatting vigilance, centralized audit logs to a SIEM). Treat the server manifest as a signed, versioned, verifiable artifact—because it is precisely what poisoning and rug-pull attacks corrupt.