Ship an MCP Server: TypeScript and Python, Measured

An incident log. Three tools, because Chapter 18's split between reads and writes has to be visible: search_incidents reads, open_incident writes and hands back a handle, resolve_incident takes that handle and closes. One resource, incidents://open, because reading the current list is something the application attaches. One prompt, postmortem, because "write this up" is a person's slash command. That is Chapter 26's control hierarchy — model, application, person — turned into five registrations.

The handle matters more than it looks. Chapter 26 broke a toy calendar by keeping its state in a module-level array: the protocol has no session, so a creation tool returns an opaque identifier and every later call takes it as an ordinary argument. Nothing in either file assumes the caller is the process that opened it.

Here is the same tool in both languages, registered side by side:

server.registerTool(
  "resolve_incident",
  {
    description:
      "Close an incident by handle and record its cause.",
    inputSchema: {
      id: z.string().describe(
        "The handle returned by open_incident, e.g. INC-3."),
      cause: z.string().describe(
        "One sentence. What actually broke."),
    },
    annotations: {
      readOnlyHint: false,
      destructiveHint: true,
      idempotentHint: true,
    },
  },
  async ({ id, cause }) => {
    const at = OPEN.findIndex((i) => i.id === id);
    if (at < 0) {
      return { isError: true, content: [{ type: "text",
        text: `No open incident ${id}. ` +
              `Call search_incidents first.` }] };
    }
    const [done] = OPEN.splice(at, 1);
    return { content: [{ type: "text",
      text: JSON.stringify({ ...done, cause }) }] };
  },
);

@server.tool(
    description=
      "Close an incident by handle and record its cause.",
    annotations=ToolAnnotations(
        readOnlyHint=False,
        destructiveHint=True,
        idempotentHint=True,
    ),
)
def resolve_incident(
    id: Annotated[str, Field(description=
        "The handle returned by open_incident, e.g. INC-3.")],
    cause: Annotated[str, Field(description=
        "One sentence. What actually broke.")],
) -> Incident:
    for at, i in enumerate(OPEN):
        if i["id"] == id:
            done = OPEN.pop(at)
            return {**done, "cause": cause}
    raise ValueError(
        f"No open incident {id}. Call search_incidents first.")

Read what is the same first, because that is the finding. Both declare a name, a description, two described string arguments and three annotations; both are one function; neither mentions JSON-RPC, framing, stdout or a protocol version. The two SDKs converged on the same shape, which is what "Tier 1" is supposed to mean.¹

Two differences are real and both come back later. TypeScript describes arguments with a schema library — Zod here — and the schema is a value you write. Python describes them with the function's own type hints and reads them at import time, which is why it knows things about the function that the TypeScript file never told it. And the error path: TypeScript returns a tool result with isError, Python raises. Hold on to that.

The other four registrations differ in nothing structural. The resource is server.registerResource("open-incidents", "incidents://open", …) against @server.resource("incidents://open", …); the prompt is registerPrompt against @server.prompt. The last line of each file is the transport: await server.connect(new StdioServerTransport()) against server.run().

Whole files: 81 non-blank lines and 3,060 bytes of TypeScript against 63 and 2,555. Take that with the salt it deserves — line counts measure a formatter as much as a language, which is why neither number is in the headline table below.

The proof that the language is invisible is one client run twice, in eleven lines:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const client = new Client({ name: "incident-cli", version: "1.0.0" });
await client.connect(new StdioClientTransport({
  command: process.argv[2], args: process.argv.slice(3) }));

const { tools } = await client.listTools();
console.log("tools:", tools.map((t) => t.name).join(", "));

const opened = await client.callTool({ name: "open_incident",
  arguments: { title: "Queue backed up", severity: "sev2" } });
console.log("open_incident ->", JSON.stringify(opened.content));

Point it at each server in turn. Real output, trimmed:

$ node client.ts node incidents.ts
tools: search_incidents, open_incident, resolve_incident
open_incident -> [{"type":"text","text":"{\"id\":\"INC-3\"}"}]

