# MCP TypeScript SDK: установка, версии и редакции протокола

> Официальный TypeScript SDK для MCP - выпуск 2.3.0, установка, какие редакции протокола он понимает, что клиент отправляет по умолчанию и чем отличается ветка v1.

Страница: https://mcpdoc.ru/sdk/typescript/
Указатель сайта: https://mcpdoc.ru/llms.txt

TypeScript SDK - официальный набор пакетов для серверов и клиентов MCP. Выпуск 2.3.0 понимает обе эпохи протокола: Modern (2026-07-28) и Legacy (2025-11-25 и старше). Клиент по умолчанию начинает со старого рукопожатия `initialize`, новую эпоху нужно включить настройкой `versionNegotiation`. Ветка v1 (пакет `@modelcontextprotocol/sdk` 1.32.0) работает только в эпохе Legacy.

сверено с выпуском 2.3.0 4 октября 2026

Совместимость Dual-era работает с обеими эпохами и выбирает по собеседнику

- **Проверенная версия:** 2.3.0, выпуск от 2026-10-02

- **Новейшая поддерживаемая редакция:** 2026-07-28

- **С сервером только Modern:** работает

- **С сервером только Legacy:** работает

- **Переход на старую редакцию:** вручную

- **Использует устаревшее:** Roots, Sampling, Logging, динамическая регистрация клиента (DCR), транспорт HTTP+SSE

- **Сохраняет удалённое в редакции 2026-07-28:** сессии, рукопожатие initialize

- **Расширение Tasks:** нет

- **Расширение MCP Apps:** нет

- **Проверено:** 2026-10-04

- **Источник:** [github.com](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.3.0)

## Что это

