The Model Context Protocol TypeScript SDK is undergoing a ground-up rewrite. The v2 branch carries a pre-alpha warning, v1.x remains the production recommendation, and the maintainers promise a stable release in Q1 2026 with six months of v1 support afterward. This migration window creates a natural experiment: what architectural decisions matter enough to break compatibility?
The SDK sits at 12,498 stars and trending #6 in TypeScript. It’s the reference implementation for a protocol that separates LLM context providers (tools, resources, prompts) from the orchestration layer. The v2 rewrite exposes three design tensions that apply to any agent-to-tool protocol: package boundaries, validation portability, and transport surface area.
Split Package Architecture
v2 splits the monolith into @modelcontextprotocol/server and @modelcontextprotocol/client. This isn’t cosmetic. It’s a boundary enforcement mechanism.
Server package responsibilities:
- Tool, resource, and prompt registration
- Stdio and Streamable HTTP transports
- Auth helpers for inbound requests
Client package responsibilities:
- Transport abstraction for connecting to servers
- High-level helpers for tool invocation
- OAuth helpers for agent-to-service credential flows
The split forces you to declare whether you’re building a tool provider or an orchestrator. You can’t accidentally leak server internals into client code or vice versa. This matters when you’re running agent infrastructure across trust boundaries. A client library that imports server validation logic creates a dependency chain that complicates sandboxing and increases attack surface.
The practical consequence: if you’re building a tool that an agent calls, you only pull in the server package. If you’re building the agent harness, you only pull in the client package. The dependency graph stays clean.
Standard Schema Adoption
v2 replaces hardcoded validation with Standard Schema, a compatibility layer that works with Zod v4, Valibot, ArkType, and any library that implements the spec.
This is a portability play. Tool definitions in v1 were tied to a specific validation library. If your org standardized on Valibot or ArkType, you had to write adapters. v2 lets you bring your own validator as long as it speaks Standard Schema.
Why this matters for agent protocols:
Tool schemas are contracts. They define what an agent can pass to a tool and what it gets back. Hardcoding the validation library means every tool provider must adopt the same dependency. Standard Schema decouples the contract from the implementation.
The trade-off: you lose tight integration with a single validator’s features. Zod’s .refine() or Valibot’s .pipe() might not map cleanly to Standard Schema’s lowest common denominator. You gain ecosystem compatibility at the cost of validator-specific ergonomics.
Transport Abstractions and Middleware
v2 ships stdio and Streamable HTTP transports in the core packages, plus optional middleware for Express, Hono, and Node.js HTTP. This reveals a deployment assumption: stdio isn’t enough.
Stdio transport:
- Process-to-process communication
- Suitable for local tool invocation
- No network stack, no auth layer
Streamable HTTP transport:
- Long-running agent sessions
- Supports OAuth flows
- Requires reverse proxy or API gateway in production
The middleware packages exist because HTTP-based tools need to integrate with existing web frameworks. If you’re exposing a tool via Express, you don’t want to rewrite your routing layer. The middleware adapts MCP’s transport interface to the framework’s request/response model.
| Transport | Use Case | Auth Model | Failure Mode |
|---|---|---|---|
| Stdio | Local tools, single-process agents | None (process isolation) | Process crash kills tool |
| Streamable HTTP | Multi-tenant agents, remote tools | OAuth, bearer tokens | Network partition, timeout |
| Express middleware | Existing HTTP APIs | Framework-native (passport, etc.) | Framework-specific bugs |
| Hono middleware | Edge runtime tools | Edge-compatible auth | Cold start latency |
The cross-runtime support (Node.js, Bun, Deno) signals that MCP is targeting both traditional server deployments and edge functions. Deno’s security model and Bun’s performance characteristics create different constraints for tool execution.
Observability Gaps
The SDK doesn’t ship built-in observability. No structured logging, no trace context propagation, no metrics collection. This is intentional: the protocol layer stays thin, and you bring your own instrumentation.
What you need to add:
- Request IDs for correlating tool calls across transports
- Latency histograms for tool execution time
- Error rate tracking per tool
- Schema validation failure logs
The OAuth helpers in the client library handle credential flows, but they don’t log token refresh failures or rate limit hits. You need to wrap the client with your own retry logic and observability hooks.
Migration Path
The six-month support window after v2 ships creates a forcing function. If you’re running v1 in production, you have until roughly Q3 2026 to migrate. The breaking changes cluster around three areas:
- Package imports:
@modelcontextprotocol/sdkbecomes@modelcontextprotocol/serveror@modelcontextprotocol/client - Validation: Hardcoded Zod schemas need Standard Schema wrappers
- Transport configuration: HTTP transport setup changes to support streaming
The examples directory in the repo shows migration patterns, but there’s no automated codemod. You’re rewriting imports and validation logic by hand.
Security Boundaries
The split package model helps with sandboxing, but it doesn’t solve the tool execution problem. If an agent calls a tool that runs arbitrary code, you need process isolation or a WebAssembly sandbox. MCP provides the protocol, not the runtime.
Attack vectors to consider:
- Tool schema injection (malformed Standard Schema definitions)
- Credential leakage via OAuth helpers (token storage in logs)
- Denial of service via long-running tool calls (no built-in timeout enforcement)
The stdio transport assumes trusted processes. The HTTP transport assumes you’ve configured TLS and auth correctly. The SDK doesn’t enforce these constraints.
Code Example: Standard Schema Tool Definition
import { Server } from '@modelcontextprotocol/server';
import { z } from 'zod';
const server = new Server({
name: 'example-tools',
version: '1.0.0',
});
// v2 uses Standard Schema, Zod v4 implements it natively
const weatherSchema = z.object({
location: z.string(),
units: z.enum(['celsius', 'fahrenheit']).optional(),
});
server.tool({
name: 'get_weather',
description: 'Fetch current weather for a location',
inputSchema: weatherSchema,
handler: async (input) => {
// input is typed from weatherSchema
const { location, units = 'celsius' } = input;
// Tool implementation here
return {
temperature: 22,
conditions: 'sunny',
units,
};
},
});
// Start stdio transport
server.connect();The inputSchema field accepts any Standard Schema implementation. Swap Zod for Valibot without changing the server setup. The handler receives typed input based on the schema.
Technical Verdict
Use MCP TypeScript SDK v2 if:
- You’re starting a new agent project and can tolerate pre-alpha instability
- You need cross-runtime support (Node.js, Bun, Deno)
- Your org has standardized on a non-Zod validator and wants native integration
- You’re building tools that need HTTP transport for remote invocation
Avoid it if:
- You need production stability before Q1 2026
- You’re running v1 and don’t have bandwidth for a six-month migration
- You need built-in observability without custom instrumentation
- You require runtime sandboxing or execution isolation (MCP doesn’t provide this)
The v2 rewrite shows that agent protocols are moving from monolithic SDKs to composable layers. Split packages enforce boundaries, Standard Schema enables validator portability, and multiple transports acknowledge that stdio isn’t sufficient for distributed agent systems. The pre-alpha label is honest: this is infrastructure under construction, not a finished product.