recommend · verified 2026-09-08
connecting to MCP servers from a TypeScript app or agent
pick MCP TypeScript SDK 1.30.0
The official SDK's `Client` over Streamable HTTP. On the 1.x line that is @modelcontextprotocol/sdk 1.30.0, the version every server in the wild is tested against. The 2.x line is published as a separate package, @modelcontextprotocol/client 2.0.0, implementing the 2026-07-28 spec; move when your servers do, not before, because the import paths change.
alternative · @modelcontextprotocol/client
mcp-use 2.4.3 wraps connection management, multi-server config, and agent glue if you are wiring several servers into one agent rather than talking to one.
Wins when you connect to many servers at once and want config-file setup rather than transport objects.
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 connecting to MCP servers from a TypeScript app or agent PICK MCP TypeScript SDK 1.30.0: The official SDK's `Client` over Streamable HTTP. On the 1.x line that is @modelcontextprotocol/sdk 1.30.0, the version every server in the wild is tested against. The 2.x line is published as a separate package, @modelcontextprotocol/client 2.0.0, implementing the 2026-07-28 spec; move when your servers do, not before, because the import paths change. ALT @modelcontextprotocol/client: mcp-use 2.4.3 wraps connection management, multi-server config, and agent glue if you are wiring several servers into one agent rather than talking to one.; wins when you connect to many servers at once and want config-file setup rather than transport objects 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 4