$ node client.ts ./py/.venv/bin/python ./py/incidents.py
tools: search_incidents, open_incident, resolve_incident
open_incident -> [{"type":"text","text":"{\n  \"id\": \"INC-3\"\n}"}]

Same tools, same order, same handle. A TypeScript client cannot tell what the server is written in, and it never asks. That is the whole promise of a protocol, holding.

Now look at the whitespace in the second result, because it is not cosmetic: the Python SDK serialises payloads with pydantic_core.to_json(result, fallback=str, indent=2). On the resource read with two incidents in the list, the TypeScript body is 136 characters and 37 o200k_base tokens; the Python body is 185 and 62. Sixty-eight per cent more tokens for identical rows, paid by whoever reads the resource into a prompt, every time.

The catalogue has the same story with a larger cause. Both servers, same three tools, tools/list weighed key by key:

Python's input schemas are cheaper — TypeScript's Zod bridge stamps a $schema and an additionalProperties on each one. The entire 138-token gap is an output schema that nobody wrote. resolve_incident is annotated -> Incident, so the SDK derived a JSON Schema for the return type and shipped it. It is genuinely useful — it is what lets a client validate structuredContent — and it is 187 tokens of your context window arriving because of a type hint. Chapter 24's rule about definitions crowding out the material that matters applies to schemas you did not know you had.

The two error paths above are not a style choice. Give each server a tool that fails the way a real integration fails, and read what reaches the model.

TypeScript  {"content":[{"type":"text","text":
              "connect ECONNREFUSED 10.0.3.7:5432 (db-prod-eu, user=reporting)"}],
             "isError":true}

Python      {"content":[{"text":"Error executing tool boom","type":"text"}],
             "isError":true}

The TypeScript SDK put an internal address, a port, a database name and a service account into the model's context. The Python SDK put none of it there; the traceback went to stderr and stayed on the server.

Neither is a bug. Both are decisions, and the Python one is written down in its own docstring: a ToolError is "a failure you anticipated" and its message is returned "in content for the model to read"; anything else "is treated as a crash: the model sees only Error executing tool <name>, and the server logs the traceback at ERROR". The class for the crash case says the rest out loud — "nothing from the original reaches the client".

Both behaviours are wrong half the time. Chapter 18 argued that a validation error should come back as a tool result the model can read and correct, because that is the highest-leverage line in most integrations; on the Python side that requires raising ToolError explicitly, and a bare ValueError throws the useful sentence away. Chapter 30's argument runs the other way: everything a tool returns lands in a context a later prompt injection can try to read back out, and an unreviewed exception string is the least-audited text in your system.

The rule that survives both: decide, per tool, what a failure is allowed to say, and write that string yourself. Never let an exception's default text decide, in either language.

The official tutorial states the rule without hedging: "For STDIO-based servers: Never write to stdout. Writing to stdout will corrupt the JSON-RPC messages and break your server. The print() function writes to stdout by default, so keep it out of a STDIO server entirely."¹ Chapter 26 quoted the normative version — a server "MUST NOT write anything to its stdout that is not a valid MCP message".²

Add one line to each server and read the raw stream:

TypeScript  incidents server starting
            {"result":{"protocolVersion":"2025-11-25", … },"jsonrpc":"2.0","id":1}

Python      {"jsonrpc":"2.0","id":1,"result":{ … }}
            incidents server starting

The Python one is worse, and the reason is not MCP. A process whose stdout is a pipe rather than a terminal gets a block-buffered stream, so the stray line is flushed whenever the buffer decides — here, at exit, after a response it was written before. The corruption does not appear where the bug is. Add flush=True, or a library that flushes, and it moves.

Then the part that explains why this ships. Feed the broken server to three clients:

naive parser, dirty server   SyntaxError: Unexpected token 'i',
                             "incidents "... is not valid JSON
SDK client, dirty server     tools: search_incidents, open_incident, resolve_incident
MCP Inspector, dirty server  full catalogue, no warning

The seven-line parser dies immediately. The official client and the Inspector both shrug — they skip the line and carry on. A rule that only breaks the clients nobody uses is a rule that reaches production intact, which is why it is worth breaking on purpose here rather than in a customer's log.

