TypeScript SDK

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

Это SDK из репозитория modelcontextprotocol/typescript-sdk. В списке официальных SDK он отнесён к первому уровню (Tier 1).

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

По README выпуска, v2 - основная ветка, а v1 получает исправления ошибок и обновления безопасности не меньше шести месяцев после выхода v2. К v2 также относятся необязательные пакеты-переходники @modelcontextprotocol/node, /express, /fastify и /hono.

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

Нужен Node.js 20 или новее: так записано в поле engines пакетов в реестре npm. По README SDK работает также в Bun и Deno. По руководству «первый сервер», пакеты поставляются только как модули ES, поэтому в package.json проекта нужен "type": "module".

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

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

• Список для рукопожатия initialize в packages/core/src/constants.ts: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07.
• Список новой эпохи в protocolEras.ts: только 2026-07-28.

Для вас это значит: один и тот же выпуск может говорить с новыми и со старыми собеседниками, но эпоху каждого соединения он выбирает один раз, при подключении. Чем эпохи различаются, описано на странице о версиях протокола.

Поведением управляет настройка клиента versionNegotiation. По документу о версиях у поля mode три значения:

Значение по умолчанию - 'legacy': это записано в versionNegotiation.ts константой DEFAULT_VERSION_NEGOTIATION_MODE. То есть клиент, написанный без этой настройки, остаётся в эпохе Legacy даже с сервером, который умеет 2026-07-28.

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' - эпоху, на которой остановилось соединение.

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

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

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, handler.fetch - это функция вида «запрос - ответ» по веб-стандарту. Сам пример ещё ничего не слушает: обработчик нужно подключить к среде выполнения или к одному из пакетов-переходников. Как совместить обе эпохи на одном адресе, разобрано на странице о сервере двух эпох.

Пакет @modelcontextprotocol/sdk 1.32.0 ставится командой из README ветки:

npm install @modelcontextprotocol/sdk zod

Ему нужен Node.js 18 или новее. Список версий в src/types.ts заканчивается на 2025-11-25, строки 2026-07-28 в исходниках выпуска нет. Поэтому v1 - только Legacy: ни server/discover, ни работы без initialize в нём нет.

По плану развития, новые редакции спецификации реализуются только в основной ветке. Для переноса кода с v1 на v2 руководство даёт команду:

npx @modelcontextprotocol/codemod@latest v1-to-v2 .

Там же сказано, что команда переносит только программный интерфейс SDK. Переход на редакцию 2026-07-28 она не делает: это отдельная работа, см. страницу о переходе.

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

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

Что такое расширения и как о них договариваются стороны - на странице о расширениях.

• Roots, Sampling, Logging. Устарели с редакции 2026-07-28, но остаются в SDK. По руководству по обновлению, устаревание выражено только пометками @deprecated.
• Динамическая регистрация клиента. Функция registerClient осталась с пометкой @deprecated; руководство советует Client ID Metadata Documents.
• HTTP+SSE. Сервер v2 этот старый транспорт не обслуживает. Клиент сохраняет SSEClientTransport для старых серверов. Замороженная копия серверного транспорта лежит в @modelcontextprotocol/server-legacy/sse; она помечена устаревшей, и её удаление запланировано на v3. Источник - документ о старых клиентах.
• Сеансы и Mcp-Session-Id. Остаются только в транспортах эпохи 2025 года, которые подключаются вручную.

Общий список устаревшего в протоколе - на странице об устаревших возможностях.

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

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

• Все официальные SDK
• Версии протокола и эпохи
• Сервер двух эпох
• Переход на 2026-07-28