Remote MCP: the Streamable HTTP Binding, the Stateless Model and Request Metadata, OAuth 2.1 Authorization, Container Deployment

One endpoint, two ways to answer

The conclusion is simpler than most people expect: a server must provide exactly one HTTP path supporting POST, such as https://example.com/mcp. Just that one. No second path, no WebSocket, no polling endpoint.

The client-side rules are short too: every JSON-RPC message must be a new HTTP POST; the Accept header must list both application/json and text/event-stream; and the body must be a single JSON-RPC request or notification and must not be a JSON-RPC response.

On receipt the server has two cases. When the body is a notification (no id), accepting it returns 202 Accepted with no body. When it is a request, the server decides for itself which shape to return:

• Content-Type: application/json — one JSON object, done.
• Content-Type: text/event-stream — an event stream belonging to this request alone, streaming out any notifications related to this request and finally the actual response.

A client must support both, because the choice belongs to the server. This is the most easily missed rule: many home-grown clients handle only application/json and break outright against a server that streams progress.

The event stream has three hard rules. It may carry notifications/progress and notifications/message, but they must relate to the request that opened the stream; the server must never send an independent JSON-RPC request on that stream (the previous revision did this and this one forbids it, for the reason given in the next section); and the final response should terminate the stream. Two engineering recommendations are not to be skipped either: send X-Accel-Buffering: no when opening the stream, or a reverse proxy such as nginx will buffer events and deliver them together — everything works locally and in production all the progress smears into the last second; and a long-lived stream should periodically send an SSE comment line beginning with a colon as a keepalive, so intermediaries do not cut it on an idle timeout.

There is also an easily overlooked semantic: a client closing the event stream is the cancellation signal for that request. Because each request has its own response stream, disconnection is unambiguous, so HTTP needs no notifications/cancelled message at all (it is used only on stdio).

// One endpoint, two ways to answer. The only real branch is right here
async function handlePost(req, res, msg) {
  if (msg.id === undefined) {
    res.writeHead(202) // a notification: accepted means 202, with no body
    return res.end()
  }
 
  const tool = TOOLS.get(msg.params.name)
  if (!tool.streaming) {
    const result = await tool.run(msg.params.arguments)
    return sendJson(res, 200, { jsonrpc: '2.0', id: msg.id, result })
  }
 
  res.writeHead(200, {
    'content-type': 'text/event-stream',
    'cache-control': 'no-cache',
    'x-accel-buffering': 'no', // without this line nginx buffers the progress and sends it all at once
  })
  res.write(':\n\n') // a leading colon is an SSE comment line used as a keepalive; clients must ignore it
  const send = (payload) => res.write(`data: ${JSON.stringify(payload)}\n\n`)
 
  const token = msg.params._meta?.progressToken
  const result = await tool.run(msg.params.arguments, {
    // With no progressToken from the client, not one progress notification may be sent
    progress: token ? (u) => send({ jsonrpc: '2.0', method: 'notifications/progress', params: { progressToken: token, ...u } }) : undefined,
  })
  send({ jsonrpc: '2.0', id: msg.id, result })
  res.end() // the final response terminates this stream
}

# One endpoint, two ways to answer. The only real branch is right here
async def handle_post(request):
    msg = await request.json()
    if "id" not in msg:
        return Response(status_code=202)  # a notification: accepted means 202, with no body
 
    tool = TOOLS[msg["params"]["name"]]
    if not tool.streaming:
        result = await tool.run(msg["params"]["arguments"])
        return JSONResponse({"jsonrpc": "2.0", "id": msg["id"], "result": result})
 
    async def event_stream():
        yield ":\n\n"  # a leading colon is an SSE comment line used as a keepalive; clients must ignore it
        queue: asyncio.Queue = asyncio.Queue()
        token = msg["params"].get("_meta", {}).get("progressToken")
 
        def on_progress(update):  # with no progressToken, not one progress notification may be sent
            if token is not None:
                queue.put_nowait({"jsonrpc": "2.0", "method": "notifications/progress",
                                  "params": {"progressToken": token, **update}})
 
        task = asyncio.create_task(tool.run(msg["params"]["arguments"], progress=on_progress))
        while not task.done() or not queue.empty():
            with contextlib.suppress(asyncio.TimeoutError):
                yield f"data: {json.dumps(await asyncio.wait_for(queue.get(), 0.1))}\n\n"
        yield f"data: {json.dumps({'jsonrpc': '2.0', 'id': msg['id'], 'result': task.result()})}\n\n"
 
    # Without X-Accel-Buffering, nginx buffers the events and sends them together
    return StreamingResponse(event_stream(), media_type="text/event-stream",
                             headers={"cache-control": "no-cache", "x-accel-buffering": "no"})