The Inspector's CLI mode is the half that gets forgotten: npx @modelcontextprotocol/inspector --cli <command> --method tools/list prints a catalogue and exits, which makes it scriptable in a way the browser UI is not.³

Both SDKs installed clean, into their own directories, nothing shared:

Every row surprises in a different direction, which is why the comparison is worth running rather than assuming.

TypeScript installs more than three times the packages and less than a third of the bytes. 94 dependencies is the npm ecosystem being itself — fast-deep-equal, es-errors, dunder-proto. Python's 28 are fewer and enormous: cryptography, pydantic-core and uvicorn are compiled artefacts. If your instinct is that dependency count is what to worry about, this row is the counter-example.

Python's interpreter starts faster than Node's, and it is not close — 11.1 ms against 19.4 ms on an empty program. So the 565 ms in the cold-start row is not the language. It is the SDK, and the loaded-packages row says why:

TypeScript   8 of 94   sdk, zod, zod-to-json-schema, ajv, ajv-formats,
                       fast-deep-equal, fast-uri, json-schema-traverse

Python      18 of 28   mcp, mcp_types, pydantic, pydantic_core, anyio,
                       starlette, uvicorn, sse_starlette, httpx2,
                       cryptography, _cffi_backend, opentelemetry, click, …

A server whose only I/O is a pipe imports an ASGI web server, an HTTP client and a TLS library before it reads its first line. The TypeScript SDK ships Express, Hono, jose and eventsource too — they sit on disk unread, because the package boundary keeps them out of a server/stdio.js import. Python's package is one import graph, so import mcp is all of it: python -X importtime attributes 727 ms to import mcp.server.mcpserver — a figure measured under the import profiler, which is why it comes out above the 709 ms the unprofiled run takes from spawn to answer — and 269 of them to the mcp.types subtree alone — the wire types are Pydantic models, one class per protocol message per revision, and building them is work done at import. That is a design trade, not sloppiness — eager imports are why the Python SDK can hand you run(transport="streamable-http") on the next line without a second install.

And then the last row of the opening block undoes the argument. Package the TypeScript server properly — a bin entry, a shebang, npm link, nothing to download — and launch it through npx with --no-install, which is how a published stdio server is actually started:

node ./incidents.js       144.5 ms
npx incidents-mcp         712.6 ms      (+568.1 ms of launcher)
python incidents.py       709.4 ms

The launcher costs 568 ms per start — four and a half times the entire TypeScript SDK import — and it is paid every launch, because an MCP host starts a stdio server by running that command. So the honest form of "TypeScript starts five times faster" is: it does, until you distribute it the normal way. The same caveat presumably applies to uvx; this machine had no uv installed, so that row does not exist. Nothing unmeasured goes in the table.

Chapter 26 covered stdio's framing. Two things it left for here.

The first: running a server with npx or uvx is the stdio transport. There is no separate "package mode". A host's configuration names a command and arguments; the host spawns it and talks over the pipes. Which is why "how do I distribute this" and "which transport does it speak" are one question locally, and why the launcher's cost belongs in a chapter about shipping.

The second: stdio has no authorization section at all, and the specification says so in one line — implementations using stdio "SHOULD NOT follow this specification, and instead retrieve credentials from the environment".⁴ Its security model is the operating system's, and so is its limit: a local subprocess serves exactly one machine and one user.

The other live transport is Streamable HTTP: a single endpoint that accepts POST, one HTTP request per JSON-RPC message, and an Accept header that must list both application/json and text/event-stream because the server picks per request which of the two it answers with.⁵ Chapter 14 parsed that event stream by hand, so nothing in the wire format is new — only what wraps it. Three obligations of the current revision are easy to miss and all three are testable:

Now the measurement that reframes the whole chapter. Send a current-revision request to each server over HTTP.

Python   200  {"result":{"resultType":"complete","cacheScope":"private","ttlMs":0,
              "tools":[…],"_meta":{"io.modelcontextprotocol/serverInfo":{…}}}}

