MCP server project (TypeScript) · Chapter 6 of 12

Streamable HTTP

By the end of this chapter Parda's /mcp answers every request on its own: no session to start, plain JSON replies, the same answer from any machine and after any restart. It refuses requests meant for another host or sent by a web page from another site, its checks run in the right order, and the lab's inspector talks to it over HTTP with the SDK's client. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: One member at a time
  • 3 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of MCP server project (TypeScript) are free. This one comes with the all labs plan.

Why you need this

On Thursday 29 October Nikhil rehearsed Diwali week. Parda runs the API on 2 machines behind a load balancer, which sends each request to whichever machine is free, and it deploys about 5 times a day. With the MCP server as it is, about half of the assistants' requests came back 404 Session not found: the session had been started on the other machine. And every deploy restarted both machines, so every connected assistant lost its session at once.

The cause is the given transport.ts, which /mcp has used since chapter 1. initialize starts a session that lives in one process's memory. Another process has never heard of it, and a restarted one has forgotten it. This chapter takes the session out, and adds the checks a server on the network needs.

What you build: 3 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    transport.ts: one request, one server, plain JSON

    Write handleMcp(build) in src/mcp/transport.ts. It returns an Express handler that makes a new server with build() and a new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true }), closes both when the response closes (res.on('close')), connects the server to the transport and lets the transport answer: transport.handleRequest(req, res, req.body).

    The Check puts your handler on POST /mcp of an Express app of its own and sends a tools/call with no initialize before it (it must answer 200 with plain JSON and no Mcp-Session-Id), a notification (202) and a second call, and counts the servers made.

  2. Task 2

    transport.ts: only allowed callers, in order

    Write checkOrigin and mount(app, build, guards = []) in src/mcp/transport.ts. checkOrigin lets a request without an Origin header through, and otherwise answers rpcError(res, 403, "Forbidden: origin <origin> is not allowed") unless the origin's protocol and host name (no port) is in mcpConfig.allowedOrigins. mount adds app.post('/mcp', hostHeaderValidation(mcpConfig.allowedHosts), checkOrigin, ...guards, handleMcp(build)) and, for every other method, app.all('/mcp') answering rpcError 405 "Method not allowed: send each JSON-RPC message with POST".

    The Check mounts your endpoint with a guard that wants a token into an Express app of its own and sends requests without and with it, with the Host header evil.example, from the origins http://evil.example and http://localhost:5173, and a GET. Then it starts two separate whole apps, as two machines would be: initialize on the first, tools/call on the second.

  3. Task 3 · interview question

    Interview: http-client.ts, a client over HTTP

    Write openHttp(url, token, fetchFn = fetch) in src/mcp/http-client.ts. It returns an SDK Client (name parda-inspector, version 1.0.0) connected to a new StreamableHTTPClientTransport(new URL(url), { requestInit: { headers }, fetch: fetchFn }), where headers is { authorization: Bearer <token> } when there is a token and {} otherwise.

    The Check runs the whole app on a real port and lists its tools with your openHttp, then calls find_showtimes with a token through a fetch of its own that records the headers of every request sent.

    Nikhil will ask: Parda turned sessions off. What did a session give, and why can Parda do without one?

What you will learn

  • Streamable HTTP: one POST per message, and a reply as JSON or as server-sent events.
  • Sessions and Mcp-Session-Id: what the given transport did, and the real 404 after a restart.
  • Stateless: sessionIdGenerator: undefined and enableJsonResponse: true, the 202 for a notification, and the accept header.
  • One server, one transport: why every request gets its own, and the real error when two share.
  • The Host and Origin checks: what DNS rebinding is, hostHeaderValidation, your checkOrigin, and Express's order.
  • The SDK's client over HTTP: StreamableHTTPClientTransport, with a header on every request.

More in One member at a time

Build "Streamable HTTP" yourself

Parda wants AI assistants like Claude Desktop to book seats for its members, safely. You build the MCP server that lets them, and only as the member who allowed it. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of MCP server project (TypeScript) are free. This one comes with the all labs plan.