Required headers: protocol version, method name, target name

This revision added a set of required request headers for Streamable HTTP that mirror a few key body fields onto the HTTP headers.

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

Why copy them? Because an intermediary should not have to parse the body to route. A gateway, a rate limiter, or an observability probe wanting to split by method name or rate-limit tools/call separately needs only the headers.

The crucial sentence follows: since intermediaries decide by header and the server executes by body, a disagreement between the two is a vulnerability. Picture a gateway configured with "tools/list needs no auth, tools/call does"; an attacker writes tools/list in the header and tools/call in the body and walks around it. So the spec requires that a server processing the body must validate that the header and body values agree, returning 400 Bad Request plus JSON-RPC error code -32020 (HeaderMismatch) when they do not.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32020,
    "message": "Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"
  }
}

Two more error paths are worth memorizing, because their HTTP status codes differ: a server that does not support the requested protocol version returns 400 plus -32022 (UnsupportedProtocolVersion) with the list of versions it supports; a server that does not implement the method returns 404 Not Found plus -32601. That 404 is a deliberate choice — it lets a client distinguish "this endpoint does not know this method" from "there is no MCP endpoint at this address at all."

Value encoding has one pothole: an HTTP header value may only be visible ASCII, so a tool name in Chinese cannot be represented. The spec gives a sentinel format wrapping the Base64 of the UTF-8 bytes:

Mcp-Name: =?base64?5p+l5aSp5rCU?=

A server must decode before comparing, or your own validation will call a perfectly normal request a header mismatch. This is the easiest thing to trip over in today's lab.

A word on x-mcp-header while we are here: a server marks a parameter with it in a tool's inputSchema, and the client then mirrors that value into an Mcp-Param-{Name} header so a gateway can route by parameter value (a region, say). It may only be used on primitive fields reachable from the schema root through properties. Do not mark sensitive parameters this way — once a password or a token is in a header, every hop along the way can see it.

Sessions are gone, the GET stream is gone, and stream resumption is gone

If you wrote a remote MCP server following a tutorial online, the three things below are removed in this revision — not deprecated, removed:

Protocol-level sessions and the Mcp-Session-Id header. A server no longer mints session ids and no longer terminates sessions with HTTP DELETE. Returns from listing endpoints must not vary by connection — though they may vary by the authorization the request carries, because a credential is per-request input rather than connection state.

Opening a separate long-lived GET connection. In the previous revision a client opened a GET stream to receive server-initiated messages; this revision has none. To receive change notifications, use subscriptions/listen (covered on day 3), an ordinary request whose response stream simply stays open.

Last-Event-ID stream resumption. A broken stream loses that request, and the client must resend with a new request id. Do not plan on compensating delivery; the protocol layer no longer handles it.

For a server supporting only this revision meeting older client traffic, the spec prescribes definite behavior: a GET or DELETE to the MCP endpoint returns 405 Method Not Allowed; an Mcp-Session-Id header is ignored, neither minted nor echoed; and a Last-Event-ID is ignored too, since streams are not resumable.

Three things a client has to add: manage retries itself (which brings idempotence along, and is why idempotentHint exists among the tool annotations); move subscriptions to subscriptions/listen; and use explicit handles for cross-call state, the shopping basket pattern from day 1.

What if the server needs the client's cooperation

In the previous revision, a server needing the user to fill in a form, or needing to borrow the client's model, initiated a JSON-RPC request to the client. This revision blocks that road: a server must never initiate a JSON-RPC request.

The replacement is called multi round-trip requests (MRTR): the server puts what it needs into the result it returns, the client goes and gets it, and having got it resends the original request.

sequenceDiagram
  participant U as User
  participant C as Client
  participant S as Server
  C->>S: tools/call id=1
  Note over S: attendee email missing
  S-->>C: resultType input_required<br/>inputRequests + requestState
  C->>U: pop a form
  U-->>C: fills in the email
  C->>S: tools/call id=2<br/>original args + inputResponses + requestState
  S-->>C: resultType complete

