MCP TypeScript SDK v2 review of integration and migration

A local test of MCP SDK 2.4.0 initialization, schema validation, tool errors, resource reads and process state, with practical v1 to v2 migration boundaries.

AgentIndex · Published 2026-11-04 · Updated 2026-11-04

MCP TypeScript SDK fits teams exposing application capabilities to agents or adding MCP client support to their own products. It supplies protocol clients, servers and transports for discovery, invocation and resource access. The application still owns model selection, business permissions and the meaning of a completed task.

The most important version distinction is the package split. Current v2 uses packages including @modelcontextprotocol/server and @modelcontextprotocol/client; the older @modelcontextprotocol/sdk belongs to the v1 maintenance line. Establish that distinction before combining examples, dependencies or error-handling code.

A pinned local check

On 2026-11-04, we installed client and server 2.4.0 and used Node.js 26.6.0, Zod 4.1.12 and stdio. Our synthetic server registered an addition tool, a tool that deliberately throws, and a resource reporting how often the addition handler ran.

No model or real business service was connected. We did not test HTTP, OAuth, multi-user sessions, Bun or Deno. The checks establish whether the basic protocol connects, where invalid input is rejected, how different errors return, and what state a fresh server process starts with.

CheckObserved result
Initialization and discoveryTwo registered tools discovered
Valid arguments 2 and 3Text result 5
String supplied for a numeric argumentisError: true; addition handler did not run again
Handler deliberately throwsisError: true
Unregistered tool nameClient received a protocol exception with code -32602
List and read the resourceExpected resource and invocation count
Close and start a fresh server processInvocation count started at 0

Reading the counter through a separate resource let us check that invalid input had not reached the business handler, rather than merely observing an error message. The fresh-process result concerns local memory; it does not establish isolation in a shared database or a multi-user HTTP service. The reproducible fixture includes the server, verifier and results.

The protocol layer can be tested independently

A minimal service can register tools and their input schemas, then connect a stdio transport. A client initializes, discovers the available definitions and invokes them. Our complete addition workflow ran without a model, making this layer suitable for contract tests independent of model behavior. Official server and client introduction

That separation helps diagnose product failures. A request that never arrived, rejected parameters, a failed business operation and a successful tool call that did not complete the user's task should be distinct states. A search tool returning an empty list may be a valid result; deciding whether to reformulate the query belongs to the host.

Schema validation also does not grant permission to act. Even valid arguments need a business decision about which records the current user may access, whether writes are permitted and how duplicate writes are prevented. Keep those rules independently testable instead of treating a working protocol connection as a release criterion for the entire product.

Installing v2 and migrating an existing project

New services should install the packages needed for their roles. Clients, servers and framework-specific HTTP adapters have separate packages. V2 requires Node.js 20 or later; our check used an ESM example on Node.js 26 only. Package and runtime migration guidance

For an existing v1 application, inventory source imports, each workspace's dependency declarations and scripts that encode the old package name. Establish a real client/server call as the migration baseline, then replace components incrementally. Inspect transport adapters, registration interfaces and error types as well as package names. A migration tool cannot establish that the surrounding business logic remains correct. Complete migration guide

The differently named v1 and v2 packages can coexist during that transition. Put the boundary at a process or protocol transport, and avoid casually mixing objects constructed by the two libraries inside one process. Tests should inspect stable error fields instead of matching only message wording.

Make failure handling part of acceptance

In our fixture, invalid tool arguments and a thrown handler error both returned tool results with isError: true. An unknown tool instead made callTool throw a numeric protocol error. A caller needs both paths, plus reliable cleanup of its transport and spawned process. Client calling tutorial

The accompanying browser-harness review observed a further case: an application placed an error in JSON content while leaving the outer MCP flag false. A host must understand the business result format of the service it connects to as well as protocol-level failures. A shared protocol does not automatically normalize every application's definition of failure.

Moving beyond local stdio

A local fixture is useful for checking tool contracts before choosing an HTTP adapter and designing authentication, session lifecycle, timeouts and deployment boundaries. Do not use a fresh process's empty counter as a substitute for multi-user isolation tests. Shared state needs its own scenarios and test data.

Version selection should also account for the hosts you need to support. Pin and verify specific client/server combinations for the v1 and v2 lines. The repository's license file describes a transition toward Apache-2.0 while some existing contributions retain MIT terms; retain the applicable notices for the version you adopt. License file

For teams building an MCP service or host, the SDK provides a direct protocol foundation. People looking for an already configured agent should first choose a suitable host application. An early integration deliverable should be a small, repeatable tool fixture covering success and failure, followed by a gradual connection to real business capabilities.

Related reviews: Next AI Draw.io editing and export, browser-harness control and recovery.