All chapters
  1. Start hereA protocol standardizes the call. It does not grant the permission
  2. Foundations · 1The primitive: a function, its arguments, its result, its side effects
  3. Foundations · 2Function calling: the model asks, your application executes
  4. Foundations · 3Client and server: process boundaries, JSON-RPC, errors and trust
  5. Foundations · 4What MCP is: host, client, server and what the protocol promises
  6. Protocol · 5Three surfaces: tools act, resources inform, prompts guide
  7. Protocol · 6A first MCP server: typed input, deterministic data, the raw exchange
  8. Protocol · 7Java and the SDKs: typed DTOs, validation and interoperability
  9. Protocol · 8Local or remote: stdio, HTTP, stateless requests and availability
  10. Platform · 9The database decision: direct SQL, a service boundary or an MCP adapter
  11. Platform · 10Sharing across teams: ownership, catalogs, contracts and versions
  12. Platform · 11Who gets access: users, agents, delegation and least privilege
  13. Platform · 12Enterprise authorization: tokens, audiences, gateways and no passthrough
  14. Platform · 13The threat model: injection, poisoned tools, confused deputies and egress
  15. Platform · 14Governance: who may publish, who approves, who answers the page
  16. Operations · 15Observability and audit: what was called, by whom, and why it was allowed
  17. Operations · 16Resilience: timeouts, retries, idempotency and overload at a shared server
  18. Operations · 17Testing and evaluation: contracts, authorization matrices and injection
  19. Reference · 18Advanced MCP: long tasks, large catalogs, tenants and evolving versions
  20. Reference · 19The ecosystem: SDKs, registries, gateways, identity and telemetry
  21. Reference · 20Enterprise reference architecture: one assessment platform, four teams
  22. Reference · 21Decision playbooks: function, API or MCP, and the records that explain why
  23. ReferenceGlossary
  24. AboutAbout this site and its sources
Protocol · 8

Local or remote: stdio, HTTP, stateless requests and availability

A local server is a child process of one application; a remote server is a network service many applications share. Transports, the stateless revision, connectivity, errors and who operates what.

You will understand
What changes when an MCP server stops being a child process of one application and becomes a network service many share.
You will be able to read
A Streamable HTTP exchange: required headers, status codes, and what each one asks the client to do.
You will know
Why the stateless revision 2026-07-28 matters for load balancing, and who operates and secures each kind of server.

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):

RuleWhat 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 requestalways one JSON object (no event streams in this subset)
Every POST carries MCP-Protocol-Version, equal to the version in _metamissing or different: 400, -32020
Mcp-Method on all requests; Mcp-Name (from params.name or params.uri) on tools/call, resources/read, prompts/getmissing or different from the body: 400, -32020
An unknown method gets 404 and -32601; an unsupported version gets 400 and -32022same
An accepted notification gets 202 with no bodysame
Origin validated on every connection; present and invalid means 403; a local server should bind to 127.0.0.1allowlist 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.

  1. 2025-11-25 · protocol sessions
    1. 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.
    2. sticky routing: The session lives in one instance's memory, so the load balancer must keep a client on that instance.
    3. instance two restarts: A terminated session must be answered with 404.
    4. 404, initialize again: The client must start a new session with a new initialize request before it can continue.
  2. 2026-07-28 · stateless requests
    1. 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.
    2. any instance: The server must not rely on earlier requests for version, capabilities or identity, so any healthy instance can answer.
    3. instance two restarts: Only requests in flight on instance two are lost.
    4. 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.

