The underwriting team started the easy way. Each underwriter's workbench launched the uw-assessment server as a child process on the underwriter's own laptop, over a pipe. It worked on the first day. No network, no tokens, no gateway.
By the second month there were forty laptops, and each one held the assessment database's connection string in a configuration file, because the server process on each machine had to reach the database itself. The intake team copied the setup. A contractor's laptop was lost. Nobody could say for certain which credentials had been on it, or which version of the server package each laptop was running.
The platform team moved the server to a shared service: three instances behind a load balancer, one URL, a token on every request. In the first design review an engineer who had built on the earlier MCP revision asked the question everybody with sessions in their past asks: "When instance two restarts, what happens to the clients whose sessions lived there?" In revision 2026-07-28 the answer is that there are no protocol sessions to lose.
This page is about that move from local to remote: the two transports, what each lets a server assume, what the stateless revision changed, how errors and connectivity behave, and who operates what. Tools Engineering already teaches the basics of both transports for a tool author (MCP transports); this page takes the operator's view of one server shared by several teams.
Two ways to reach a server#
A local server is an MCP server that runs on the same machine as the host, started and stopped by it, usually as its child process. A tiny example: the workbench starts mcp_server.py and talks to it through its standard input and output. A remote server is an MCP server that runs as a network service, operated by someone else, that many hosts reach at one URL. A tiny example: https://mcp.uw.insurer.example/mcp, called by the claims, underwriting, support and analytics teams.
Normative (MCP specification 2026-07-28): MCP defines two standard transports for these, the stdio transport (the client launches the server as a subprocess and exchanges newline-delimited JSON-RPC over its standard streams) and Streamable HTTP (the server is an independent process with one HTTP endpoint, and every client message is its own POST). The messages are the same on both. What differs is everything around them: who starts the server, how the caller proves who it is, how a request is cancelled, and what a failure looks like.
Before AI. A backend engineer knows both shapes. A local server is like a command-line tool a script spawns with credentials in its environment: fast, private, and as safe as the machine it runs on. A remote server is like a shared microservice behind a load balancer: one deployment, one owner, an OAuth token on every call, and the classic lesson that server-side sessions make scaling and failover harder.
stdio: one line in, one line out#
The smallest primitive is one line on a pipe. The example's stdio server is main() in mcp_server.py, quoted:
def main() -> int:
"""stdio transport: newline-delimited JSON-RPC on stdin/stdout, logs on stderr, exit on stdin EOF."""
clock = SimClock()
principal = os.environ.get("UW_MCP_PRINCIPAL", "underwriting-agent")
if principal not in identity.PRINCIPALS:
principal = "unknown-agent"
server = McpServer(clock=clock, transport="stdio")
ctx = {"claims": local_claims(principal, clock), "token": None, "transport": "stdio"}
print(f"[uw-assessment stdio] principal {principal} (from the environment)", file=sys.stderr)
for line in sys.stdin:
if not line.strip():
continue
reply = server.handle_line(line, ctx)
if reply is not None:
sys.stdout.write(json.dumps(reply) + "\n")
sys.stdout.flush()
return 0
Three rules of the stdio page are visible in those lines. A message is one line and must not contain a newline. The server may log to standard error and must write nothing but MCP messages to standard output, which is why the startup line goes to sys.stderr. And the server should exit when its input closes, which is what the for loop does when the host closes the pipe.
The identity line matters most for this page. Normative: implementations on stdio should not follow the HTTP authorization specification and should take credentials from the environment instead. The host that starts the process decides who it acts for; here it sets UW_MCP_PRINCIPAL. There is no token, no audience and no per-request proof. The trust boundary is the operating system: whoever can start the process, or read its environment, is the caller.
The rest of the stdio lifecycle is the host's job, as the specification describes it. To shut down, the client closes the server's input, waits, and then terminates the process (on POSIX, SIGTERM then SIGKILL). To cancel one request, the client sends notifications/cancelled with its id. If the server dies, the client should restart it; in-flight requests are lost and can be retried against the fresh process, because the protocol keeps no state between requests.
Streamable HTTP: one endpoint, one POST, headers that mirror the body#
On the remote side, the specification's rules are more numerous because more parties touch each request: proxies, gateways, load balancers. Normative (MCP specification 2026-07-28):
| Rule | What the example's server does (mcp_http.py) |
|---|---|
| One MCP endpoint that accepts POST; every client message is a new POST with one request or notification | /mcp; GET and DELETE get 405 |
The client's Accept lists application/json and text/event-stream; the server answers a request with either a JSON object or an event stream scoped to that request | always one JSON object (no event streams in this subset) |
Every POST carries MCP-Protocol-Version, equal to the version in _meta | missing or different: 400, -32020 |
Mcp-Method on all requests; Mcp-Name (from params.name or params.uri) on tools/call, resources/read, prompts/get | missing or different from the body: 400, -32020 |
An unknown method gets 404 and -32601; an unsupported version gets 400 and -32022 | same |
| An accepted notification gets 202 with no body | same |
Origin validated on every connection; present and invalid means 403; a local server should bind to 127.0.0.1 | allowlist of two origins; binds 127.0.0.1 |
Why mirror the body into headers? The specification gives the reason in its validation section: without the check, a load balancer could route on the header while the server executes on the body, and the two could disagree. The header lets infrastructure route, rate-limit and filter on Mcp-Name without parsing JSON; the server's check makes sure what infrastructure saw is what the server runs. The body remains the source of truth.
What 2025-11-25 did, and why the stateless revision matters#
Here the earlier revision differs most. In 2025-11-25, a connection started with an initialize request; over HTTP the server could then assign a session id in an MCP-Session-Id header on the response that carried the initialize result. The client had to send that header on every later request. A server could end the session at any time and then had to answer requests carrying it with 404, after which the client had to start over with a new initialize. Clients could also open a GET stream for server-initiated messages, and streams were resumable with Last-Event-ID.
Think about the three instances behind the load balancer under those rules. A session lives in one instance's memory, so request 2 must reach the instance that saw request 1: sticky routing. When an instance restarts, every session on it is gone, and every client on it receives a 404 and redoes its handshake. Draining an instance for a deploy means waiting for its sessions or breaking them. The availability of a client's conversation was tied to the availability of one process.
Revision 2026-07-28 removed all of it. Normative: MCP is stateless; every request carries its protocol version and capabilities in _meta; servers must not rely on earlier requests on the same connection for capabilities, version or client identity; state that spans requests must be referenced by an explicit identifier the client passes on each request. No MCP-Session-Id, no GET stream, no Last-Event-ID. A modern-only server should answer GET or DELETE with 405 and ignore an MCP-Session-Id header without minting or echoing one. The specification adds that an open stdio process "is not a conversation or session" either.
A stateless request is a request that carries everything the server needs to process it, so any instance can answer it. For the operator this is the whole point. Any instance can serve any request, so the load balancer can route freely, a restart loses only the requests in flight, and a deploy can drain an instance in seconds. The MCP Java SDK's modern server page puts it in one line, as documented on 2026-11-18: "Any instance can serve any request, so a server scales out without sticky routing."
Diagram: Instance two restarts · sessions in 2025-11-25, stateless requests in 2026-07-28
Two columns, the same event. Three server instances sit behind a load balancer and instance two restarts during the day. Read each column top to bottom. On the left, under 2025-11-25 with sessions, the clients pinned to instance two lose their session, get 404 and must initialize again, and the load balancer had to route them stickily all along. On the right, under 2026-07-28, every request carries its version and capabilities, so the load balancer sends the next request to any healthy instance; only requests in flight are lost, and the client retries them.
- 2025-11-25 · protocol sessions
- initialize, then MCP-Session-Id: The server may assign a session id on the response carrying the initialize result; the client must send it on every later request.
- sticky routing: The session lives in one instance's memory, so the load balancer must keep a client on that instance.
- instance two restarts: A terminated session must be answered with 404.
- 404, initialize again: The client must start a new session with a new initialize request before it can continue.
- 2026-07-28 · stateless requests
- every request carries version + capabilities: No initialize, no session id. MCP-Protocol-Version, Mcp-Method and Mcp-Name mirror the body so infrastructure can route without parsing it.
- any instance: The server must not rely on earlier requests for version, capabilities or identity, so any healthy instance can answer.
- instance two restarts: Only requests in flight on instance two are lost.
- retry on another instance: The client retries the lost read within its deadline, and a lost write with the same idempotency key; state lives in the database and in explicit handles.
The diagram sets the two revisions side by side for one restart of instance two. Read each column top to bottom: the event is the same, the consequence is not.
Common confusion. "Stateless protocol" does not mean "stateless system". record_recommendation still writes a row, and its idempotency key still keeps a retried write to one row. What moved is where the state lives: out of a protocol session in one process's memory, into the database and into handles the client passes explicitly.
The one pattern that looks like state is the multi round-trip request: when a server needs more input (for example a confirmation from the user) it returns a result with resultType input_required, and the client sends the original request again with a new JSON-RPC id plus the answers and an opaque requestState the server gave it. Normative: servers must treat requestState as attacker-controlled and integrity-protect it when it influences authorization or business logic. Behind a load balancer the retry may land on another instance, which must be able to verify that state. The Java SDK page says to configure a shared HMAC key for exactly this. The example does not implement multi round-trip requests.
The insurance example: stage 4 and stage 5#
The example runs the same get_roof_assessment("SUB-1004") through five architectures (case UW-M01, this site's own). Stages 4 and 5 are this page's subject. Pick a stage in the lab to see the components, hops, trust boundaries, identity and who deploys each part; the tables next to each lab hold the same facts.
| Stage | Process / network hops | Trust boundaries | Identity at the call | Who deploys |
|---|---|---|---|---|
| 4. Local MCP server (stdio) | 1 / 0 | host to server process (same OS user); server to database | the OS process owner; principal from the environment variable UW_MCP_PRINCIPAL | the user or consumer application owner; the server maintainer; database credentials end up on each machine |
| Stage | Process / network hops | Trust boundaries | Identity at the call | Who deploys |
|---|---|---|---|---|
| 5. Remote MCP server (Streamable HTTP) | 2 / 2 | host to MCP server (audience https://mcp.uw.insurer.example); MCP server to the service (exchanged token, audience https://assessment-svc.internal.example); service to database | access token with an audience, validated on every request; a separate downstream token | each consumer team; the server maintainer; the platform team; identity and security governance; the assessment domain |
The result at both stages is the same DTO: submission_id SUB-1004, property_id PROP-2207, roof_age_years 22, roof_material modified bitumen, evidence_id EV-ROOF-0412, policy_version 2026.2, assessment_status complete. The model here is a scripted stand-in, so these results show how the protocol and the controls work, not how good any model is.
Read the last column of stage 4 again: "database credentials end up on each machine". That is the opening scene's forty laptops, written down by the example's own stage descriptor (stages.py, STAGES). Stage 5 has more parties and more hops, and in exchange the database credentials live in one place, the assessment service, and the MCP server holds none.
Run it: the recorded HTTP session#
run_cases.py writes out/mcp_transcript_http.json: 22 messages between the host's MCP client and the server, recorded from mcp_http.py on 127.0.0.1 with an ephemeral port. A short scratch script printed one line per message with the headers that matter (run on 2026-11-18 in a scratch copy; long lines cut):
messages: 22 | transport: Streamable HTTP (JSON responses only; no SSE in this subset)
1 C POST /mcp {"MCP-Protocol-Version": "2026-07-28", "Mcp-Method": "tools/list"}
2 S 401 Bearer resource_metadata="https://mcp.uw.insurer.example/.well-known/oauth-protected-resou
3 C GET /.well-known/oauth-protected-resource {}
4 S 200
5 C POST /mcp {"MCP-Protocol-Version": "2026-07-28", "Mcp-Method": "server/discover", "Authorization": "Bearer <toy token jti-b40df40f>"}
6 S 200
9 C POST /mcp {"MCP-Protocol-Version": "2026-07-28", "Mcp-Method": "tools/call", "Mcp-Name": "get_roof_assessment", "Authorization": "Bearer <toy token jti-b40df40f>"}
10 S 200
11 C POST /mcp {"MCP-Protocol-Version": "2026-07-28", "Mcp-Method": "tools/call", "Mcp-Name": "record_underwriter_decision", "Authorization": "Bearer <toy token jti-b40df40f>"}
12 S 403 error -31403 insufficient_scope Bearer error="insufficient_scope", scope="uw.decide", resource_metadata="https://mcp.uw.in
14 S 401 Bearer error="invalid_token", error_description="expiry check failed", resource_metadata="
16 S 401 Bearer error="invalid_token", error_description="audience check failed", resource_metadata
17 C POST /mcp {"MCP-Protocol-Version": "2026-07-28", "Mcp-Method": "tools/call", "Mcp-Name": "check_eligibility", "Authorization": "Bearer <toy token jti-b40df40f>"}
18 S 400 error -32020 Header mismatch: Mcp-Name header value 'check_eligibility' does not ma
19 C POST /mcp {"Authorization": "Bearer <toy token jti-b40df40f>"}
20 S 400 error -32020 Header mismatch: MCP-Protocol-Version header is missing; this server s
21 C GET /mcp {}
22 S 405
(Fifteen of the 22 lines shown; 7, 8, 13 and 15 are the requests and the list answer between them.) A successful run proves that the server refuses each wrong request at the layer that owns it, before any tool runs: no token (401 with a pointer to the metadata), an expired token (UW-M06) and a token for another audience (UW-M04) at authentication; a missing scope (403) at authorization; a header that disagrees with the body at header validation; a legacy client at header validation too; a GET stream at the method level. It does not prove anything about networks or speed: the server listened on one laptop's loopback address.
Message 18 is the load balancer problem in miniature: Mcp-Name says check_eligibility, the body says get_roof_assessment, and the server refuses rather than run either. Message 20 is the 2025-11-25 client from the opening review: it sends initialize without the new headers and gets 400 with the supported version named, the behavior the versioning page asks of a modern-only server.
The lab below steps through the same session, one exchange at a time, with who sent each message and the raw JSON. The table after it lists the exchanges for a reader without JavaScript.
| Messages | Request (host's MCP client) | Answer (MCP server uw-assessment) |
|---|---|---|
| 1, 2 | tools/list with no token | 401, WWW-Authenticate naming the protected resource metadata and scope uw.read |
| 3, 4 | GET /.well-known/oauth-protected-resource | 200, the metadata (RFC 9728): resource, authorization server, scopes |
| 5, 6 | server/discover with a token for this server | 200, supported versions and capabilities |
| 7, 8 | tools/list as the underwriting agent | 200, four tools; cacheScope private, ttlMs 300000 |
| 9, 10 | tools/call get_roof_assessment SUB-1004 | 200, the PropertyAssessment; the server exchanged the token for a downstream one |
| 11, 12 | tools/call record_underwriter_decision | 403 insufficient_scope, scope uw.decide, JSON-RPC error -31403 |
| 13, 14 | tools/call with an expired token (UW-M06) | 401 invalid_token, nothing executes |
| 15, 16 | tools/call with a token for the CRM (UW-M04) | 401 invalid_token, audience |
| 17, 18 | Mcp-Name header disagrees with the body | 400, -32020 HeaderMismatch |
| 19, 20 | legacy initialize without the headers | 400, -32020, the supported version named |
| 21, 22 | GET /mcp | 405 Method Not Allowed |
What this is not. Tokens, audiences, the protected resource metadata and token exchange are explained on Enterprise authorization; this page uses their outcomes only. The basic shape of both transports for a tool author, and notifications, are on Tools Engineering: MCP transports.
Status codes, errors and connectivity: what the client must do#
Each answer above asks the host's MCP client for a different next step. Getting this table wrong is how a remote server turns a token refresh into an outage, or a refusal into a retry storm.
| Answer | Who produced it | What the client should do |
|---|---|---|
401 invalid_token or no token | authentication at the server or gateway | obtain a new token (the challenge names the metadata); never retry the same token |
403 insufficient_scope | authorization at the server | ask for the named scope if a person may grant it (step-up); for an agent, stop: retrying cannot help |
400 -32020 HeaderMismatch | header validation | fix the client; this is a bug, not a transient fault |
400 -32022 UnsupportedProtocolVersion | version negotiation | retry once with a version from data.supported |
404 -32601 | method dispatch | the method does not exist on this server; do not retry |
| 405 on GET | a modern server meeting a 2025-era client | switch to the modern revision; there is no GET stream |
200 with isError true | the tool | let the model read it; retry only if the error says it is retryable |
| no answer, timeout, connection reset | the network or an instance | retry reads within a deadline; retry writes only with the same idempotency key |
The last row is where local and remote differ most. On stdio a broken pipe means the child process died, the host restarts it, and the next request goes to the fresh process. Over HTTP a timeout may hide a request that completed on an instance whose reply was lost, the partial failure of Client and server. Statelessness makes the retry safe at the protocol level, since any instance can take it; the idempotency key makes it safe at the business level. Cancellation differs too. Normative: on stdio the client sends notifications/cancelled; on Streamable HTTP, closing the response stream is the cancellation, and the server must treat it as such.
Who operates a local server, and who operates a remote one#
The most important difference between the two is not technical. It is who answers the pager.
Diagram: Stage 4 and stage 5 · who starts it, who proves who, where the credentials live
Rows are the two kinds of server; columns are the questions an operator asks. Read across a row to see one architecture, or down a column to compare them. The local server is started by the host and trusts the environment; the remote server is operated by a team, checks a token on every POST and holds no database credentials.
- Local server
- the host, as a child process: The client launches the server as a subprocess and closes its input to stop it.
- the environment: stdio does not use the HTTP authorization flow; credentials and identity come from the environment the host set.
- on every machine: The server process on each machine reaches the database itself, so each machine holds its credentials.
- one user's work: In-flight requests are lost and can be retried against the fresh process.
- Remote server
- the server maintainer: One deployment, rolled out once; several instances behind a load balancer.
- a token per POST: Every POST carries a bearer token for this server's audience, validated on every request, scopes checked per call.
- the assessment service: The MCP server exchanges the caller's token for a downstream one; only the service holds database credentials.
- requests in flight: Other instances keep answering; nothing was pinned to the one that failed.
The diagram reads in two directions: across a row for one architecture, down a column to compare them on one question. The table adds the rows an operator asks next.
| Question | Local server (stage 4) | Remote server (stage 5) |
|---|---|---|
| Who starts and stops it | the host application on each machine | the server maintainer's deployment, behind the platform team's gateway |
| Who updates it | every machine, at its own pace | one deployment; versions roll out once |
| Where database credentials live | on each machine that runs it | in the assessment service only; the MCP server holds none |
| How the caller is identified | the OS user and the environment the host set | a token per request, audience checked, scopes per call |
| What a crash affects | one user's session of work; the host restarts it | in-flight requests on one instance; the others continue |
| Who sees an audit trail | whatever that machine logs | one audit store with every decision (AUD-0002 in the example's README) |
| Typical fit | one person's private data and tools on their own machine | a capability several teams share, with central identity and audit |
Neither column is better. A local server is right when the data and the authority are one person's: their files, their repository, their machine. A remote server is right when the capability is shared and the data is the organization's. The underwriting team's mistake in the opening was not stdio. It was putting a shared database's credentials into forty copies of a local server.
What goes wrong without these ideas#
Without the local-versus-remote distinction, teams make one of two mistakes. They put shared, sensitive capabilities in local servers and scatter credentials across laptops, with no central record of who called what. Or they put a person's private tools behind a remote service and add a network, an identity provider and an on-call rotation to something a pipe did well.
Without the stateless model, a remote server repeats session-era mistakes in new places: it keeps per-client state in process memory, behind a load balancer that does not know about it. Without header validation, a gateway that filters Mcp-Name can be bypassed by a body that says otherwise. And without the status-code table, clients retry 403s forever and give up on 400 -32022 instead of retrying once.
In a coding agent. A developer's coding agent runs a repository server locally over stdio: it reads the working copy with the developer's own rights, andread_fileandsearch_codenever leave the machine. The company's code review server is remote:open_pull_requestgoes over Streamable HTTP with a token that says which repositories this developer may write to, and the review system keeps the audit trail. Same agent, two transports, two operators. Harness Engineering shows where both sit in the agent's runtime.
Security and governance notes#
Security note. A local server runs with the privileges of whoever started it. The security best practices page, read on 2026-11-18, describes local server compromise: a malicious startup command in a client configuration, a malicious payload inside the server, or a local server left running on localhost and reached by DNS rebinding. A client offering one-click setup MUST show the exact command, untruncated, flag it as dangerous, require explicit approval and allow cancel; it SHOULD sandbox the server with minimal privileges. Developers of local servers SHOULD use stdio, or restrict an HTTP server with a token or a Unix socket. A remote server validates Origin, authenticates every request and checks headers against the body.
Governance note. For a local server, governance is package provenance (which build is on which machine), the exact launch command a person approved, and where local secrets live; the example's stage descriptor lists those three. For a remote server, it is the catalog, scope approval, per-call authorization, audit events, per-team rate limits and a deprecation policy, owned by named roles on Governance. Decide which list you are signing up for before you choose the transport.
Checklist for Monday#
- Each MCP server you run is labelled local or remote, with the person or team that operates it.
- No shared database credential sits in a local server's configuration; shared data goes through a remote server or the service itself.
- A stdio server writes only MCP messages to standard output, takes its principal from the environment, and exits on input EOF.
- A remote server keeps no per-client state in process memory; any instance can serve any request.
MCP-Protocol-Version,Mcp-MethodandMcp-Nameare validated against the body on every POST; mismatches get 400-32020.- The client handles 401, 403, 400
-32020, 400-32022, 404 and 405 differently, as in the table. Originis validated; a local HTTP server binds 127.0.0.1 and requires a token.- The protocol revision of every request is logged; there is no session to look it up in later.
Exercises#
- A remote server keeps each client's search cursor in a dictionary in process memory, keyed by client id. What breaks behind three instances, and what does the specification ask instead?
- A gateway rate-limits by
Mcp-Nameand forwards to the server. A client sendsMcp-Name: search_guidancewith a body callingrecord_recommendation. What stops the write? - The team wants underwriters to run the server locally "for speed", with the database password in an environment variable. Which two problems from this page apply?
AnswersOne line each
- The next page request may land on another instance with no cursor; state that spans requests must be an explicit identifier passed on each request (a handle), stored where every instance can read it and bound to the caller.
- The server's header validation:
Mcp-Namemust equalparams.name, so it answers 400-32020and runs nothing; the gateway should also check that the protocol version requires that validation. - Credentials on every machine (stage 4: "database credentials end up on each machine") and local server compromise: the server runs with the user's rights, so whatever can read that environment holds the password.
Where state goes behind a load balancerHandles, requestState, change feeds and caches when any instance may answer
Removing protocol sessions moves state; it does not remove it. Four kinds of state remain on a shared server, and each needs a home that every instance can reach.
Business state lives in the domain service's database. That was already true: record_recommendation writes a row and the idempotency key makes a retry land on the same row, whichever instance received it.
Cross-call handles, such as a paging cursor, are the specification's replacement for session state. The tools page describes them as explicit identifiers the model or client passes back as ordinary arguments. The security best practices page adds that a handle is not authentication: a server must verify every request, should make handles random, and should bind them to the user from the verified token. A handle kept in one instance's memory reintroduces sticky routing by the back door.
Multi round-trip state is the subtle one. The server returns requestState with an input_required result; the client echoes it on the retry, which may land anywhere. Because it is attacker-controlled, the server must integrity-protect it when it matters, and every instance must hold the key. The MCP Java SDK's modern server page says to configure a shared HMAC key for this across instances. It also says its change feed reaches only listeners on the same instance and that multi-instance deployments need a shared message bus publisher: a subscriptions/listen stream opened on instance one will not hear about a change made through instance three unless the instances share one feed.
Caches are the fourth. Results of tools/list carry ttlMs and cacheScope. The example's list is private, because it depends on who asks; a shared cache in a gateway must not serve one team's list to another. This site's recommendation: write down, per kind of state, where it lives and who can read it, before the second instance is started.
Running two eras at once during a migrationWhat a 2025-11-25 client sees at a modern server, and how a platform team stages the move
A platform rarely switches every host on one day. The specification describes the meeting points. A legacy client that opens with initialize over HTTP is rejected by a modern server with 400, because the required headers are missing; message 20 of the example's session is exactly that. A client still on the older HTTP+SSE transport fails at its opening GET, which a modern server answers with 405. A dual-era client tries a modern request first and, on a 400, reads the body: a recognized modern error means the server is modern, and it retries with a supported version; an empty or unrecognized body means it falls back to initialize. On stdio the probe is server/discover, and the fallback must not depend on one specific error code.
Server side, a dual-era server picks legacy behavior when a client opens with initialize. The official SDKs differ on this, as documented today: the Python SDK v2 serves both revisions at once, the Java SDK supports both, and the TypeScript README read here names only 2026-07-28 (Java and SDKs has the table). A shared server built on a dual-era SDK can therefore accept old and new hosts during the move, at the cost of keeping session-era behavior alive for the old ones, sticky routing included.
A staged plan follows from that. First, log the revision of every request and count hosts per era. Second, run the shared server dual-era, with session affinity only for legacy traffic. Third, move host by host, starting with the hosts the platform team controls. Fourth, switch the server to modern-only and watch for 400s with an empty MCP-Protocol-Version, which name the stragglers. The legacy path is where the old problems live; the goal is to shrink it to zero, then remove it.
A local server over HTTP instead of stdioWhy some tools listen on localhost, and the three defences that then become mandatory
Some local servers listen on a localhost port instead of using a pipe, for instance so that several applications on one machine can share one server process. That brings HTTP's threat model onto the laptop. Any web page the user opens can try to send requests to 127.0.0.1, and with DNS rebinding a malicious site can make the browser treat its own domain as resolving to the local address.
The specification answers with three rules, all of which the example's HTTP server follows: validate Origin on every connection and answer 403 to a present, invalid one; bind to 127.0.0.1, not 0.0.0.0; authenticate every connection. The security best practices page adds, for local servers in particular, that a developer should prefer stdio, which limits access to the client that started the process, or restrict HTTP access with an authorization token or a Unix domain socket. The MCP Java SDK goes further by default, as documented on 2026-11-18: its server rejects any request that carries an Origin header with 403 until origins are explicitly allowed.
The same page warns about one architecture in particular: a local proxy that spawns stdio servers on request. If a web vulnerability in a client leaks the proxy's token, the attacker can ask the proxy to start arbitrary commands. The defences named are sandboxing spawned processes, restricting their file system access, logging every spawn and requiring extra authorization for dangerous commands. This site's recommendation: use stdio for a local server unless you have a concrete reason not to, and treat a localhost HTTP server with the same checklist as a remote one.
In one breath#
A local server is a child process the host starts over stdio, identified by the environment it inherits and as safe as the machine it runs on; a remote server is a network service reached over Streamable HTTP, where every POST carries a token, the protocol version and mirrored headers that the server checks against the body. Revision 2026-07-28 removed initialize and MCP-Session-Id, so any instance can answer any request, a restart loses only requests in flight, and state lives in the database and in explicit handles. Choose by who owns the data and who will operate the server, and give each answer code its own client behavior.
Stage 5 moved the database credentials out of forty laptops and into one service, but it did not settle how that service should reach its data, or whether the agent application should reach the database directly in the first place. Direct SQL, a service boundary or an MCP adapter each put the connection pool, the transaction and the database account in a different place. That decision is The DB decision.