Several rules are worth pinning down. The result's resultType is "input_required", and inputRequests is a map whose keys the server chooses and whose values are one of three request objects: elicitation/create, sampling/createMessage, or roots/list. Having supplied the answers, the client must resend the original request with a different JSON-RPC id (the two are independent requests), placing the answers in inputResponses under matching keys. Only tools/call, resources/read, and prompts/get can receive such a result. A server must not send a type the client never declared in its capabilities — if the other side did not say it can pop a form, you may not ask for one.

requestState is the mechanism's key: an opaque string only the server understands, which the client must not parse, modify, or assume anything about, and must return verbatim on retry. The server signs its context into it and thereby needs no server-side storage and no sticky routing — which is exactly why the stateless design works.

The cost is that the entire security burden sits with the server. The spec is unambiguous: requestState must be treated as attacker-controlled input; whenever it affects authorization, resource access, or business logic, the server must apply integrity protection (HMAC or AEAD) and reject values that fail validation; and it should sign in the authenticated principal, a short expiry, and the originating request identifier, blocking cross-user, timeout, and cross-request replay respectively.

import crypto from 'node:crypto'
 
// The server mints it: stuffing context in means no server-side storage is needed on retry
function sign(payload) {
  const body = Buffer.from(JSON.stringify(payload)).toString('base64url')
  const mac = crypto.createHmac('sha256', SECRET).update(body).digest('base64url')
  return `${body}.${mac}`
}
 
function verify(state, expect) {
  const [body, mac] = state.split('.')
  if (!body || !mac) return null
  const want = crypto.createHmac('sha256', SECRET).update(body).digest('base64url')
  // Constant-time comparison, so returning early per byte cannot leak information
  if (mac.length !== want.length || !crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(want))) return null
 
  const p = JSON.parse(Buffer.from(body, 'base64url').toString())
  if (p.principal !== expect.principal) return null // blocks cross-user replay
  if (p.origin !== expect.origin) return null // blocks taking tool A's state to tool B
  if (p.exp < Date.now()) return null // blocks timeout replay
  return p
}

import hmac, json, time, base64, hashlib
 
def _b64(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).decode().rstrip("=")
 
 
# The server mints it: stuffing context in means no server-side storage is needed on retry
def sign(payload: dict) -> str:
    body = _b64(json.dumps(payload).encode())
    mac = _b64(hmac.new(SECRET, body.encode(), hashlib.sha256).digest())
    return f"{body}.{mac}"
 
 
def verify(state: str, expect: dict) -> dict | None:
    body, _, mac = state.partition(".")
    if not body or not mac:
        return None
    want = _b64(hmac.new(SECRET, body.encode(), hashlib.sha256).digest())
    if not hmac.compare_digest(mac, want):  # constant-time comparison from the standard library
        return None
 
    p = json.loads(base64.urlsafe_b64decode(body + "=" * (-len(body) % 4)))
    if p["principal"] != expect["principal"]:  # blocks cross-user replay
        return None
    if p["origin"] != expect["origin"]:  # blocks taking tool A's state to tool B
        return None
    if p["exp"] < time.time() * 1000:  # blocks timeout replay
        return None
    return p

The spec adds a reminder: the measures above narrow the replay window and block cross-user and cross-request reuse, but do not guarantee single use. A scenario requiring a state to be redeemed exactly once (a one-time discount, say) needs a consumption record on the server.

The OAuth 2.1 layer

Authorization is optional for MCP: the HTTP transport should follow this specification and the stdio transport should not, taking credentials from environment variables instead. That line is drawn clearly, so do not wrestle with OAuth in a local server.

The role mapping fits in one sentence: the MCP server is the OAuth 2.1 resource server and the MCP client is the OAuth 2.1 client, with the authorization server being a third party (co-located with the resource server or independent).

Four actions to remember in the flow. One, discovery: the client accesses with no token, the server returns 401 and points at the protected resource metadata's location in WWW-Authenticate; the server must implement that metadata (RFC 9728) and the client must use it to find the authorization server.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

Two, carry the resource indicator: the client must implement RFC 8707, sending a resource parameter in both the authorization request and the token request, valued as the MCP server's canonical URI, such as https://mcp.example.com/mcp (no missing scheme, no fragment, and as specific as possible). That step tells the authorization server which service the token is for, so it can write that audience into the token.