StageProcess / network hopsTrust boundariesIdentity at the callWho deploys
4. Local MCP server (stdio)1 / 0host to server process (same OS user); server to databasethe OS process owner; principal from the environment variable UW_MCP_PRINCIPALthe user or consumer application owner; the server maintainer; database credentials end up on each machine
StageProcess / network hopsTrust boundariesIdentity at the callWho deploys
5. Remote MCP server (Streamable HTTP)2 / 2host to MCP server (audience https://mcp.uw.insurer.example); MCP server to the service (exchanged token, audience https://assessment-svc.internal.example); service to databaseaccess token with an audience, validated on every request; a separate downstream tokeneach 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.

MessagesRequest (host's MCP client)Answer (MCP server uw-assessment)
1, 2tools/list with no token401, WWW-Authenticate naming the protected resource metadata and scope uw.read
3, 4GET /.well-known/oauth-protected-resource200, the metadata (RFC 9728): resource, authorization server, scopes
5, 6server/discover with a token for this server200, supported versions and capabilities
7, 8tools/list as the underwriting agent200, four tools; cacheScope private, ttlMs 300000
9, 10tools/call get_roof_assessment SUB-1004200, the PropertyAssessment; the server exchanged the token for a downstream one
11, 12tools/call record_underwriter_decision403 insufficient_scope, scope uw.decide, JSON-RPC error -31403
13, 14tools/call with an expired token (UW-M06)401 invalid_token, nothing executes
15, 16tools/call with a token for the CRM (UW-M04)401 invalid_token, audience
17, 18Mcp-Name header disagrees with the body400, -32020 HeaderMismatch
19, 20legacy initialize without the headers400, -32020, the supported version named
21, 22GET /mcp405 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.

AnswerWho produced itWhat the client should do
401 invalid_token or no tokenauthentication at the server or gatewayobtain a new token (the challenge names the metadata); never retry the same token
403 insufficient_scopeauthorization at the serverask for the named scope if a person may grant it (step-up); for an agent, stop: retrying cannot help
400 -32020 HeaderMismatchheader validationfix the client; this is a bug, not a transient fault
400 -32022 UnsupportedProtocolVersionversion negotiationretry once with a version from data.supported
404 -32601method dispatchthe method does not exist on this server; do not retry
405 on GETa modern server meeting a 2025-era clientswitch to the modern revision; there is no GET stream
200 with isError truethe toollet the model read it; retry only if the error says it is retryable
no answer, timeout, connection resetthe network or an instanceretry 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.

  1. Local server
    1. the host, as a child process: The client launches the server as a subprocess and closes its input to stop it.
    2. the environment: stdio does not use the HTTP authorization flow; credentials and identity come from the environment the host set.
    3. on every machine: The server process on each machine reaches the database itself, so each machine holds its credentials.
    4. one user's work: In-flight requests are lost and can be retried against the fresh process.
  2. Remote server
    1. the server maintainer: One deployment, rolled out once; several instances behind a load balancer.
    2. a token per POST: Every POST carries a bearer token for this server's audience, validated on every request, scopes checked per call.
    3. the assessment service: The MCP server exchanges the caller's token for a downstream one; only the service holds database credentials.
    4. 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.

QuestionLocal server (stage 4)Remote server (stage 5)
Who starts and stops itthe host application on each machinethe server maintainer's deployment, behind the platform team's gateway
Who updates itevery machine, at its own paceone deployment; versions roll out once
Where database credentials liveon each machine that runs itin the assessment service only; the MCP server holds none
How the caller is identifiedthe OS user and the environment the host seta token per request, audience checked, scopes per call
What a crash affectsone user's session of work; the host restarts itin-flight requests on one instance; the others continue
Who sees an audit trailwhatever that machine logsone audit store with every decision (AUD-0002 in the example's README)
Typical fitone person's private data and tools on their own machinea 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, and read_file and search_code never leave the machine. The company's code review server is remote: open_pull_request goes 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#

Exercises#

  1. 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?
  2. A gateway rate-limits by Mcp-Name and forwards to the server. A client sends Mcp-Name: search_guidance with a body calling record_recommendation. What stops the write?
  3. 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
  1. 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.
  2. The server's header validation: Mcp-Name must equal params.name, so it answers 400 -32020 and runs nothing; the gateway should also check that the protocol version requires that validation.
  3. 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.