MCP Stdio vs. HTTP Transport: How Claude Talks to Tools
MCP defines two standard transports: stdio, where the client launches the server as a local subprocess and exchanges JSON-RPC messages over stdin/stdout, and Streamable HTTP, where the server runs independently and accepts requests over a network connection. Claude Code and Claude Desktop default to stdio for local tools because it needs no port, no auth, and no running server — which is exactly how open-context's own MCP server works today.
Key takeaways
- Stdio and Streamable HTTP are the two transports defined by the MCP specification; both carry the same JSON-RPC messages, just over different pipes.
- On stdio, the client process launches the MCP server and owns its lifecycle — no port is ever opened.
- open-context's MCP server (
src/mcp/index.ts) connects overStdioServerTransportonly; it has no Streamable HTTP mode. - open-context's Express REST API (
src/server.ts, port 3000) is a separate, unrelated HTTP server for the web UI — it does not speak MCP. - Streamable HTTP is the right choice for a remote or multi-client MCP server; stdio is the right choice for a tool that runs next to the client.
Why MCP needs more than one transport
The Model Context Protocol is a JSON-RPC-based protocol: every message — a tool call, a resource read, a notification — is the same shape no matter how it travels. What differs is the transport underneath it, and the spec defines exactly two standard ones: stdio and Streamable HTTP. Picking the wrong one is a common source of confusion when wiring up an MCP server, because "it's just JSON-RPC" doesn't tell you whether to spawn a process or open a socket.
Stdio: the client owns the process
Over stdio, the MCP client — Claude Code, Claude Desktop, or any other host — launches the server as a child process and writes JSON-RPC requests to its stdin, reading responses back from stdout. The server's stderr is free for logging, since it's never parsed as protocol traffic. The specification is explicit that clients should support stdio whenever possible, and for good reason: there's no port to bind, no network exposure, no authentication scheme to design, and the server's lifetime is tied directly to the client's. Close the client, and the subprocess goes away with it.
This is exactly the shape of open-context's MCP server. src/mcp/index.ts creates a
StdioServerTransport and connects it to the tool server — there's no listener, no
port, nothing to secure beyond the local filesystem permissions on
~/.opencontext/contexts.json. A Claude Code config entry like this launches it
directly as a subprocess:
{
"mcpServers": {
"open-context": {
"command": "node",
"args": ["PATH_TO_PROJECT/dist/mcp/index.js"]
}
}
}
The Docker variant works the same way — docker run -i --rm ... node dist/mcp/index.js
still launches a process that Claude's client manages, it just happens to be a container instead
of a bare Node process. Either way, the transport is stdio.
Streamable HTTP: the server runs on its own
Streamable HTTP is the transport for a server that isn't tied to any one client's process lifecycle. Instead of being launched, the server runs independently — on a port, on a remote host, behind a load balancer — and clients connect to it over HTTP. The 2025-03-26 through 2025-11-25 protocol revisions describe a single endpoint accepting both POST and GET requests, with an optional SSE stream for server-initiated messages, and a session ID the server may issue and the client must echo back on later requests.
The newest revision, 2026-07-28, simplifies this: it removes the GET/SSE streaming endpoint and protocol-level session IDs, moving request metadata into the message body instead (with some of it mirrored into HTTP headers so proxies can still route on it without parsing JSON bodies). Across every revision, the core trade stays the same — Streamable HTTP costs you a port, a host, and usually some form of auth, in exchange for a server that any number of remote clients can reach at once.
Where open-context's HTTP server fits — and where it doesn't
It's easy to assume open-context's Express server (src/server.ts, the thing serving
the web UI on port 3000) is "the HTTP version" of its MCP server. It isn't. That server exposes a
conventional REST API — POST /api/contexts, GET /api/contexts/search?q=,
GET /api/db/status, and similar routes documented in the
MCP tools reference — built for
open-context's own dashboard, not for MCP clients. It doesn't speak JSON-RPC and has no
mcp/ endpoint. The two servers happen to ship in the same Docker image, selected by
overriding the container's command (default CMD serves the HTTP API; node dist/mcp/index.js
runs the MCP server over stdio instead), but they are independent processes with independent
protocols.
That matters if you're trying to point Claude at open-context over a network: today you can't. The MCP server only runs in stdio mode, which means it has to be launched locally (or in a container Claude's client can exec into) rather than reached over HTTP from a remote host.
Choosing a transport for your own MCP server
Use this as the quick decision:
| Scenario | Transport |
|---|---|
| Tool runs on the same machine as Claude Code / Claude Desktop | stdio |
| Tool needs no network exposure or auth setup | stdio |
| Server must serve multiple remote clients at once | Streamable HTTP |
| Server runs on infrastructure the client can't launch a process on | Streamable HTTP |
open-context's own roadmap leans toward stdio staying the default for the MCP server specifically, since its primary job — giving Claude Code and Claude Desktop persistent local memory — is inherently a same-machine use case. A Streamable HTTP mode would matter mainly for a team-shared context store scenario, where one server needs to answer multiple developers' Claude sessions at once.
Give Claude persistent memory with open-context's MCP server.
Get started with open-context →FAQ
Does open-context's MCP server support HTTP transport?
Not today. src/mcp/index.ts connects the server to a StdioServerTransport only, so Claude Code and Claude Desktop launch it as a local subprocess and talk to it over stdin/stdout. There is no Streamable HTTP endpoint for the MCP protocol itself.
Why does Claude Code launch MCP servers as a subprocess instead of connecting over HTTP?
Stdio is the simplest transport for a tool that runs on the same machine as the client: no port to bind, no auth to configure, and the process exits cleanly when the client disconnects. The MCP specification recommends clients support stdio whenever possible for exactly this reason.
Is open-context's REST API the same thing as an MCP HTTP transport?
src/server.ts is a separate Express application that serves the web UI and a REST API (POST /api/contexts, GET /api/contexts/search, and similar routes) for open-context's own dashboard. It does not speak the MCP JSON-RPC protocol, so pointing Claude's MCP client at it will not work.
Which transport should I use for a remote or team-shared MCP server?
Streamable HTTP, because stdio requires the client to launch the server as a local child process on the same machine. HTTP lets one server instance accept connections from multiple remote clients, which stdio cannot do.
What changed with MCP's Streamable HTTP transport in the newest spec revision?
The 2026-07-28 revision removed the optional GET/SSE streaming endpoint and protocol-level session IDs from Streamable HTTP, moving request metadata into the message body instead. Earlier revisions (2025-03-26 onward) used a single HTTP endpoint with POST and GET, and allowed servers to open an SSE stream for server-initiated messages.