Three, audience validation, this section's most important sentence: an MCP server must validate that a token was issued specifically for it and must return 401 when validation fails; and it must accept only tokens valid for its own resource and must not accept or forward any other token.

Four, handling insufficient privilege: discovering at runtime that a scope is insufficient, it should return 403 with error="insufficient_scope" and the required scope, from which the client performs one elevation, and should take the union of the old and new scopes so raising one does not drop another.

Failing to validate the audience has a name of its own — token passthrough — and the spec lists it as an explicitly forbidden anti-pattern. It is bad in three ways: it bypasses security controls — rate limiting, request validation, and traffic monitoring usually hang off the premise that a token was issued to me, and a client bringing a token from elsewhere makes all of them idle; it breaks the audit chain — the server cannot tell which client is calling, and the identity in downstream logs is not the server that genuinely forwarded it, so after an incident nobody can reconstruct the scene; and it punches through the trust boundary — downstream grants trust on the premise that only the upstream service could hold this token, so once one service is compromised the attacker can move sideways with the same token.

Container deployment and scaling out

Back to the third question from the first section: how many of me there are.

Statelessness pays out in full here: nothing at the protocol level needs sharing between replicas. No session table, no sticky routing, no connection affinity configuration. One client sending three requests to three different replicas gets identical results. That is this revision's most tangible benefit, and the reason it is worth paying for repeating the version and capability blocks in every request.

services:
  mcp-a:
    build: .
    ports: ['3034:3034']
    environment:
      # The only thing that must be shared is the signing key: a requestState signed by A must verify on B
      REQUEST_STATE_SECRET: shared-dev-secret
    stop_grace_period: 10s
  mcp-b:
    build: .
    ports: ['4034:3034']
    environment:
      REQUEST_STATE_SECRET: shared-dev-secret
    stop_grace_period: 10s

Three operational matters to handle in passing. The health check needs its own path and cannot hit the MCP endpoint, which accepts only POST and answers a GET with 405. Graceful shutdown has to actually wait: on SIGTERM, stop accepting new connections first and then let in-flight requests finish; an MCP tool call routinely takes tens of seconds, so stop_grace_period must exceed the longest tool. Bind 0.0.0.0 inside a container and 127.0.0.1 on bare metal, and do not mix the two up.

One pothole to close on: ordinary requests need no connection affinity, but that long-lived subscriptions/listen stream is still a stateful connection — when it drops, the client has to resubscribe. So the load balancer's idle timeout must exceed the keepalive interval, and a rolling deploy has to accept that subscriptions break once. Stateless describes the protocol, not the TCP connection.

Source Reading

Hands-On Lab

Today's lab deliberately avoids the official SDK: the JavaScript SDK through 1.30.0 still implements the previous transport, and following it would teach you sessions and the GET stream all over again. The hand-written endpoint is only about two hundred lines with comments, and every MUST in the spec maps onto it at a glance. Run as-is, starter shows 3 green and 5 red, and your job is turning those 5 green.

1. Read the solution's server.ts first, finding origin validation, header validation, and the two response branches for JSON and the event stream.
2. Complete the header-body consistency check in the starter's checkHeaders, run the self-test, and watch items 3 and 4 go from red to green.
3. Complete the event stream branch, send one slow tool call by hand with curl and -N, and watch the progress appear one line at a time rather than all at the end.
4. Complete the meeting-booking tool's multi-round-trip return and then the requestState signature verification, turning items 7 and 8 green.
5. Bring up two replicas with the compose file in the lab root, send the same curl to 3034 and 4034, and confirm identical returns.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward the trade-offs of stateless transport, header-body consistency, and token audience validation. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Implement a Streamable HTTP server with a single POST endpoint that returns JSON or an event stream as needed
• State how a client must change now that sessions, the GET stream, and stream resumption are gone in this version
• Explain the token audience validation an MCP server must do as a protected resource, and what happens if it doesn't
• Write the three required headers from memory, and which error code a header-body mismatch returns
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D5) we move to the other side of the table and hand-write an MCP client. The order is again deliberate: only after implementing the server's two response shapes, the required headers, and multi round-trip requests do you know how many situations the client side must handle. Today you wrote what a server may return; tomorrow you write what a client must catch every one of — including the name collision that inevitably appears when merging several servers' tools for the model.