recommend · verified 2026-09-08
which MCP server SDK and transport for a remote MCP server in TypeScript
pick MCP TypeScript SDK 1.30.0
@modelcontextprotocol/sdk 1.x with Streamable HTTP in stateless mode (`sessionIdGenerator: undefined`), one McpServer per request. It is the line every client is tested against; v2.0.0 shipped in September 2026 and splits into @modelcontextprotocol/server, /node, /express with different imports, so wait for 2.1 before moving.
traps for MCP TypeScript SDK (4)
| severity | versions | symptom and fix |
|---|---|---|
| major | >=1.0.0 <2.0.0 | Upgrading to v2 by bumping the version fails, because there is no 2.x of this package. v2 ships as separate packages, @modelcontextprotocol/client and @modelcontextprotocol/server, not as a major of @modelcontextprotocol/sdk. Install the new package and follow the v2 upgrade guide; 1.x keeps getting bug and security fixes for at least six months after the v2 release. evidence |
| major | >=1.25.0 <2.0.0 | registerTool inputSchema written as z.object(...) is accepted by TypeScript but tools/list shows an empty schema. In 1.x pass the raw zod shape `{ a: z.string() }` as `inputSchema`, not `z.object({...})`; the object form is the v2 API. |
| minor | >=1.0.0 | A client written for an SSE endpoint cannot connect to a server built this year. The 2026-07-28 spec defines two standard bindings, stdio and Streamable HTTP, where each message is an HTTP POST to one endpoint and replies come back as JSON or a request-scoped SSE stream. Point the client at the single MCP endpoint with the Streamable HTTP transport rather than an /sse path. evidence |
| minor | >=1.25.0 <2.0.0 | The SDK imports zod/v4 internally; a project on zod 3.24 or older fails at import. Install zod ^3.25 (which ships zod/v3 and zod/v4 entry points) or zod ^4. |
what your agent receives
VERDICT which MCP server SDK and transport for a remote MCP server in TypeScript PICK MCP TypeScript SDK 1.30.0: @modelcontextprotocol/sdk 1.x with Streamable HTTP in stateless mode (`sessionIdGenerator: undefined`), one McpServer per request. It is the line every client is tested against; v2.0.0 shipped in September 2026 and splits into @modelcontextprotocol/server, /node, /express with different imports, so wait for 2.1 before moving. TRAPS (4) [876cfb42] major: Upgrading to v2 by bumping the version fails, because there is no 2.x of this package. [fb40a653] major: registerTool inputSchema written as z.object(...) is accepted by TypeScript but tools/list shows an empty schema. [0de0fa09] minor: A client written for an SSE endpoint cannot connect to a server built this year. [abab7e80] minor: The SDK imports zod/v4 internally; a project on zod 3.24 or older fails at import. VERIFIED 2026-09-08 by wellworn reviewer · recheck 2027-01-06 · sources 2