Это SDK из репозитория [modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk/tree/v2.3.0). В [списке официальных SDK](https://modelcontextprotocol.io/docs/sdk) он отнесён к первому уровню (Tier 1).

У SDK две ветки, и они публикуются под разными именами:

| Ветка | Пакеты | Проверенный выпуск | Эпоха |
|---|---|---|---|
| v2 | `@modelcontextprotocol/server`, `@modelcontextprotocol/client` | 2.3.0, 2026-10-02 | Dual-era |
| v1 | `@modelcontextprotocol/sdk` | 1.32.0, 2026-10-02 | только Legacy |

По [README выпуска](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/README.md), v2 - основная ветка, а v1 получает исправления ошибок и обновления безопасности не меньше шести месяцев после выхода v2. К v2 также относятся необязательные пакеты-переходники `@modelcontextprotocol/node`, `/express`, `/fastify` и `/hono`.

## Установка и среда

```bash title="Установка v2"
npm install @modelcontextprotocol/server
npm install @modelcontextprotocol/client
```

Нужен Node.js 20 или новее: так записано в поле `engines` пакетов в [реестре npm](https://www.npmjs.com/package/@modelcontextprotocol/server). По README SDK работает также в Bun и Deno. По [руководству «первый сервер»](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/docs/get-started/first-server.md), пакеты поставляются только как модули ES, поэтому в `package.json` проекта нужен `"type": "module"`.

Схемы инструментов описываются через Standard Schema: по README подойдут Zod v4, Valibot, ArkType или другая совместимая библиотека.

## Какие редакции понимает выпуск

В выпуске 2.3.0 два отдельных списка версий.

- Список для рукопожатия `initialize` в [`packages/core/src/constants.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/packages/core/src/constants.ts): 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07.
- Список новой эпохи в [`protocolEras.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/packages/core-internal/src/shared/protocolEras.ts): только 2026-07-28.

Открытая константа `LATEST_PROTOCOL_VERSION` в выпуске 2.3.0 равна `'2025-11-25'`. Она называет самую новую редакцию старой эпохи, а не самую новую редакцию, которую понимает SDK. Редакция 2026-07-28 лежит в отдельной внутренней константе `SUPPORTED_MODERN_PROTOCOL_VERSIONS`. Если судить о поддержке по одной `LATEST_PROTOCOL_VERSION`, вывод будет неверным.

Для вас это значит: один и тот же выпуск может говорить с новыми и со старыми собеседниками, но эпоху каждого соединения он выбирает один раз, при подключении. Чем эпохи различаются, описано на странице [о версиях протокола](https://mcpdoc.ru/protocol/versions/).

## Что отправляет клиент по умолчанию

Поведением управляет настройка клиента `versionNegotiation`. По [документу о версиях](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/docs/protocol-versions.md) у поля `mode` три значения:

| Значение `mode` | Что уходит в сеть |
|---|---|
| не задано или `'legacy'` | рукопожатие `initialize`, без пробного запроса |
| `'auto'` | пробный `server/discover`; если сервер старый - откат на `initialize` |
| `{ pin: '2026-07-28' }` | только эта редакция; отката нет, при неудаче `connect()` завершается ошибкой |

Значение по умолчанию - `'legacy'`: это записано в [`versionNegotiation.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/packages/client/src/client/versionNegotiation.ts) константой `DEFAULT_VERSION_NEGOTIATION_MODE`. То есть клиент, написанный без этой настройки, остаётся в эпохе Legacy даже с сервером, который умеет 2026-07-28.

```ts title="Клиент с выбором эпохи"
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const client = new Client({ name: 'my-client', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });

await client.connect(new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp')));

console.log(client.getProtocolEra());
```

Пример взят из документации выпуска 2.3.0 и здесь не запускался.

Метод `getProtocolEra()` возвращает `'modern'` или `'legacy'` - эпоху, на которой остановилось соединение.

Тот же документ советует не включать `'auto'` по умолчанию в программах командной строки, которые каждый раз запускают сервер заново. На stdio пробный запрос идёт через отдельный короткоживущий процесс сервера, а старый сервер, который молчит в ответ, задерживает `connect()` на всё время ожидания.

## Что принимает сервер

В v2 есть две точки входа, которые обслуживают обе эпохи одной фабрикой сервера:

- `createMcpHandler` - для Streamable HTTP. По умолчанию запросы старой эпохи тоже обслуживаются, без сеансов (`legacy: 'stateless'`). Значение `legacy: 'reject'` оставляет только новую эпоху: на `initialize` сервер ответит HTTP 400 с ошибкой `-32022`.
- `serveStdio` из `@modelcontextprotocol/server/stdio` - для stdio. Эпоху соединения задаёт первый обмен; `legacy: 'reject'` отклоняет старое начало.

По [руководству по переходу](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/docs/migration/support-2026-07-28.md), сервер, собранный вручную и подключённый через `server.connect(new StdioServerTransport())`, обслуживает только протокол эпохи 2025 года. Обновление пакета этого не меняет. Именно такую связку показывает короткий пример в README выпуска. Чтобы сервер на stdio отвечал в редакции 2026-07-28, нужна точка входа `serveStdio`.

```ts title="Сервер для Streamable HTTP"
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';

const handler = createMcpHandler(() => {
    const server = new McpServer({ name: 'notes', version: '1.0.0' });
    server.registerTool(
        'add-note',
        {
            description: 'Save a note',
            inputSchema: z.object({ text: z.string() })
        },
        async ({ text }) => ({ content: [{ type: 'text', text: `Saved: ${text}` }] })
    );
    return server;
});
```

Пример взят из документации выпуска 2.3.0 и здесь не запускался.

По [руководству по HTTP](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/docs/serving/http.md), `handler.fetch` - это функция вида «запрос - ответ» по веб-стандарту. Сам пример ещё ничего не слушает: обработчик нужно подключить к среде выполнения или к одному из пакетов-переходников. Как совместить обе эпохи на одном адресе, разобрано на странице [о сервере двух эпох](https://mcpdoc.ru/deployment/dual-era/).

## Ветка v1

Пакет `@modelcontextprotocol/sdk` 1.32.0 ставится командой из [README ветки](https://github.com/modelcontextprotocol/typescript-sdk/blob/1.32.0/README.md):

```bash title="Установка v1"
npm install @modelcontextprotocol/sdk zod
```

Ему нужен Node.js 18 или новее. Список версий в [`src/types.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/1.32.0/src/types.ts) заканчивается на 2025-11-25, строки `2026-07-28` в исходниках выпуска нет. Поэтому v1 - только Legacy: ни `server/discover`, ни работы без `initialize` в нём нет.

По [плану развития](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/ROADMAP.md), новые редакции спецификации реализуются только в основной ветке. Для переноса кода с v1 на v2 [руководство](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/docs/migration/index.md) даёт команду:

```bash title="Автоматический перенос импортов и имён"
npx @modelcontextprotocol/codemod@latest v1-to-v2 .
```

Там же сказано, что команда переносит только программный интерфейс SDK. Переход на редакцию 2026-07-28 она не делает: это отдельная работа, см. страницу [о переходе](https://mcpdoc.ru/protocol/migration/).

## Расширения

**Tasks.** Готовой реализации расширения в выпуске 2.3.0 нет. По руководству по переходу, слой перехвата задач удалён, а типы задач редакции 2025-11-25 оставлены только как устаревший словарь для совместимости. Методы `tasks/get` и `tasks/cancel` в любой эпохе можно отправлять и обслуживать только вручную, как собственные методы с явной схемой. Если обработчик не зарегистрирован, входящий запрос `tasks/*` получает ошибку `-32601`. В плане развития расширение Tasks названо отдельной задачей.

**MCP Apps.** Реализации в этом репозитории нет. В выпуске расширение встречается только в журнале изменений, где упомянут отдельный «MCP Apps SDK», и в примере внутри типов спецификации.

Что такое расширения и как о них договариваются стороны - на странице [о расширениях](https://mcpdoc.ru/protocol/extensions/).

## Устаревшее, что выпуск ещё содержит

- **Roots, Sampling, Logging.** Устарели с редакции 2026-07-28, но остаются в SDK. По [руководству по обновлению](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/docs/migration/upgrade-to-v2.md), устаревание выражено только пометками `@deprecated`.
- **Динамическая регистрация клиента.** Функция `registerClient` осталась с пометкой `@deprecated`; руководство советует Client ID Metadata Documents.
- **HTTP+SSE.** Сервер v2 этот старый транспорт не обслуживает. Клиент сохраняет `SSEClientTransport` для старых серверов. Замороженная копия серверного транспорта лежит в `@modelcontextprotocol/server-legacy/sse`; она помечена устаревшей, и её удаление запланировано на v3. Источник - [документ о старых клиентах](https://github.com/modelcontextprotocol/typescript-sdk/blob/v2.3.0/docs/serving/legacy-clients.md).
- **Сеансы и `Mcp-Session-Id`.** Остаются только в транспортах эпохи 2025 года, которые подключаются вручную.

Общий список устаревшего в протоколе - на странице [об устаревших возможностях](https://mcpdoc.ru/protocol/deprecations/).

## Выпуск и ветка main

На 4 октября 2026 ветка `main` опережает метку `v2.3.0` на три изменения. Это правки документации и тестов; константы версий протокола совпадают с выпуском. Пробных выпусков новее 2.3.0 в реестре npm нет.

## Что неизвестно

- Содержимое опубликованных архивов npm отдельно не распаковывалось: сверялись исходники по метке выпуска и данные реестра.
- Минимальная версия компилятора TypeScript в README и в руководствах для начинающих выпуска 2.3.0 не названа.
- Точная дата окончания поддержки v1 не опубликована: названо только «не меньше шести месяцев после выхода v2».

## Что читать дальше

- [Все официальные SDK](https://mcpdoc.ru/sdk/)
- [Версии протокола и эпохи](https://mcpdoc.ru/protocol/versions/)
- [Сервер двух эпох](https://mcpdoc.ru/deployment/dual-era/)
- [Переход на 2026-07-28](https://mcpdoc.ru/protocol/migration/)