Overview

The MCP TypeScript SDK repository is the TypeScript implementation of the Model Context Protocol, an open standard for connecting AI applications to the systems where tools, data, and prompt templates live. The repository is currently centered on the v2 SDK beta on the main branch, with the README explicitly calling out that v2 implements the 2026-07-28 MCP specification candidate and that v1.x remains the supported production line until v2 stabilizes. For a new reader, the most important orientation is that MCP separates the host or model-facing application from the server that exposes useful context. A developer either builds a server that offers capabilities to hosts, or builds a client that connects to MCP servers and invokes those capabilities. Sources: README.md, docs/index.md

Purpose and Scope

Use this page as the map for deciding where to begin in the repository. If you want to expose an API, file system, database, SaaS service, or internal workflow to AI applications, start with the server path. The landing documentation describes a complete one-file server that creates an MCP server, registers a weather tool with an input schema, and serves it over standard input and output so an MCP host can launch it. If you are building an application that acts as a host or orchestration layer, start with the client path: a client connects to MCP servers, lists their tools and resources, calls methods, handles authentication, and closes the connection cleanly. Sources: docs/index.md

The repository is intentionally split by role. The README describes server libraries for tools, resources, prompts, Streamable HTTP, stdio, and authorization helpers; client libraries for transports, high-level helpers, and OAuth helpers; optional middleware packages for framework integration; and runnable examples. That split matters because v2 replaces the older monolithic package shape with side-specific packages. Most applications should install one primary package for the side of the protocol they implement, then add a middleware or runtime adapter only when they need to serve over a particular HTTP framework. Sources: README.md

The beta status should influence planning. The README asks users to open v2 feedback issues and says pull requests are limited while the 2026-07-28 specification implementation lands. That means the SDK is ready for experimentation, integration feedback, migration testing, and early application development, but teams shipping production workloads should account for the stated support window for v1.x and the possibility of v2 API changes before the stable release. The package metadata also identifies the repository root as private, versioned as an alpha of the historic SDK package, and configured as an ECMAScript module workspace requiring modern Node. Sources: README.md, package.json

Relevant Source Files

• README.md — repository-level overview, beta notice, package categories, runtime support, installation table of contents, contribution guidance, and v2 versus v1 production status.
• docs/index.md — v2 documentation landing page, first-server orientation, MCP host/server terminology, quick path selector, and recap of the core getting-started flow.
• package.json — workspace metadata, Node engine requirement, package manager pin, documentation scripts, build and test scripts, conformance commands, and repository links.

Core Primitives

The core product vocabulary begins with MCP itself. In these docs, MCP is the standard that lets AI applications connect to external systems in a consistent way. A server exposes capabilities: tools that perform actions, resources that return data, and prompts that package reusable interaction templates. A host is the AI application, such as a coding assistant, editor, desktop app, or custom product, that connects to a server and lets a model use those capabilities. The SDK gives TypeScript developers the building blocks to implement either side while preserving the protocol boundary between context provision and model interaction. Sources: README.md, docs/index.md

The central server primitive in the landing example is the high-level server object. A developer creates a server with a name and version, registers a tool by name, supplies a description and input schema, and writes an async handler that returns MCP content. The docs emphasize that the SDK validates tool calls against the supplied schema before the handler runs. That validation detail is important because it lets a server describe a contract to the host while keeping application logic focused on the requested operation. The same conceptual pattern extends to resources and prompts in the rest of the documentation spine. Sources: docs/index.md

Serving is the second primitive. The landing example uses stdio because local MCP hosts can launch a process and communicate with it over standard input and output. The README also points to Streamable HTTP and middleware packages for runtime and framework integration. In practice, stdio is the easiest path for a first local server, while Streamable HTTP is the natural path for servers deployed behind web infrastructure or shared by multiple users. Middleware packages are deliberately thin adapters: they help connect framework request and response objects to the SDK rather than adding new MCP behavior. Sources: README.md, docs/index.md

Package and Runtime Orientation

The main starting packages are the server and client packages. The official docs describe the published SDK as split packages with subpath exports, where root imports contain portable public APIs and Node-only stdio helpers live behind a stdio subpath. This overview matters because it prevents accidental coupling between browser-compatible, web-standard, and Node-only code. The README mirrors the same high-level package categories: server libraries for exposing capabilities, client libraries for connecting to servers, and middleware packages for Express, Hono, and Node HTTP integration. Sources: README.md

