Packages and Installation

Purpose and Scope

Use this page to choose the smallest install set for a TypeScript MCP project. The v2 SDK is split by protocol role: a server package for exposing tools, resources, prompts, and serving surfaces, and a client package for connecting to MCP servers and invoking what they advertise. Most applications start with exactly one side of that split. A local host, gateway, integration test, or development tool that both exposes and consumes MCP installs both. The repository README frames this branch as v2 beta, with v1.x still the supported production line during the 2026-07-28 specification rollout.

Sources: README.md, package.json

The practical rule is to install the package that owns the public object you construct first. Server builders begin with the server package and add a serving entry point such as stdio or HTTP. Client builders begin with the client package and then choose a transport. The client docs consistently show one connected Client per server, created with a name and version, then connected through a transport such as Streamable HTTP, stdio, SSE fallback, or in-memory test transport. That sequencing matters because capabilities, instructions, and protocol version are only available after the handshake completes.

Sources: docs/clients/connect.md

Relevant Source Files

• docs/clients/middleware.md — explains that client request middleware is exported from the client package and is different from server framework middleware packages.
• docs/clients/caching.md — documents client response cache options, cache modes, custom stores, and cache partitioning configured through Client options.
• docs/clients/calling.md — shows the high-level client verbs that justify installing the client package: listing tools, calling tools, reading resources, prompts, pagination, and structured output.
• docs/clients/connect.md — grounds the client constructor, transports, stdio subpath, SSE fallback, handshake accessors, and clean shutdown behavior.
• docs/clients/machine-auth.md — shows machine-oriented auth providers exported from the client package and passed to Streamable HTTP transports.
• docs/clients/oauth.md — shows user OAuth provider types, UnauthorizedError behavior, and transport authProvider wiring from the client package.
• README.md — summarizes the v2 beta branch, split server and client packages, optional middleware packages, supported runtimes, and repository intent.
• package.json — records the monorepo metadata, Node engine requirement, workspace package usage, package manager, and development scripts.

Choose the Package for Your Role

Install the server package when your process is the MCP server. That side registers capabilities and answers client requests; it is the correct starting point for tool, resource, prompt, sampling, elicitation, logging, and serving work. Install the client package when your process connects outward to an MCP endpoint. The client package owns the Client class, HTTP transport, SSE transport, middleware helpers, caching configuration, and authentication providers used throughout the client guides. A process that acts as a bridge or gateway may depend on both sides, but ordinary applications should resist pulling in both until they actually need both responsibilities.

Sources: README.md, docs/clients/connect.md, docs/clients/calling.md

The official package split also distinguishes framework adapters from client request middleware. The repository README describes optional middleware packages for runtime or web framework wiring, such as Node.js HTTP, Express, and Hono helpers. Those packages help mount a server handler safely in a specific HTTP environment; they are not the same thing as client middleware. Client middleware wraps the fetch used by an HTTP client transport, sees outbound requests and inbound responses, and is composed with helpers such as createMiddleware, applyMiddlewares, withLogging, and withOAuth inside the client package.

Sources: README.md, docs/clients/middleware.md

Install Commands and Subpath Exports

A minimal server-side application normally installs the server package, while a minimal client-side application installs the client package. The official docs describe the SDK as published as nine npm packages, with most projects installing exactly one. The root package entry is intended for broadly usable APIs, while subpath exports hold environment-specific entry points. For example, stdio client transport is intentionally imported from the client stdio subpath because it spawns a child process and therefore belongs in Node-only code rather than in code intended for browsers, Workers, Bun, or Deno-compatible HTTP usage.

npm install @modelcontextprotocol/server
npm install @modelcontextprotocol/client

import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

Sources: docs/clients/connect.md, README.md

Keep subpath imports meaningful in application architecture. If a file imports stdio transport, treat that file as process-management code and keep it away from browser bundles or generic shared modules. If a file imports only Client and Streamable HTTP transport, it can remain focused on the protocol session instead of local process spawning. The same convention applies on the server side: stdio serving and HTTP serving should live in the runtime boundary layer, while tool and resource definitions can remain transport-independent. This makes it easier to swap transports, run tests in memory, or add a web adapter later.

Sources: docs/clients/connect.md

Runtime, TypeScript, and v2 Migration Notes

The repository package metadata declares a Node engine requirement of at least version twenty for the monorepo. The README also states that the SDK runs on Node.js, Bun, and Deno, while the stdio examples make clear that spawning a local process is Node-oriented behavior exposed behind the stdio subpath. Treat TypeScript configuration as part of the package boundary: import from published package roots or documented subpaths rather than deep internal files, and let the package exports map decide what is stable. The repository uses pnpm workspaces internally, but consuming applications install the published packages from npm.

Sources: README.md, package.json, docs/clients/connect.md

Coming from the v1 package, the most visible installation change is import-path movement. The client connect guide notes that Client and transport class names remain recognizable, but their paths move to the split client package and its stdio subpath. The official package docs also identify server-legacy and codemod packages as migration surfaces for v1 code. Use the codemod for broad import rewriting, then review runtime boundaries manually, especially where previous code mixed browser-safe client imports with local stdio process management or where a single package import previously supplied both client and server concepts.

Sources: docs/clients/connect.md, README.md

Client-Side Options That Influence Dependencies

The client package is not only a transport package; it also carries higher-level behavior that can remove the need for extra libraries in simple integrations. Once connected, the client guide shows listTools, callTool, listResources, readResource, prompt listing, automatic pagination, structured output handling, and capability introspection. The calling guide also documents important behavior differences: failed tool calls can be ordinary results marked with isError, while protocol-level failures throw. That means application code should model both result validation and exception handling before deciding to wrap the SDK with another abstraction.

Sources: docs/clients/calling.md, docs/clients/connect.md

Caching, authentication, and middleware are configured at the client and transport layer rather than as separate runtime packages. Every Client holds a response cache, and cacheable calls honor server hints with per-call cache modes such as use, refresh, and bypass. A custom responseCacheStore can be shared across clients, and cachePartition separates principals when one backing store serves multiple users. For HTTP authentication, user OAuth uses an OAuthClientProvider passed as authProvider, while machine authentication can use client credentials, bearer tokens, private-key JWT, or cross-app access providers through the same transport option.

Sources: docs/clients/caching.md, docs/clients/oauth.md, docs/clients/machine-auth.md

Package Selection Reference

Next Steps

After choosing packages, follow the role-specific guide rather than continuing to design from package names alone. Server authors should build the first server, then choose stdio, Streamable HTTP, or a framework adapter based on where the host will run. Client authors should connect first, inspect server capabilities and instructions, and only then add calling, caching, middleware, OAuth, or machine authentication. If you are upgrading, run the migration path early in a branch and review subpath imports carefully; that catches most packaging problems before they become runtime transport failures.