Skip to content

docs: comprehensive GA pass — stable-release wording, released-spec links, install tags #2566

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
felixweinberger merged 4 commits into from
Jul 27, 2026
Merged

docs: comprehensive GA pass — stable-release wording, released-spec links, install tags #2566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
522b55c
docs: point install commands at latest ahead of the stable release
felixweinberger Jul 27, 2026
73d369f
docs: stable-release wording for the GA cut
felixweinberger Jul 27, 2026
9f034cc
docs: comprehensive GA pass — remove beta framing, point draft-spec l…
felixweinberger Jul 27, 2026
5986f9d
docs: catch the v1-site banner and one more middleware mention
felixweinberger Jul 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/v2-feedback.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ body:
- type: markdown
attributes:
value: |
Thanks for trying v2. Anything that broke, surprised you, or slowed you down is useful — API feedback is explicitly welcome while v2 is in beta.
Thanks for trying v2. Anything that broke, surprised you, or slowed you down is useful — API feedback is explicitly welcome while v2 settles.

Docs: https://ts.sdk.modelcontextprotocol.io/v2/ · Migration from v1: https://ts.sdk.modelcontextprotocol.io/v2/migration/
- type: textarea
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ By the time you open a PR, the "what" and "why" should already be settled in an

This repository has two main branches:

- **`main`** – v2 of the SDK (currently in development). This is a monorepo with split packages.
- **`main`** – v2 of the SDK (the stable release line). This is a monorepo with split packages.
- **`v1.x`** – stable v1 release. Bug fixes and patches for v1 should target this branch.

**Which branch should I use as a base?**
Expand Down
14 changes: 9 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