The root package metadata provides the repository-level runtime baseline. The workspace is an ECMAScript module project and declares Node greater than or equal to version twenty. It pins the package manager to pnpm 10.26.1 and exposes workspace scripts for building all packages, typechecking all packages, linting, running examples, building docs, generating API documentation, and running client and server conformance suites. Those scripts are not application APIs, but they are important operational signals for contributors: the repository expects coordinated workspace builds and checks rather than isolated package commands only. Sources: package.json

A useful mental model is to choose the fewest packages that match your deployment. A local tool server normally starts with the server package and a stdio serving subpath. A host implementation starts with the client package and adds transports and authentication helpers as needed. A web server adds one runtime or framework adapter if the framework’s request and response types need adaptation. A migration project may need the codemod package or the legacy server package, but those are not the default path for new v2 code. The README and landing page both steer readers toward building one side first, then adding serving or migration guidance only when the project requires it. Sources: README.md, docs/index.md

Developer Workflows

For first-time server development, follow the landing-page flow before exploring lower-level APIs. Create the server, register a tool with a schema, return content from the handler, and serve it over stdio. That path demonstrates the protocol’s most common loop: a host discovers available tools, calls one by name with structured arguments, and receives content back. The landing page’s weather example is intentionally compact because it shows the minimum viable shape without introducing HTTP sessions, authorization, caching, or middleware. Once the local version works, move to Streamable HTTP or a framework page if the server needs to run as a web service. Sources: docs/index.md

For client development, begin from the opposite side of the same boundary. The client’s job is to connect to a server, inspect the server’s advertised capabilities, call tools or read resources, and integrate the results into an application or model workflow. The repository overview distinguishes client libraries from server libraries, and the documentation landing page explicitly offers a client path for people building applications that talk to MCP servers. That separation is especially useful in larger systems where one process may be a host-facing application, another process may expose tools, and a third may proxy or gateway traffic between them. Sources: README.md, docs/index.md

For repository contributors, the package scripts show the expected verification loop. Documentation snippets can be synchronized, guide examples can be run, API docs can be generated, the VitePress site can be built, and the workspace can be typechecked, linted, built, and tested. The conformance commands are split across client and server surfaces, including draft and extension server suites. Those script names indicate that public protocol behavior is tested as a compatibility surface, not only as package-local TypeScript behavior. Before changing APIs, transports, or protocol schemas, contributors should expect to run the relevant workspace checks and docs checks. Sources: package.json

System-to-Code Mapping

The README is the broad repository contract. It tells readers what MCP is, which runtimes the SDK targets, what the major package families are, and how the v2 beta should be treated. It is the best first file for understanding repository intent, support posture, and package categories. The docs landing page is the reader journey. It turns the same concepts into an immediate task: build a server, build a client, upgrade from v1, or integrate with a framework. The package metadata is the operational map, showing the workspace’s Node requirement, scripts, package manager, repository identity, and automated verification surfaces. Sources: README.md, docs/index.md, package.json

These three files also define how to navigate the rest of the wiki. Server builders should continue to the first-server tutorial, then tools, resources, prompts, transports, and serving pages. Client builders should continue to connection, calling, OAuth, middleware, caching, roots, subscriptions, and server-request handling pages. Teams migrating from v1 should read the migration overview before relying on codemods, because the beta documentation distinguishes mechanical package and symbol rewrites from architectural changes such as adopting the 2026-07-28 protocol revision. Operators deploying HTTP servers should use the serving pages for framework-specific request handling, host validation, authorization, sessions, and scaling guidance. Sources: README.md, docs/index.md

Next Steps

Start with a task, not a package list. If your goal is to let Claude Code, VS Code, Cursor, or another MCP host use your system, build the first stdio server and register one real tool. If your goal is to build a host or integration service, build a client and connect it to an existing server before adding authentication and caching. If your goal is migration, read the v2 beta notices, run the codemod only on a clean working tree, and plan manual review for behavior changes. If your goal is contribution, use the root scripts as the checklist for docs, examples, typechecking, linting, build, tests, and conformance. Sources: README.md, docs/index.md, package.json