TypeScript    {"error":{"code":-32000,"message":"Bad Request: Unsupported protocol
              version: 2026-07-28 (supported versions: 2025-11-25, 2025-06-18,
              2025-03-26, 2024-11-05, 2024-10-07)"}}

The constants agree with the behaviour: the Python SDK's LATEST_PROTOCOL_VERSION reads 2026-07-28, the TypeScript SDK's reads 2025-11-25. Send the header-mismatch request from the step above and the Python server answers 400 with error -32020 and the message "mcp-protocol-version header does not match the request envelope's protocol version"; the TypeScript SDK has no such code, because it does not implement the revision that defines it.

The page that lists both at Tier 1 also says "Each SDK provides the same functionality".¹ On the date below, for the current revision, that sentence is aspirational. Check LATEST_PROTOCOL_VERSION in the SDK you are about to install; it is one line, and the only claim in this chapter that will still matter in a year.

Move a server off your laptop and a stranger's client shows up with a token. This is the half Chapter 26 left alone and the half a multi-user product cannot skip.

The specification puts the MCP server in an OAuth 2.1 role and names it: a protected MCP server is a resource server, the client is an OAuth client, and the authorization server is somebody else's problem.⁴ From that role, four mandatory clauses, quoted whole because paraphrasing them is how the mistake gets made:

MCP servers, acting in their role as an OAuth 2.1 resource server, MUST validate access tokens as described in OAuth 2.1 Section 5.2. MCP servers MUST validate that access tokens were issued specifically for them as the intended audience, according to RFC 8707 Section 2. […] MCP clients MUST NOT send tokens to the MCP server other than ones issued by the MCP server's authorization server. MCP servers MUST only accept tokens that are valid for use with their own resources. MCP servers MUST NOT accept or transit any other tokens.⁴

"Must not accept or transit" is the anti-passthrough rule, and it is why the whole audience apparatus exists. A server that replays the bearer token it was handed at a third-party API is a confused deputy: it lends its own trust to whoever called it. The rule forbids the reuse, not just the storage.

Making that enforceable takes four RFCs, one job each.⁶ RFC 9728 is how the client finds the authorization server at all: the MCP server serves a protected-resource-metadata document and a 401 points at it. RFC 8707 is the resource parameter — the client must send the server's canonical URI in both the authorization request and the token request, "regardless of whether authorization servers support it", so the issued token names its audience. RFC 9207 closes the loop from the other side: the client records the issuer before redirecting and compares the returned iss by exact string, with no normalisation — no case folding, no default-port elision, no trailing slash. And RFC 7591, Dynamic Client Registration, is now deprecated in favour of Client ID Metadata Documents, "retained for backwards compatibility with authorization servers that do not support" them.⁴

Wire that up on both servers with a token verifier that does nothing but check the audience. The TypeScript ladder:

no token            401  WWW-Authenticate: Bearer error="invalid_token",
                         error_description="Missing Authorization header",
                         scope="incidents:read",
                         resource_metadata="…/.well-known/oauth-protected-resource/mcp"
aud=other server    401  error_description="token audience is not this server"
no exp claim        401  error_description="Token has no expiration time"
right aud, no scope 403  error="insufficient_scope", scope="incidents:read"
right aud + scope   200  {"result":{"tools":[…]}}

{"resource":"http://127.0.0.1:8931/mcp",
 "authorization_servers":["https://auth.example.com/"],
 "scopes_supported":["incidents:read","incidents:write"],
 "resource_name":"Incidents"}

Both SDKs serve that document and both point a 401 at it, which is the entire discovery story: a client that has never seen your server learns where to authenticate from a refusal. The 403 is a different animal — the token is fine, the scope is not — and the challenge names what is missing so the client can step up rather than start over.

Two rungs differ, and neither difference is in the specification. The TypeScript SDK refuses a token with no expiry claim; the Python one returns 200, because expires_at is optional on its AccessToken and None means "no opinion". And the Python 403 carries error_description="Required scope: incidents:read" without the scope parameter the specification says servers should include. A verifier is no place to accept a library default: the audience check is yours to write in either language, and so is the expiry.

One honest nit from the same run. A GET on the endpoint answered 404 on the Express wiring and 400 Bad Request: Missing session ID on the Python one, where the specification asks for 405 Method Not Allowed and where "session ID" is vocabulary this revision removed. Neither is dangerous; both are the shape of an ecosystem mid-migration.

The last piece of shipping is where you publish, and it has an answer with a number. Crawled today, every server in the official registry at its latest version:⁷

Two readings, pointing opposite ways. By published servers, npm leads 2.3 to 1 — the number people quote when they say the ecosystem is TypeScript. By downloads, Python leads: over the last thirty days mcp took 286.7 million against @modelcontextprotocol/sdk at 194.7 million, before adding fastmcp at 72.1 million.⁷ Both are Tier 1, the normative schema is a schema.ts, and the official "Build an MCP server" tutorial opens on the Python tab.¹ Whichever half of that you had in your head, the other half is also true.

And the row that matters more than either: more than half the registry — 14,696 of 28,170 — has nothing to install. Those are web services. The transport tallies agree from the other side: of 14,290 package entries, 13,787 declare stdio; of 16,640 remote entries, 15,570 declare Streamable HTTP and 1,070 still declare the deprecated HTTP+SSE. So "an MCP server is a subprocess on your laptop" describes a shrinking minority, and every one of the 14,696 needs the section above rather than an environment variable.

Read and measured on 7 September 2026, against protocol revision 2026-07-28.

One migration note that is not a number. In mcp 2.x, FastMCP was renamed MCPServer, and almost every tutorial online still opens with the old import. The SDK ships a module whose only purpose is to explain that, which is the most considerate deprecation in this chapter:

ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x,
where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import
MCPServer) and other APIs changed; see the migration guide … or pin 'mcp<2'
to keep running v1 code.

With the table in front of you, the recommendation is boring, which is a good sign.

If the server lives inside a web application you already run, write it in TypeScript. Same process, same deploy, same request handler; Streamable HTTP is an endpoint you add next to the others; and the 13.9 MiB and the 145 ms are free because the runtime was already up. That is most of the 14,696 remote servers.

If the server wraps data tooling, write it in Python. What you are exposing is pandas, a warehouse client, a notebook's worth of transforms, and a server in another language would be a subprocess call wearing a schema. Seven hundred milliseconds of import in a service that starts once is not a cost; in a subprocess a host relaunches all day, it is.

And for now, the revision row overrides both. If you need 2026-07-28 — multi-round-trip requests, resultType, cache hints, server/discover — one of the two SDKs has it today and the other does not.

You can now ship the same server in either language, defend the choice with a table instead of a preference, run it over both live transports, and hand it a token it will refuse.

What you built is still a function: a schema, an endpoint, a deterministic thing the model invokes. A whole class of knowledge does not fit that shape — how we write a postmortem, which fields our incident reports need, the order we do things in and why. It is procedure, it is prose, and forcing it into a tool description is how system prompts grow to two thousand tokens paid on every single turn whether or not the conversation is about incidents.

Chapter 28 is the other answer: a folder with a SKILL.md in it that the model reads instead of calls, loaded in three levels so that the reference material costs almost nothing until the turn it is needed. It has no main language, and that is the first thing it teaches.

Everything here was measured on 7 September 2026, on Node 22.22.3 and Python 3.14.4, against @modelcontextprotocol/sdk 1.30.0 with zod 3.25.76 and mcp 2.1.1, each installed into its own throwaway directory. Timings are medians of 25 launches, wall clock from spawn to the line carrying the tools/list response; token counts are o200k_base via tiktoken over the JSON of each definition. No paid API was called: nothing here needs a model.

The two servers are 81 and 63 non-blank lines; one of their three tools is reproduced above in both languages, and the other four registrations differ only as described. The Python SDK's error-disclosure policy is quoted from the docstrings of ToolError and UnexpectedToolError in mcp/server/mcpserver/exceptions.py; the pretty-printing default is pydantic_core.to_json(result, fallback=str, indent=2) in mcp/server/mcpserver/resources/types.py and utilities/func_metadata.py. The protocol-version constants are LATEST_PROTOCOL_VERSION in mcp_types/version.py and in the TypeScript SDK's types.js, both read from the installed packages rather than from a changelog.