<!-- prettier-ignore -->
> [!IMPORTANT]
> **This is the `main` branch — v2 of the SDK, now in beta** (`@modelcontextprotocol/server`, `@modelcontextprotocol/client`), implementing the [2026-07-28 MCP spec](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/).
> **This is the `main` branch — v2 of the SDK** (`@modelcontextprotocol/server`, `@modelcontextprotocol/client`), implementing the [2026-07-28 MCP spec](https://modelcontextprotocol.io/specification/2026-07-28).
>
> **Have feedback? Please [open a v2 issue](https://github.com/modelcontextprotocol/typescript-sdk/issues/new?template=v2-feedback.yml)** — it is the most useful thing you can do for the SDK right now. The [v2 documentation](https://ts.sdk.modelcontextprotocol.io/v2/) starts with a ten-minute server tutorial.
>
> We expect a stable release alongside the full release of the 2026-07-28 spec on July 28, 2026. Until then, **v1.x remains the supported release for production**; it keeps receiving bug fixes and security updates for at least 6 months after v2 ships. v1 documentation: [ts.sdk.modelcontextprotocol.io](https://ts.sdk.modelcontextprotocol.io/) · v2: [`/v2/`](https://ts.sdk.modelcontextprotocol.io/v2/).
> **v2 is the stable release line**, released alongside the 2026-07-28 spec. v1.x continues to receive bug fixes and security updates for at least 6 months after v2's release. v1 documentation: [ts.sdk.modelcontextprotocol.io](https://ts.sdk.modelcontextprotocol.io/) · v2: [`/v2/`](https://ts.sdk.modelcontextprotocol.io/v2/).

<!-- prettier-ignore -->
> [!WARNING]
> **We're limiting pull requests to 1 per new contributor while we land the [2026-07-28 spec](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) implementation.**
> **We're limiting pull requests to 1 per new contributor while v2 settles after the [2026-07-28 spec](https://modelcontextprotocol.io/specification/2026-07-28) release.**
>
> [Issues](https://github.com/modelcontextprotocol/typescript-sdk/issues/new?template=v2-feedback.yml) are the most useful feedback right now — we'll reopen PRs as v2 stabilizes.

Expand Down Expand Up @@ -38,7 +38,7 @@

- MCP **server** libraries (tools/resources/prompts, Streamable HTTP, stdio, auth helpers)
- MCP **client** libraries (transports, high-level helpers, OAuth helpers)
- Optional **middleware packages** for specific runtimes/frameworks (Express, Hono, Node.js HTTP)
- Optional **middleware packages** for specific runtimes/frameworks (Express, Fastify, Hono, Node.js HTTP)
- Runnable **examples** (under [`examples/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples))

## Packages
Expand All @@ -58,6 +58,7 @@

- **`@modelcontextprotocol/node`**: Node.js Streamable HTTP transport wrapper for `IncomingMessage` / `ServerResponse`
- **`@modelcontextprotocol/express`**: Express helpers (app defaults + Host header validation)
- **`@modelcontextprotocol/fastify`**: Fastify helpers (app defaults + Host header validation)
- **`@modelcontextprotocol/hono`**: Hono helpers (app defaults + JSON body parsing hook + Host header validation)

## Installation
Expand All @@ -84,7 +85,7 @@

### Optional middleware packages

The SDK also publishes optional “middleware” packages that help you **wire MCP into a specific runtime or web framework** (for example Express, Hono, or Node.js `http`).
The SDK also publishes optional “middleware” packages that help you **wire MCP into a specific runtime or web framework** (for example Express, Fastify, Hono, or Node.js `http`).

Check warning on line 88 in README.md

View check run for this annotation

Claude / Claude Code Review

Last surviving Fastify omission: docs/clients/middleware.md adapter enumeration 

One framework-adapter enumeration survives the Fastify sweep: the `:::info Not the framework middleware packages` callout in `docs/clients/middleware.md` (line 29) still lists only `@modelcontextprotocol/express`, `@modelcontextprotocol/hono`, and `@modelcontextprotocol/node`, and its see-also links cover only Express and Hono. Add `@modelcontextprotocol/fastify` to the list (and optionally [Fastify](../serving/fastify.md) to the see-also links) — the callout exists precisely to enumerate which

@claude claude Bot Jul 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 One framework-adapter enumeration survives the Fastify sweep: the :::info Not the framework middleware packages callout in docs/clients/middleware.md (line 29) still lists only @modelcontextprotocol/express, @modelcontextprotocol/hono, and @modelcontextprotocol/node, and its see-also links cover only Express and Hono. Add @modelcontextprotocol/fastify to the list (and optionally Fastify to the see-also links) — the callout exists precisely to enumerate which packages carry the word "middleware", so the omission makes it factually incomplete. (Anchored here on the in-diff middleware prose; the edit target is docs/clients/middleware.md, which is not in the diff.)

Extended reasoning...

The issue. This PR's staleness sweep adds the Fastify adapter to "every package list" (the PR description's own words), and the head commit 5986f9d ("catch the v1-site banner and one more middleware mention") fixed the previously flagged README.md instance. One enumeration of the framework-adapter packages still survives without Fastify: docs/clients/middleware.md line 29, the :::info Not the framework middleware packages callout on the published v2 docs site:

The @modelcontextprotocol/express, @modelcontextprotocol/hono, and @modelcontextprotocol/node packages also carry the word "middleware" — those are server-side framework adapters for mounting a handler. See Express and Hono.

Why the list is meant to be exhaustive. Unlike the "for example Express, Fastify, Hono…" prose fixed elsewhere in this PR, this callout is not illustrative: its entire purpose is to disambiguate which packages carry the word "middleware" from the client request middleware this page documents. @modelcontextprotocol/fastify (under packages/middleware/fastify) is one of them, and a docs/serving/fastify.md page exists for the see-also link. An enumeration whose job is completeness is wrong when incomplete.

Step-by-step proof.

  1. This PR merges; the v2 docs site rebuilds from main.
  2. A reader lands on the Client middleware page and reads the callout to learn which SDK packages are framework adapters.
  3. The callout names three adapters; the reader concludes there is no Fastify adapter — while docs/serving/fastify.md, packages/middleware/README.md, the root README, and packages/server/README.md (all updated by this very PR) say there is.

Why nothing else catches it. The callout is plain prose — no lint, snippet-sync, or test validates docs enumerations. Repo-wide grep confirms this is the only remaining framework-adapter enumeration missing Fastify after 5986f9d (docs/get-started/packages.md, docs/migration/upgrade-to-v2.md, docs/serving/http.md, docs/index.md, both READMEs, and packages/middleware/README.md all include it).

Relation to earlier review comments. This is not a duplicate of the earlier README.md:101 inline comment — that site was already fixed by head commit 5986f9d. This is a different file the same sweep missed; fixing README.md does not fix this line. It matches REVIEW.md's Completeness recurring catch: "when a PR replaces a pattern, grep for surviving instances of the old form."

Fix. In docs/clients/middleware.md line 29, change the enumeration to "The @modelcontextprotocol/express, @modelcontextprotocol/fastify, @modelcontextprotocol/hono, and @modelcontextprotocol/node packages…" and optionally extend the see-also to "See Express, Fastify and Hono."

Severity. Nit: this is docs-site prose, rebuilt continuously from main, so a one-line follow-up commit corrects it with no irreversible artifact (unlike the npm-tarball READMEs). Nothing breaks if it merges as-is — it just leaves the GA sweep slightly short of its own stated scope.


These packages are intentionally thin adapters and should not introduce additional MCP features or business logic. See [`packages/middleware/README.md`](packages/middleware/README.md) for details.

Expand All @@ -95,6 +96,9 @@
# Express integration:
npm install @modelcontextprotocol/express express

# Fastify integration:
npm install @modelcontextprotocol/fastify fastify

Comment thread
claude[bot] marked this conversation as resolved.
# Hono integration:
npm install @modelcontextprotocol/hono hono
```
Expand Down
2 changes: 1 addition & 1 deletion docs/.vitepress/llms.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ export function generateLlmsArtifacts(docsDir: string, outDir: string, site: str
const header = [
'# MCP TypeScript SDK',
'',
'> The official TypeScript SDK for the Model Context Protocol (MCP): build MCP servers and clients on Node.js, Bun, Deno, and Workers. This is the v2 beta documentation, tracking the 2026-07-28 spec revision.',
'> The official TypeScript SDK for the Model Context Protocol (MCP): build MCP servers and clients on Node.js, Bun, Deno, and Workers. This is the v2 documentation, covering the 2026-07-28 spec revision.',
'',
'Every page below is also served as plain markdown at its `.md` URL — fetch any page directly.',
''
Expand Down
2 changes: 1 addition & 1 deletion docs/.vitepress/theme/Banner.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<template>
<div class="version-banner">
This is the documentation for the v2 beta — looking for the
This is the documentation for v2 — looking for the
<a href="https://ts.sdk.modelcontextprotocol.io/" target="_self">v1 documentation</a>?
</div>
</template>
Comment thread
claude[bot] marked this conversation as resolved.
2 changes: 1 addition & 1 deletion docs/clients/roots.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ shape: how-to
# Provide roots

::: warning Deprecated — SEP-2577
Pass paths through tool arguments, resource URIs, or host configuration instead. **Roots** are deprecated as of protocol version 2026-07-28 (SEP-2577) and stay functional on 2025-era connections for at least twelve months — see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated).
Pass paths through tool arguments, resource URIs, or host configuration instead. **Roots** are deprecated as of protocol version 2026-07-28 (SEP-2577) and stay functional on 2025-era connections for at least twelve months — see the [deprecated features registry](https://modelcontextprotocol.io/specification/2026-07-28/deprecated).
:::

## Migrate away first
Expand Down
4 changes: 2 additions & 2 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ shape: landing

# MCP TypeScript SDK

::: info v2 beta
This is the documentation for **v2** of the SDK, currently in **beta**: the API is settling but can still change before the stable release alongside the [2026-07-28 spec](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/). [Tell us what you find](https://github.com/modelcontextprotocol/typescript-sdk/issues/new?template=v2-feedback.yml) — and if you need the stable v1, its documentation is at [ts.sdk.modelcontextprotocol.io](https://ts.sdk.modelcontextprotocol.io/).
::: info v2
This is the documentation for **v2** of the SDK, the stable release line implementing the [2026-07-28 spec](https://modelcontextprotocol.io/specification/2026-07-28). [Report issues](https://github.com/modelcontextprotocol/typescript-sdk/issues/new/choose) — and if you need v1, its documentation is at [ts.sdk.modelcontextprotocol.io](https://ts.sdk.modelcontextprotocol.io/).
:::

The **Model Context Protocol** (MCP) is an open standard that connects AI applications to the systems where your data and tools live. You write a **server** that exposes tools, resources, and prompts; any MCP **host** — Claude Code, VS Code, Cursor, your own application — connects to it and lets a model use them. The protocol is defined by [the MCP specification](https://modelcontextprotocol.io/specification/latest); this SDK is its TypeScript implementation, on Node.js, Bun, and Deno.
Expand Down
2 changes: 1 addition & 1 deletion docs/migration/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ v2 packages (`@modelcontextprotocol/client`, `@modelcontextprotocol/server`, …
Start by running the codemod:

```bash
npx @modelcontextprotocol/codemod@beta v1-to-v2 .
npx @modelcontextprotocol/codemod@latest v1-to-v2 .
```

Run it at the package root (`.`) — real projects import the SDK from `test/`,
Expand Down
7 changes: 1 addition & 6 deletions docs/migration/support-2026-07-28.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,6 @@ protocol revision — and for code written against an earlier **v2 alpha** that
wire-only members directly. If you are on `@modelcontextprotocol/sdk` (v1.x), start with
[upgrade-to-v2.md](./upgrade-to-v2.md) instead.

> **Schema artifact:** until the revision is finalized, the spec repository publishes
> the 2026-07-28 schema under `schema/draft/` — there is no `schema/2026-07-28/`
> directory yet. Tooling that vendors per-revision schema artifacts should track
> `draft/` and note the divergence.

Nothing in v2 puts a 2026-07-28 byte on the wire by default: a hand-constructed
`Client` / `Server` / `McpServer` keeps speaking the 2025-era protocol it was written
for. Serving or speaking 2026-07-28 is always an explicit opt-in via one of the entries
Expand Down Expand Up @@ -366,7 +361,7 @@ tightening that **does** affect v1 code (custom-handler `_meta` passthrough,
`CallToolResult.content` keeps its v1 default on the legacy era (2026-07-28
connections require it explicitly).

> **If you were on a v2 alpha:** the 2026-07-28 draft error codes were renumbered:
> **If you were on a v2 alpha:** the 2026-07-28 error codes were renumbered:
> `HeaderMismatch` `-32001`→`-32020`, `MissingRequiredClientCapability` `-32003`→`-32021`,
> `UnsupportedProtocolVersion` `-32004`→`-32022`. No v1.x impact (these codes never
> existed in v1); v2-alpha code that hard-coded the old literals must update — prefer
Expand Down
7 changes: 3 additions & 4 deletions docs/migration/upgrade-to-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ If you are already on v2 and want to adopt the **2026-07-28 protocol revision**,
both `import` and `require('@modelcontextprotocol/…')` resolve natively.
2. **Run the codemod.**
```bash
npx @modelcontextprotocol/codemod@beta v1-to-v2 .
npx @modelcontextprotocol/codemod@latest v1-to-v2 .
```
Run it at the **package root** (`.`), not `./src` — it also rewrites `package.json`,
and real projects import the SDK from `test/`, `scripts/`, and fixtures too.
Expand Down Expand Up @@ -233,10 +233,9 @@ quote-anchored pattern misses silently — match either quote. The build layout
changed: v2 emits `.mjs`/`.cjs` siblings in a flat `dist/`, so v1's `/dist/cjs/` ↔
`/dist/esm/` flavor-pair path swaps have no equivalent.

#### Registry availability during the beta
#### Registry availability

All v2 packages are published on the public npm registry. Two notes for the beta
window:
All v2 packages are published on the public npm registry. Two notes:

- As of `2.0.0-beta.1` all v2 packages share one version number (earlier alphas
did not). The codemod writes ranges that match what is published, so prefer its
Expand Down
2 changes: 1 addition & 1 deletion docs/servers/logging-progress-cancellation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Only the result comes back:
## Log to the client

::: warning Deprecated — SEP-2577
Log to `stderr` (stdio servers) or use OpenTelemetry instead. **MCP logging** is deprecated as of protocol version 2026-07-28 (SEP-2577) and stays functional through the deprecation window (at least twelve months) — see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated).
Log to `stderr` (stdio servers) or use OpenTelemetry instead. **MCP logging** is deprecated as of protocol version 2026-07-28 (SEP-2577) and stays functional through the deprecation window (at least twelve months) — see the [deprecated features registry](https://modelcontextprotocol.io/specification/2026-07-28/deprecated).
:::

Declare the `logging` capability when you construct the server.
Expand Down
2 changes: 1 addition & 1 deletion docs/servers/sampling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ shape: how-to
# Sampling

::: warning Deprecated — SEP-2577
Call your LLM provider's API directly from your server instead. **Sampling** is deprecated as of protocol version 2026-07-28 (SEP-2577) and stays functional on 2025-era connections for at least twelve months — see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated).
Call your LLM provider's API directly from your server instead. **Sampling** is deprecated as of protocol version 2026-07-28 (SEP-2577) and stays functional on 2025-era connections for at least twelve months — see the [deprecated features registry](https://modelcontextprotocol.io/specification/2026-07-28/deprecated).
:::

## Replace sampling with a direct provider call
Expand Down
2 changes: 1 addition & 1 deletion docs/v1/.vitepress/theme/Banner.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<template>
<div class="version-banner">
This is the documentation for v1.x — looking for the
<a href="https://ts.sdk.modelcontextprotocol.io/v2/" target="_self">v2 beta documentation</a>?
<a href="https://ts.sdk.modelcontextprotocol.io/v2/" target="_self">v2 documentation</a>?
</div>
</template>
4 changes: 2 additions & 2 deletions packages/client/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The MCP (Model Context Protocol) TypeScript client SDK. Build MCP clients that c

<!-- prettier-ignore -->
> [!WARNING]
> **This is a beta release.** The API surface is settling but breaking changes remain possible until v2 stabilizes. Please try it and open issues — feedback during the beta directly shapes the stable release.
> **v2 is the stable release line**, implementing the [2026-07-28 MCP spec](https://modelcontextprotocol.io/specification/2026-07-28). Migrating from v1? Start with the [migration guide](https://ts.sdk.modelcontextprotocol.io/v2/migration/).

<!-- prettier-ignore -->
> [!NOTE]
Expand All @@ -13,7 +13,7 @@ The MCP (Model Context Protocol) TypeScript client SDK. Build MCP clients that c
## Install

```bash
npm install @modelcontextprotocol/client@beta
npm install @modelcontextprotocol/client
```
Comment thread
claude[bot] marked this conversation as resolved.

TypeScript ≥6.0 no longer auto-includes `@types/*` — add `"types": ["node"]` to your `tsconfig.json` `compilerOptions` (the published `.d.mts` references `Buffer`).
Expand Down
2 changes: 1 addition & 1 deletion packages/client/src/client/authExtensions.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -572,7 +572,7 @@ export interface CrossAppAccessProviderOptions {
* a callback function that you provide. This allows flexibility in how you obtain and
* cache ID Tokens from the IdP.
*
* @see https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx
* @see https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/stable/enterprise-managed-authorization.mdx
*
* @example
* ```ts
Expand Down
2 changes: 1 addition & 1 deletion packages/client/src/client/crossAppAccess.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
* Provides standalone functions for RFC 8693 Token Exchange and RFC 7523 JWT Authorization Grant
* flows as specified in the Enterprise Managed Authorization specification (SEP-990).
*
* @see https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx
* @see https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/stable/enterprise-managed-authorization.mdx
* @module
*/

Expand Down
4 changes: 2 additions & 2 deletions packages/codemod/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ Codemods for migrating MCP TypeScript SDK code between major versions.
## Usage

```bash
npx @modelcontextprotocol/codemod@beta v1-to-v2 .
npx @modelcontextprotocol/codemod@latest v1-to-v2 .

# or a single source file (manifest changes are reported, not applied)
npx @modelcontextprotocol/codemod@beta v1-to-v2 src/server.ts
npx @modelcontextprotocol/codemod@latest v1-to-v2 src/server.ts
```

The codemod rewrites TypeScript and JavaScript source files
Expand Down
Loading
Loading