# MCP Docs — все страницы одним файлом --- # Model Context Protocol (MCP) Документация на русском: перевод и разборы > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/). Протокол MCP — открытый стандарт, по которому ИИ-приложения подключаются к внешним серверам и получают от них инструменты, ресурсы и шаблоны запросов. Хост создаёт для каждого сервера своего клиента, а сервер объявляет возможности ответом на `server/discover`. > **Заметка переводчика.** Подчёркнутые слова можно навести мышью или выбрать с клавиатуры: появится короткое определение. Начиная с ревизии 2026-07-28 протокол работает без состояния: нет рукопожатия и сессий, а версия и возможности клиента передаются в каждом запросе. Это самое значительное изменение протокола на сегодня, и его разбор вынесен в отдельный раздел. > **Заметка переводчика.** Если вы работаете с серверами и клиентами прежних версий, начните со страницы [«Миграция на 2026-07-28»](https://mcpdocs.ru/migration/) и [матрицы совместимости](https://mcpdocs.ru/protocol/versions/). Проверить свой сервер можно бесплатной [проверкой](https://mcpprotocol.ru/mcp-check/) справочника mcpprotocol.ru. ## Маршрут чтения Страницы идут от общего к частному. Если у вас уже есть сервер или клиент прежней ревизии, начните с четвёртого листа. 1. [Введение](https://mcpdocs.ru/intro/) 2. [Понятия](https://mcpdocs.ru/concepts/) 3. [Протокол](https://mcpdocs.ru/protocol/) 4. [Миграция на 2026-07-28](https://mcpdocs.ru/migration/) 5. [Безопасность](https://mcpdocs.ru/security/) (в разработке) 6. [Руководства](https://mcpdocs.ru/guides/) (в разработке) 7. [Справочник](https://mcpdocs.ru/reference/) 8. [Инструменты](https://mcpdocs.ru/tools/) 9. [О проекте](https://mcpdocs.ru/about/) ## Какую версию читать Сайт описывает ревизию 2026-07-28. Но серверы прежних версий ещё долго будут встречаться. | Версия | Эпоха | Что важно знать | | --- | --- | --- | | 2026-07-28 | Современная | Основа этого сайта. Протокол без состояния: нет `initialize` и сессий. | | 2025-11-25 | Прежняя | Рукопожатие `initialize`, сессии, Streamable HTTP с `Mcp-Session-Id`. | | 2025-06-18, 2025-03-26, 2024-11-05 | Прежние | Исторические ревизии. Подробности на странице «Справочник». | ## О переводе Это неофициальный перевод. Оригинал и права на него принадлежат авторам проекта MCP. Если перевод и оригинал расходятся, верен оригинал. Подробнее о том, как мы переводим и как отмечены страницы, на странице [«О проекте»](https://mcpdocs.ru/about/). --- # Введение Зачем нужен MCP и как он устроен > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/intro/). Тип: Перевод. Основа: Архитектура MCP (документация 2026-07-28) (https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Model Context Protocol (MCP) — открытый протокол, по которому ИИ-приложения получают контекст от внешних серверов: инструменты, данные и шаблоны запросов. Он описывает только обмен контекстом и не диктует, как приложение использует языковую модель и распоряжается полученным контекстом. > **Заметка переводчика.** Слово «контекст» здесь шире, чем «история диалога»: это всё, что сервер может дать приложению, от функций для вызова до содержимого файлов и баз данных. ## Из чего состоит проект - **Спецификация MCP.** Требования к реализации клиентов и серверов. - **SDK.** Библиотеки для разных языков программирования, реализующие протокол. - **Инструменты разработки.** Например, MCP Inspector для проверки серверов. - **Эталонные серверы.** Примеры реализаций серверов MCP. ## Участники MCP построен по схеме «клиент — сервер». ИИ-приложение, например Claude Code или Claude Desktop, подключается к одному или нескольким серверам MCP. Для каждого сервера приложение создаёт отдельного клиента, и у каждой пары «клиент — сервер» своё соединение. - **Хост MCP (host)**. ИИ-приложение, которое координирует одного или нескольких клиентов. - **Клиент MCP (client)**. Компонент, который держит соединение с сервером и получает от него контекст для хоста. - **Сервер MCP (server)**. Программа, которая предоставляет контекст клиентам. Например, Visual Studio Code выступает хостом. Когда он подключается к серверу Sentry, среда выполнения создаёт клиента для этого соединения. Подключение ко второму серверу, например к серверу файловой системы, создаёт второго клиента. Слово «сервер» относится к программе, которая отдаёт контекст, и не говорит, где она запущена. Локальный сервер работает на той же машине и использует транспорт stdio, а удалённый сервер работает на чужой платформе и использует Streamable HTTP. Локальный сервер обычно обслуживает одного клиента, удалённый — многих. ## Два слоя - **Слой данных** определяет протокол обмена на основе JSON-RPC 2.0: обнаружение (`server/discover`), возможности сервера (инструменты, ресурсы, шаблоны), возможности клиента, служебные функции вроде уведомлений и отчётов о ходе работы. - **Транспортный слой** определяет каналы обмена: установку соединения, обрамление сообщений и авторизацию. Формат сообщений JSON-RPC 2.0 одинаков для всех транспортов. Концептуально слой данных внутренний, а транспортный внешний. Транспорты описаны на странице [«Транспорты»](https://mcpdocs.ru/protocol/transports/). ## Три примитива сервера Примитивы определяют, что клиенты и серверы могут предложить друг другу. Сервер может открыть три основных примитива. | Примитив | Что это | Кто управляет | | --- | --- | --- | | Инструменты (tools) | Функции, которые приложение вызывает, чтобы выполнить действие: операции с файлами, вызовы API, запросы к базам данных. | Модель | | Ресурсы (resources) | Источники данных, которые дают приложению контекст: содержимое файлов, записи баз данных, ответы API. | Приложение | | Шаблоны запросов (prompts) | Готовые шаблоны, которые помогают структурировать взаимодействие с моделью: системные подсказки, примеры. | Пользователь | У каждого примитива есть методы обнаружения (`*/list`), получения (`*/get`, `resources/read`) и, для инструментов, выполнения (`tools/call`). Благодаря `*/list` перечни могут быть динамическими. Подробно: [«Понятия»](https://mcpdocs.ru/concepts/). ## Что у клиента Клиент может открыть серверу запрос данных у пользователя (elicitation): так сервер просит недостающие данные или подтверждение действия. Начиная с версии 2026-07-28 такие запросы доставляются по шаблону многошагового запроса (MRTR), описанному на странице [«Шаблоны обмена»](https://mcpdocs.ru/protocol/patterns/). Устарели с версии 2026-07-28 и не рекомендованы для новых реализаций: **сэмплинг** (sampling, запрос ответа языковой модели у клиента), **корневые каталоги** (roots) и **журналирование** (logging, передача журналов клиенту). Подробнее: [«Миграция»](https://mcpdocs.ru/migration/#ustarevshie-vozmozhnosti). ## MCP и A2A MCP подключает агента к инструментам и данным, а [A2A](https://a2adocs.ru/) связывает агентов между собой. Протоколы дополняют друг друга. Сравнение, таблица различий и типичные заблуждения: страница [«MCP и A2A»](https://mcpprotocol.ru/mcp-vs-a2a/) справочника mcpprotocol.ru (то же со стороны A2A: [a2aprotocol.ru](https://a2aprotocol.ru/a2a-vs-mcp/)). ## Что читать дальше - [Понятия](https://mcpdocs.ru/concepts/): сервер, обнаружение, инструменты, ресурсы, шаблоны. - [Протокол](https://mcpdocs.ru/protocol/): сообщения, поля `_meta`, версии. - [Миграция на 2026-07-28](https://mcpdocs.ru/migration/): если вы работаете с серверами прежней ревизии. --- # Понятия Основные объекты и роли протокола > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/concepts/). Тип: Перевод. Основа: Понимание серверов MCP (документация 2026-07-28) (https://modelcontextprotocol.io/docs/2026-07-28/learn/server-concepts). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Сервер предоставляет функциональность через три «строительных блока»: инструменты, ресурсы и шаблоны запросов. Этот раздел собирает основные понятия, а отдельные страницы разбирают главные из них подробно. ## Словарь понятий | Понятие | Что это | | --- | --- | | Хост (host) | ИИ-приложение, которое подключается к серверам MCP и координирует клиентов. | | Клиент (client) | Компонент хоста, который держит соединение с одним сервером и получает от него контекст. | | Сервер (server) | Программа, которая предоставляет контекст клиентам. Бывает локальной (stdio) и удалённой (Streamable HTTP). | | [Обнаружение](https://mcpdocs.ru/concepts/discovery/) (`server/discover`) | Запрос, по которому клиент узнаёт поддерживаемые версии протокола, возможности и сведения о сервере. | | [Инструменты](https://mcpdocs.ru/concepts/tools/) (tools) | Функции с типизированными входом и выходом, которые вызывает приложение по решению модели. | | [Ресурсы](https://mcpdocs.ru/concepts/resources/) (resources) | Данные для чтения, которые определяет URI. Бывают прямыми и шаблонными. | | [Шаблоны запросов](https://mcpdocs.ru/concepts/prompts/) (prompts) | Параметризованные шаблоны, которые пользователь вызывает явно. | | Запрос данных у пользователя (elicitation) | Способ, которым сервер просит у пользователя недостающие данные или подтверждение. | | Расширение (extension) | Необязательная возможность поверх базового протокола, например Tasks или MCP Apps. Объявляется в поле `extensions` в возможностях. | | `_meta` | Поле для служебных данных, которые клиент и сервер прикрепляют к запросам и ответам, включая версию протокола. | > **Заметка переводчика.** Слово prompt в русскоязычных текстах встречается как «промпт», «подсказка» и «шаблон». Здесь для примитива MCP используется «шаблон запроса», чтобы отличать его от текста, который пользователь пишет модели. ## Кто что контролирует У каждого примитива свой «хозяин»: - **Инструменты** управляются моделью: она сама решает, когда их вызвать. Но спецификация рекомендует, чтобы человек мог отклонить вызов. - **Ресурсы** управляются приложением: оно решает, какие данные и как показать модели. - **Шаблоны** управляются пользователем: их нужно вызвать явно, например через слэш-команду. ## Как это работает вместе Типичное взаимодействие выглядит так. 1. **Знакомство (необязательно).** Клиент запрашивает `server/discover` и узнаёт версии, возможности и название сервера. Можно обойтись без этого шага: каждый запрос и так несёт версию и возможности клиента. 2. **Перечни.** Клиент запрашивает `tools/list`, `resources/list` или `prompts/list` и узнаёт, что доступно. 3. **Работа.** Приложение вызывает инструмент (`tools/call`), читает ресурс (`resources/read`) или получает шаблон (`prompts/get`). 4. **Изменения.** Если нужно следить за изменениями, клиент открывает поток `subscriptions/listen` и выбирает типы уведомлений. Если серверу по ходу запроса нужны данные от пользователя, он не посылает отдельный запрос, а возвращает промежуточный результат `input_required`, и клиент повторяет исходный запрос с ответом. Подробнее: [«Шаблоны обмена»](https://mcpdocs.ru/protocol/patterns/). ## Что читать дальше - [Обнаружение](https://mcpdocs.ru/concepts/discovery/): что возвращает `server/discover`. - [Инструменты](https://mcpdocs.ru/concepts/tools/): поля, результаты, ошибки. - [Ресурсы](https://mcpdocs.ru/concepts/resources/): URI, шаблоны, подписки. - [Шаблоны запросов](https://mcpdocs.ru/concepts/prompts/): аргументы и вызов. --- # Обнаружение (server/discover) Как сервер рассказывает о себе > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/concepts/discovery/). Тип: Перевод. Основа: Спецификация, раздел «Discovery» (https://modelcontextprotocol.io/specification/2026-07-28/server/discover). Ревизия спецификации 2026-07-28, сверено 05.10.2026. `server/discover` позволяет клиенту узнать поддерживаемые версии протокола, возможности и идентичность сервера до любых других запросов. Реализовать его ДОЛЖНЫ все серверы; клиент может его не вызывать. ## Из чего состоит сервер Схема показывает типичный сервер MCP, разобранный на семь групп. Наведите на деталь или перемещайтесь стрелками: справа от каждой — её назначение, внизу — подробности и фрагмент сообщения. ## Запрос и ответ Запрос не несёт параметров, кроме стандартных полей `_meta` ([подробнее](https://mcpdocs.ru/protocol/#polya-meta)): ```json { "jsonrpc": "2.0", "id": "discover-1", "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "ExampleClient", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": {} } } } ``` Ответ содержит версии, возможности и идентичность сервера. Результат можно кэшировать: ```json { "jsonrpc": "2.0", "id": "discover-1", "result": { "resultType": "complete", "supportedVersions": ["2026-07-28"], "capabilities": { "tools": {}, "resources": {} }, "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "ExampleServer", "version": "1.0.0" } }, "instructions": "This server provides weather and resource utilities.", "ttlMs": 3600000, "cacheScope": "public" } } ``` ### Таблица полей | Поле | Описание | | --- | --- | | `resultType` | Тип результата. Для обычного ответа `"complete"`. | | `supportedVersions` | Версии протокола, которые поддерживает сервер. Клиент выбирает одну из них для следующих запросов. | | `capabilities` | Возможности сервера: инструменты, ресурсы, шаблоны запросов и другие. | | `_meta["io.modelcontextprotocol/serverInfo"]` | Название и версия программы сервера. Серверам СЛЕДУЕТ указывать это поле. | | `instructions` | Необязательные указания на естественном языке для языковой модели о том, как эффективно пользоваться сервером. | | `ttlMs` | Время свежести ответа в миллисекундах: подсказка для кэширования. | | `cacheScope` | Кто может использовать кэш: `"public"` или `"private"`. | > **Заметка переводчика.** `serverInfo` сообщает сам сервер, протокол его не проверяет. Он нужен для отображения, журналов и отладки: от него НЕ СЛЕДУЕТ менять поведение клиента и принимать решения о безопасности. Как отвечает ваш сервер, можно проверить бесплатной [проверкой MCP-сервера](https://mcpprotocol.ru/mcp-check/): она сверяет `server/discover`, `ttlMs`, `cacheScope`, `resultType` и название сервера с требованиями ревизии. ## Когда вызывать Вызывать `server/discover` не обязательно: клиент может сразу отправить любой запрос и обработать ошибку `UnsupportedProtocolVersionError`, если версия не поддерживается. Но метод полезен в двух случаях. - **Показать сведения о сервере.** Из одного ответа клиент узнаёт идентичность, возможности и версии, не опрашивая по отдельности `tools/list`, `prompts/list` и `resources/list`. - **Проба совместимости на stdio.** У stdio нет статус-кодов HTTP, по которым можно было бы решить, возвращаться ли к старому протоколу. Поэтому клиент, который поддерживает и современные, и прежние серверы, СЛЕДУЕТ отправить `server/discover` первым. Правила отката: [«Версии и совместимость»](https://mcpdocs.ru/protocol/versions/). > **Заметка переводчика.** В публикациях о ревизии 2026-07-28 встречается мнение, что `server/discover` необязателен. В спецификации для сервера он обязателен, а необязательным является только его вызов клиентом. ## Возможности и перечни Возможности сервера в `capabilities` определяют, какие методы клиент может вызывать. Например, `"tools": {"listChanged": true}` значит, что сервер умеет уведомлять об изменении перечня инструментов, а `"resources": {}` — что он отвечает на `resources/list` и `resources/read`. Клиент, получив это, не пытается вызвать то, чего сервер не поддерживает. Результаты `server/discover`, `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list` и `resources/read` несут обязательные поля `ttlMs` и `cacheScope`. `ttlMs` подсказывает клиенту, как долго можно не обновлять ответ, а `cacheScope` показывает, могут ли общие посредники (например, прокси) его кэшировать. Эти поля дополняют уведомления об изменениях. --- # Инструменты (tools) Функции, которые вызывает модель > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/concepts/tools/). Тип: Перевод и пересказ. Основа: Спецификация, раздел «Tools» (https://modelcontextprotocol.io/specification/2026-07-28/server/tools). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Сервер может открыть инструменты, которые вызывает языковая модель: запросы к базам данных, вызовы API, вычисления. Каждый инструмент однозначно определяется именем и содержит метаданные со схемой. ## Модель управления Инструменты рассчитаны на **управление моделью**: модель сама находит и вызывает их, исходя из контекста и запросов пользователя. Но протокол не навязывает интерфейс. > **Важно.** Ради безопасности у человека СЛЕДУЕТ быть возможность отклонить вызов. Приложениям СЛЕДУЕТ показывать, какие инструменты открыты модели, явно отмечать вызовы и просить подтверждения для операций. ## Возможности сервера Сервер, который поддерживает инструменты, ДОЛЖЕН объявить возможность `tools`: ```json { "capabilities": { "tools": { "listChanged": true } } } ``` `listChanged` показывает, пришлёт ли сервер уведомление при изменении перечня инструментов. Перечень, который сервер отдаёт в ответ на `tools/list`, МОЖЕТ быть пустым и МОЖЕТ меняться со временем, но НЕ ДОЛЖЕН зависеть от соединения или от побочных эффектов других запросов. Он МОЖЕТ различаться в зависимости от переданной авторизации: например, можно вернуть только те инструменты, которые разрешены выданными правами. Порядок инструментов СЛЕДУЕТ делать детерминированным: так клиенту проще кэшировать перечень, а у модели выше шанс попасть в кэш подсказки. ## Сообщения ### Список инструментов Операция поддерживает постраничную выдачу и кэширование. ```json { "jsonrpc": "2.0", "id": 1, "result": { "resultType": "complete", "tools": [ { "name": "get_weather", "title": "Weather Information Provider", "description": "Get current weather information for a location", "inputSchema": { "type": "object", "properties": { "location": { "type": "string", "description": "City name or zip code" } }, "required": ["location"] } } ], "nextCursor": "next-page-cursor", "ttlMs": 300000, "cacheScope": "public" } } ``` ### Вызов инструмента ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_weather", "arguments": { "location": "New York" } } } ``` Ответ несёт `content` (массив элементов) и признак `isError`: ```json { "jsonrpc": "2.0", "id": 2, "result": { "resultType": "complete", "content": [ { "type": "text", "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy" } ], "isError": false } } ``` В примерах опущены поля `_meta`, но каждый запрос ДОЛЖЕН включать обязательные поля. Подробнее: [«Протокол»](https://mcpdocs.ru/protocol/#polya-meta). ### Недостаточно данных Сервер МОЖЕТ ответить на `tools/call` результатом `input_required`, если для вызова нужны дополнительные данные. Клиент собирает их и повторяет вызов с полем `inputResponses` и, если сервер его прислал, с `requestState`. Идентификатор JSON-RPC у повторного запроса ДОЛЖЕН отличаться от идентификатора первого. Механизм описан на странице [«Шаблоны обмена»](https://mcpdocs.ru/protocol/patterns/#mnogoshagovye-zaprosy-mrtr). ### Уведомление об изменении перечня Серверу, объявившему `listChanged`, СЛЕДУЕТ отправлять `notifications/tools/list_changed` клиентам, которые открыли поток `subscriptions/listen` с фильтром `toolsListChanged: true`. ## Поля Tool | Поле | Описание | | --- | --- | | `name` | Уникальное имя инструмента. | | `title` | Необязательное название для показа человеку. | | `description` | Описание функциональности для человека. | | `icons` | Необязательные значки для интерфейсов. | | `inputSchema` | Схема JSON Schema ожидаемых параметров. По умолчанию действует 2020-12, и это ДОЛЖЕН быть корректный объект схемы (не `null`). | | `outputSchema` | Необязательная схема структуры результата. | | `annotations` | Необязательные свойства, описывающие поведение инструмента. Клиенты ДОЛЖНЫ считать аннотации недоверенными, если они не пришли от доверенного сервера. | Для инструмента без параметров рекомендуется схема `{ "type": "object", "additionalProperties": false }`. ### Имена - Длина имени СЛЕДУЕТ составлять от 1 до 128 символов. - Регистр СЛЕДУЕТ учитывать. - Допустимые символы СЛЕДУЕТ ограничить латинскими буквами, цифрами, подчёркиванием (`_`), дефисом (`-`) и точкой (`.`). - Пробелы, запятые и другие спецсимволы НЕ СЛЕДУЕТ использовать. - Имя СЛЕДУЕТ делать уникальным в пределах сервера. Уникальность ограничена одним сервером. Клиенты и прокси, которые собирают инструменты с нескольких серверов, СЛЕДУЕТ реализовать способ различения, например приставку с идентификатором сервера. Название сервера из `serverInfo` для этого не годится: оно не гарантирует уникальности. ### Заголовки из параметров (`x-mcp-header`) Сервер МОЖЕТ пометить параметр инструмента свойством `x-mcp-header`. Тогда клиент при работе по Streamable HTTP ДОЛЖЕН продублировать значение в заголовок `Mcp-Param-{имя}`. Это позволяет балансировщикам и прокси направлять запросы по значению параметра, не разбирая тело. Ограничения и кодирование значений описаны на странице [«Транспорты»](https://mcpdocs.ru/protocol/transports/#zagolovki-iz-parametrov-instrumenta). Чувствительные параметры (пароли, ключи, токены, персональные данные) помечать так НЕ СЛЕДУЕТ: заголовки видны посредникам. ## Результаты Результат может быть неструктурированным (`content`) или структурированным (`structuredContent`). | Тип содержимого | Назначение | | --- | --- | | `text` | Текст. | | `image` | Изображение в base64 с типом MIME. | | `audio` | Аудио в base64 с типом MIME. | | `resource_link` | Ссылка на ресурс, который клиент может прочитать или на который подписаться. В `resources/list` такие ссылки могут не появиться. | | `resource` | Встроенный ресурс с URI и содержимым. | Все типы содержимого поддерживают необязательные аннотации (аудитория, приоритет, время изменения). ### Структурированный результат `structuredContent` — любое значение JSON (объект, массив, строка, число, логическое значение или `null`). Если у инструмента есть `outputSchema`, сервер ДОЛЖЕН возвращать результат, который ей соответствует, а клиентам СЛЕДУЕТ проверять результат по схеме. Для обратной совместимости инструменту, который возвращает структурированный результат, СЛЕДУЕТ дублировать его сериализованным JSON в текстовом блоке. > **Заметка переводчика.** `structuredContent` не связан со «структурированным выводом» моделей, то есть с генерацией по схеме. Это просто данные, которые вернул сервер. ## Инструменты с состоянием В MCP нет сессий на уровне протокола, поэтому сервер не может опираться на неявное состояние соединения. Если инструменту нужно хранить состояние между вызовами (корзина, открытый браузер, транзакция), сервер возвращает явный **дескриптор** из инструмента создания и принимает его аргументом в последующих вызовах. Для протокола дескриптор — обычная строка. Это нормативно не регулируется, а спецификация даёт рекомендации. - **Авторизация.** Для серверов с аутентификацией дескриптор лишь имя, и права нужно проверять при каждом вызове. Без аутентификации дескриптор фактически токен предъявителя, его нужно генерировать с достаточной энтропией (например, UUIDv4) и ограничить срок жизни. - **Непрозрачность.** Дескрипторы с внутренней структурой провоцируют разбор и угадывание. - **Срок жизни.** Правила хранения СЛЕДУЕТ указать в описании инструмента создания, например «корзины удаляются через 24 часа простоя». - **Ошибка просроченного дескриптора.** Вызов с просроченным или неизвестным дескриптором СЛЕДУЕТ завершать ошибкой выполнения инструмента, чтобы модель могла создать новый. ## Ошибки Есть два вида ошибок. 1. **Ошибки протокола** касаются структуры запроса, и модель вряд ли исправит их сама: неизвестный инструмент, некорректный запрос, сбой сервера. Они возвращаются как стандартные ошибки JSON-RPC, например с кодом `-32602`. 2. **Ошибки выполнения** содержат подсказки, по которым модель может исправиться и повторить: сбой API, неверный формат даты, значение вне диапазона, нарушение бизнес-логики. Они передаются в результате с `isError: true`. Клиенты МОГУТ передавать модели ошибки протокола, а ошибки выполнения СЛЕДУЕТ передавать, чтобы модель могла исправиться. ## Безопасность Серверы ДОЛЖНЫ проверять все входные данные инструментов, реализовывать контроль доступа, ограничивать частоту вызовов и очищать выходные данные. Клиентам СЛЕДУЕТ запрашивать подтверждение для чувствительных операций, показывать пользователю входные данные до вызова (чтобы не допустить утечки), проверять результаты перед передачей модели, ограничивать время вызова и вести журнал использования. --- # Ресурсы (resources) Данные, которые читает приложение > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/concepts/resources/). Тип: Перевод и пересказ. Основа: Понимание серверов MCP; список изменений 2026-07-28 (https://modelcontextprotocol.io/docs/2026-07-28/learn/server-concepts). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Ресурсы дают приложению структурированный доступ к информации, которую оно может передать модели как контекст: файлы, ответы API, схемы баз данных. Приложение само решает, как использовать данные: выбрать фрагменты, найти по векторному поиску или отдать модели целиком. ## Как это устроено У каждого ресурса есть уникальный URI (например, `file:///path/to/document.md`) и тип MIME. Ресурсы бывают двух видов. - **Прямые ресурсы** имеют фиксированные URI и указывают на конкретные данные. Пример: `calendar://events/2024`. - **Шаблоны ресурсов** задают динамические URI с параметрами для гибких запросов. Пример: `travel://activities/{city}/{category}`; конкретный вариант — `travel://activities/barcelona/museums`. Шаблоны содержат метаданные (название, описание, ожидаемый тип MIME), поэтому их можно находить и понимать без документации: ```json { "uriTemplate": "weather://forecast/{city}/{date}", "name": "weather-forecast", "title": "Weather Forecast", "description": "Get weather forecast for any city and date", "mimeType": "application/json" } ``` ## Методы | Метод | Назначение | Что возвращает | | --- | --- | --- | | `resources/list` | Список прямых ресурсов. | Массив описаний ресурсов. | | `resources/templates/list` | Список шаблонов ресурсов. | Массив определений шаблонов. | | `resources/read` | Чтение содержимого ресурса. | Данные ресурса с метаданными. | | `subscriptions/listen` | Слежение за изменениями. | Поток уведомлений об обновлении. | Результаты `resources/list`, `resources/templates/list` и `resources/read` несут обязательные поля `ttlMs` и `cacheScope` для кэширования. Заголовок `Mcp-Name` при чтении ресурса по HTTP содержит URI ([«Транспорты»](https://mcpdocs.ru/protocol/transports/#standartnye-zagolovki-zaprosa)). ## Подписка на изменения Чтобы следить за конкретными ресурсами, клиент отправляет запрос `subscriptions/listen` и перечисляет URI в фильтре `resourceSubscriptions`. Когда наблюдаемый ресурс меняется, сервер доставляет `notifications/resources/updated` в открытом потоке. Подробнее: [«Шаблоны обмена»](https://mcpdocs.ru/protocol/patterns/#podpiska-na-izmeneniya-subscriptions-listen). > **Заметка переводчика.** До ревизии 2026-07-28 для этого служили методы `resources/subscribe` и `resources/unsubscribe`. В новой ревизии они заменены на `subscriptions/listen`. ## Автодополнение параметров Для динамических ресурсов можно подсказывать допустимые значения параметров. Когда пользователь вводит «Par» в `weather://forecast/{city}`, система может предложить «Paris» или «Park City». Так пользователю не нужно знать точный формат. ## Модель взаимодействия Ресурсы **управляются приложением**, поэтому способы показа свободны: - деревья и списки для просмотра в привычном виде папок; - поиск и фильтры; - автоматическое включение в контекст или умные предложения по эвристикам либо выбору ИИ; - ручной или массовый выбор нескольких ресурсов. Протокол не навязывает интерфейс: это может быть выбор с предпросмотром, предложения по ходу разговора или интеграция с файловыми менеджерами. ## Ошибка «ресурс не найден» В ревизии 2026-07-28 код ошибки «ресурс не найден» изменён с `-32002` на `-32602` (неверные параметры), чтобы согласовать с JSON-RPC. Клиентам СЛЕДУЕТ по-прежнему принимать `-32002` от серверов прежних версий. Подробнее: [«Ошибки»](https://mcpdocs.ru/protocol/errors/). --- # Шаблоны запросов (prompts) Готовые сценарии, которые вызывает пользователь > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/concepts/prompts/). Тип: Перевод и пересказ. Основа: Понимание серверов MCP (документация 2026-07-28) (https://modelcontextprotocol.io/docs/2026-07-28/learn/server-concepts). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Шаблоны запросов — многоразовые заготовки. С их помощью автор сервера даёт параметризованные сценарии для своей предметной области или показывает, как лучше пользоваться сервером. ## Как это устроено Шаблоны задают ожидаемые входные данные и порядок взаимодействия. Они **управляются пользователем**: их нужно вызвать явно, а не ждать автоматического срабатывания. Шаблон может ссылаться на доступные ресурсы и инструменты, чтобы описать цельный рабочий процесс. Как и у ресурсов, у шаблонов есть автодополнение аргументов, которое помогает находить допустимые значения. | Метод | Назначение | Что возвращает | | --- | --- | --- | | `prompts/list` | Узнать, какие шаблоны есть. | Массив описаний шаблонов. | | `prompts/get` | Получить шаблон. | Полное определение с аргументами. | Результат `prompts/list` несёт обязательные `ttlMs` и `cacheScope`. Заголовок `Mcp-Name` при `prompts/get` по HTTP содержит имя шаблона. ## Пример Шаблон «Спланировать отпуск»: ```json { "name": "plan-vacation", "title": "Plan a vacation", "description": "Guide through vacation planning process", "arguments": [ { "name": "destination", "type": "string", "required": true }, { "name": "duration", "type": "number", "description": "days" }, { "name": "budget", "type": "number", "required": false }, { "name": "interests", "type": "array", "items": { "type": "string" } } ] } ``` Вместо свободного текста пользователь выбирает шаблон, вводит структурированные данные (Барселона, 7 дней, 3000 долларов, пляжи, архитектура, еда), и сценарий выполняется одинаково каждый раз. ## Как показывать пользователю Протокол оставляет свободу интерфейса. Основные принципы: - шаблоны легко найти; - у каждого есть ясное описание; - ввод аргументов естественный и с проверкой; - сам шаблон прозрачно показан. Типичные решения: слэш-команды («/plan-vacation»), палитры команд с поиском, отдельные кнопки для частых шаблонов, контекстные меню с подходящими вариантами. ## Как серверы работают вместе Сила MCP проявляется, когда подключено несколько серверов. В примере из документации приложение для планирования поездки использует три сервера: путешествий, погоды и календаря с почтой. Пользователь вызывает шаблон с параметрами, выбирает ресурсы (календарь, предпочтения, прошлые поездки), и модель вызывает инструменты разных серверов, запрашивая подтверждение, где нужно. --- # Протокол Сообщения, поля _meta и устройство обмена > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/protocol/). Тип: Перевод и пересказ. Основа: Спецификация, раздел «Overview» (https://modelcontextprotocol.io/specification/2026-07-28/basic/index). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Протокол MCP состоит из нескольких компонентов: базового протокола (сообщения JSON-RPC), версионирования, шаблонов обмена, авторизации, возможностей сервера и клиента и служебных функций. Все реализации ДОЛЖНЫ поддерживать базовый протокол, версионирование и шаблоны обмена, а остальное МОЖНО реализовать по потребности. ## Сообщения Все сообщения между клиентами и серверами MCP ДОЛЖНЫ соответствовать спецификации [JSON-RPC 2.0](https://www.jsonrpc.org/specification). Есть три вида сообщений. ### Запросы Запросы идут от клиента к серверу и начинают операцию. ```typescript { jsonrpc: "2.0"; id: string | number; method: string; params?: { [key: string]: unknown }; } ``` - Запрос ДОЛЖЕН содержать идентификатор: строку или целое число. - В отличие от базового JSON-RPC, идентификатор НЕ ДОЛЖЕН быть `null`. - Идентификатор НЕ ДОЛЖЕН совпадать с идентификатором другого запроса отправителя, на который он ещё не получил ответ. ### Ответы **Успешный ответ** ДОЛЖЕН содержать тот же идентификатор, что и запрос, и поле `result`, а в нём поле `resultType`. ```typescript { jsonrpc: "2.0"; id: string | number; result: { resultType: string; [key: string]: unknown }; } ``` | Значение `resultType` | Смысл | | --- | --- | | `"complete"` | Запрос выполнен, результат содержит итоговое содержимое. | | `"input_required"` | Запрос не завершён: нужна дополнительная информация. Результат содержит объект `InputRequiredResult` ([шаблон «несколько обменов»](https://mcpdocs.ru/protocol/patterns/#mnogoshagovye-zaprosy-mrtr)). | Расширения МОГУТ добавлять свои значения. Любое незнакомое клиенту значение ДОЛЖНО считаться недопустимым. Для совместимости с серверами прежних версий, которые не передают `resultType`, клиенты ДОЛЖНЫ считать его отсутствие значением `"complete"`. **Ответ с ошибкой** ДОЛЖЕН содержать тот же идентификатор (кроме случая, когда идентификатор не удалось прочитать из-за некорректного запроса) и поле `error` с целочисленным `code` и строкой `message`. Может быть поле `data` с любой дополнительной информацией. Коды ошибок описаны на странице [«Ошибки»](https://mcpdocs.ru/protocol/errors/). ### Уведомления Уведомление — одностороннее сообщение. Получатель НЕ ДОЛЖЕН отвечать на него, а само уведомление НЕ ДОЛЖНО содержать идентификатор. ## Шаблоны обмена Базовый протокол поддерживает три шаблона: 1. **Запрос и ответ.** Клиент отправляет запрос, сервер возвращает результат или ошибку. 2. **Многошаговые запросы** (MRTR). Серверу для завершения запроса нужны данные от клиента (запрос данных у пользователя, сэмплинг или корневые каталоги). 3. **Подписка и уведомление.** Клиент подписывается на поток уведомлений, которые сервер присылает по мере появления. Подробнее: [«Шаблоны обмена»](https://mcpdocs.ru/protocol/patterns/). ## Отсутствие состояния MCP — протокол **без состояния**: вся информация, нужная для обработки запроса, содержится в самом запросе. Сервер обрабатывает каждый запрос независимо и не выводит ничего из предыдущих запросов, даже на том же соединении или потоке. В частности: - Серверы НЕ ДОЛЖНЫ полагаться на предыдущие запросы по тому же соединению, чтобы установить контекст (возможности, версию протокола, личность клиента): каждый запрос передаёт эти данные в `_meta`. - Серверам СЛЕДУЕТ быть готовыми к запросам, связанным с несколькими задачами, потоками или разговорами. - Серверам НЕ СЛЕДУЕТ требовать, чтобы клиент использовал одно и то же соединение или процесс для связанных операций. - Клиентам НЕ СЛЕДУЕТ использовать отдельную задачу, поток или разговор как границу времени жизни процесса stdio. - Состояние, которое должно сохраняться между запросами (долгие задачи, дескрипторы приложения), ДОЛЖНО передаваться явным идентификатором при каждом запросе. Открытое соединение, например процесс stdio, — не разговор и не сессия: клиенты могут чередовать несвязанные запросы на одном транспорте, а сервер не должен принимать идентичность соединения или процесса за признак непрерывности разговора. Долгие запросы вроде `subscriptions/listen` остаются парой «запрос — ответ»: просто ответ представляет собой открытый поток уведомлений. ## Поля _meta Свойство `_meta` позволяет клиентам и серверам прикреплять к взаимодействиям дополнительные метаданные. Часть ключей зарезервирована MCP для служебных данных. ### Формат имён ключей Имя ключа состоит из необязательного **префикса** и **имени**. - Префикс — цепочка меток через точку, заканчивающаяся косой чертой. Метка начинается с буквы, заканчивается буквой или цифрой, внутри допустимы буквы, цифры и дефисы. Рекомендуется обратная доменная запись (`com.example/`). - Префиксы, в которых вторая метка `modelcontextprotocol` или `mcp`, зарезервированы для MCP: `io.modelcontextprotocol/`, `dev.mcp/`. А `com.example.mcp/` не зарезервирован: вторая метка здесь `example`. - Имя, если не пусто, начинается и заканчивается буквой или цифрой, внутри допустимы дефисы, подчёркивания и точки. ### Зарезервированные ключи | Ключ | Описание | | --- | --- | | `progressToken` | Подписывает запрос на уведомления о ходе выполнения. | | `io.modelcontextprotocol/protocolVersion` | Версия протокола для запроса. | | `io.modelcontextprotocol/clientInfo` | Название и версия клиента. | | `io.modelcontextprotocol/clientCapabilities` | Возможности клиента, важные для запроса. | | `io.modelcontextprotocol/logLevel` | Минимальный уровень журнала, который сервер должен передавать по этому запросу. | | `io.modelcontextprotocol/subscriptionId` | Связывает уведомление с подпиской, которая его породила. | | `traceparent`, `tracestate`, `baggage` | Передача контекста трассировки OpenTelemetry (форматы W3C Trace Context и W3C Baggage). | ### Обязательные поля каждого запроса | Ключ | Тип | Обязателен | Описание | | --- | --- | --- | --- | | `io.modelcontextprotocol/protocolVersion` | `string` | Да | Версия протокола для этого запроса, например `"2026-07-28"`. | | `io.modelcontextprotocol/clientInfo` | `Implementation` | Нет | Название и версия клиента. | | `io.modelcontextprotocol/clientCapabilities` | `ClientCapabilities` | Да | Возможности клиента для этого запроса. | | `io.modelcontextprotocol/logLevel` | `LoggingLevel` | Нет | Минимальный уровень журнала для запроса. | Запрос без обязательного поля некорректен: сервер ДОЛЖЕН отклонить его кодом JSON-RPC `-32602` (неверные параметры), а в HTTP — статусом `400 Bad Request`. Клиентам СЛЕДУЕТ указывать `clientInfo` в каждом запросе, если не настроено иначе. Сервер НЕ ДОЛЖЕН полагаться на возможности, которые клиент не объявил. Если для запроса нужна не объявленная возможность, сервер ДОЛЖЕН вернуть `MissingRequiredClientCapabilityError` (`-32021`) с перечнем недостающих возможностей в `data.requiredCapabilities` (в HTTP со статусом `400`). В каждом результате серверу СЛЕДУЕТ указывать `io.modelcontextprotocol/serverInfo` в `_meta`. Оба поля, `clientInfo` и `serverInfo`, сообщают сами стороны, протокол их не проверяет: они нужны для отображения, журналов и отладки, но не для решений о безопасности. > **Заметка переводчика.** Пример запроса с полным набором полей `_meta` показан на странице [«Обнаружение»](https://mcpdocs.ru/concepts/discovery/#zapros-i-otvet). В коротких примерах на других страницах поля `_meta` опущены ради краткости. ## Авторизация MCP определяет [механизм авторизации](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization) для транспортов на основе HTTP. Реализациям на HTTP СЛЕДУЕТ ему соответствовать. Реализациям на stdio НЕ СЛЕДУЕТ его применять: учётные данные берутся из окружения. Клиенты и серверы МОГУТ согласовать собственные способы аутентификации и авторизации. Раздел «Безопасность» этого сайта готовится. ## Схема Полное описание протокола задано [схемой на TypeScript](https://github.com/modelcontextprotocol/specification/blob/main/schema/2026-07-28/schema.ts): она **источник истины** обо всех сообщениях и структурах. [JSON Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2026-07-28/schema.json) создаётся из неё автоматически для автоматизированных инструментов. ### Схемы JSON Schema внутри сообщений - Если в схеме нет поля `$schema`, по умолчанию действует JSON Schema 2020-12. Реализации ДОЛЖНЫ поддерживать как минимум 2020-12 и СЛЕДУЕТ документировать поддержку других диалектов. - Реализации ДОЛЖНЫ проверять схемы по заявленному или умолчательному диалекту, а неподдерживаемый диалект обрабатывать корректно, вернув ошибку. - Реализации НЕ ДОЛЖНЫ автоматически загружать `$ref`, указывающие на сетевой URI. Загрузка МОЖЕТ быть включена опционально, но по умолчанию выключена, и тогда СЛЕДУЕТ использовать список разрешённых хостов, отклонять петлевые, локальные и частные адреса, ограничивать время и размер и вести журнал. - Схемы с неразрешённым внешним `$ref` СЛЕДУЕТ отклонять, а не считать «разрешающими всё». - Конструкции композиции (`anyOf`, `oneOf`, `allOf`, `if/then/else`) и `$defs` дороги в проверке, поэтому СЛЕДУЕТ задать ограничения (глубина схемы, число подсхем, бюджет времени), чтобы вредоносная схема не стала вектором отказа в обслуживании. ## Дальше - [Транспорты](https://mcpdocs.ru/protocol/transports/): stdio и Streamable HTTP. - [Шаблоны обмена](https://mcpdocs.ru/protocol/patterns/): MRTR, подписки, отмена, прогресс. - [Ошибки](https://mcpdocs.ru/protocol/errors/): коды и их распределение. - [Версии и совместимость](https://mcpdocs.ru/protocol/versions/): согласование версий и эпохи протокола. --- # Транспорты stdio и Streamable HTTP > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/protocol/transports/). Тип: Перевод и пересказ. Основа: Спецификация, раздел «Streamable HTTP» (https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http). Ревизия спецификации 2026-07-28, сверено 05.10.2026. MCP поддерживает два транспорта. Формат сообщений JSON-RPC 2.0 у них одинаков, различается способ доставки. Готовность своего сервера к требованиям этой страницы можно проверить бесплатной [проверкой MCP-сервера](https://mcpprotocol.ru/mcp-check/): она сверяет заголовки, коды ошибок и поведение при чужом `Origin`. ## Два транспорта | Транспорт | Как работает | Когда подходит | | --- | --- | --- | | stdio | Потоки стандартного ввода и вывода между локальными процессами на одной машине. Без сетевых издержек. | Локальные серверы, которые обычно обслуживают одного клиента. | | Streamable HTTP | HTTP POST для сообщений клиента, ответ обычным JSON или потоком Server-Sent Events. Поддерживает стандартные способы HTTP-аутентификации: токены предъявителя, ключи API, собственные заголовки. MCP рекомендует OAuth. | Удалённые серверы, которые обслуживают многих клиентов. | На stdio клиентам НЕ СЛЕДУЕТ считать отдельную задачу, поток или разговор границей времени жизни процесса. Уведомление `notifications/cancelled` в базовом протоколе используется только на stdio. Проба совместимости для stdio описана на странице [«Версии и совместимость»](https://mcpdocs.ru/protocol/versions/). > **Заметка переводчика.** Страницу о stdio в спецификации я не переводил: здесь сказано только то, что подтверждается страницами об архитектуре, базовом протоколе и Streamable HTTP. Подробнее смотрите [оригинал](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio). ## Streamable HTTP Транспорт Streamable HTTP появился в версии 2025-03-26 вместо HTTP+SSE версии 2024-11-05. Ревизия 2026-07-28 изменила его поведение: убрана конечная точка GET для потока и отменены сессии на уровне протокола. Сервер работает как независимый процесс, который обслуживает много клиентов: - у сервера **одна** конечная точка HTTP (например, `https://example.com/mcp`), которая принимает POST; - каждый запрос или уведомление клиента — отдельный HTTP POST; - на каждый запрос сервер отвечает либо одним объектом JSON, либо потоком [Server-Sent Events](https://en.wikipedia.org/wiki/Server-sent_events), привязанным к этому запросу: в нём уведомления по запросу и итоговый ответ; - взаимодействия «сервер — клиент» (sampling, elicitation, roots) встроены в результаты как запросы входных данных по шаблону MRTR; - долгие уведомления об изменениях идут в потоке ответа на `subscriptions/listen`. ### Безопасность и конечная точка 1. Серверы ДОЛЖНЫ проверять заголовок `Origin` у всех входящих соединений, чтобы предотвратить атаки через DNS rebinding. Если `Origin` есть и недопустим, сервер ДОЛЖЕН ответить `403 Forbidden`. 2. При локальной работе серверам СЛЕДУЕТ слушать только localhost (127.0.0.1), а не все сетевые интерфейсы (0.0.0.0). 3. Серверам СЛЕДУЕТ реализовать аутентификацию для всех соединений. Без этих мер злоумышленник мог бы обращаться к локальным серверам MCP с чужих сайтов. ### Отправка сообщений 1. Клиент ДОЛЖЕН использовать HTTP POST. 2. Клиент ДОЛЖЕН указать в заголовке `Accept` и `application/json`, и `text/event-stream`. 3. Клиент ДОЛЖЕН включить [заголовки метаданных запроса](#zagolovki-metadannyh-zaprosa) в каждый POST. 4. Тело POST ДОЛЖНО быть одним запросом или уведомлением JSON-RPC. Клиент НЕ ДОЛЖЕН отправлять ответы JSON-RPC. 5. На уведомление сервер, если принимает его, ДОЛЖЕН вернуть `202 Accepted` без тела, а если не может принять, то код ошибки HTTP, например `400`. 6. На запрос сервер ДОЛЖЕН вернуть `Content-Type: application/json` или `Content-Type: text/event-stream`. Клиент ДОЛЖЕН поддерживать оба. В базовой ревизии нет уведомлений «клиент — сервер» по Streamable HTTP: `notifications/cancelled` используется только на stdio. ### Получение сообщений (поток SSE) - Сервер МОЖЕТ присылать уведомления (например, `notifications/progress` или `notifications/message`) до итогового ответа, и они ДОЛЖНЫ относиться к исходному запросу. - Сервер НЕ ДОЛЖЕН присылать в этом потоке собственные запросы JSON-RPC. Взаимодействия «сервер — клиент» встраиваются в `InputRequiredResult`. Это изменение относительно версий 2025-03-26–2025-11-25, где сервер мог слать такие запросы по потокам SSE. - Поток СЛЕДУЕТ закрывать после итогового ответа. - Начиная поток, серверам СЛЕДУЕТ добавлять заголовок `X-Accel-Buffering: no`, чтобы обратные прокси (например, nginx) не буферизовали ответ. - Для долгих потоков, в частности `subscriptions/listen`, рекомендуется периодически посылать строку-комментарий SSE (начинается с двоеточия) как «пульс», чтобы промежуточные узлы не закрывали соединение. Клиенты ДОЛЖНЫ игнорировать такие строки. - Возобновление потоков по `Last-Event-ID` не поддерживается. ### Отмена Закрытие потока ответа SSE сервер ДОЛЖЕН считать отменой этого запроса: прекратить работу как можно скорее и больше не присылать сообщений по нему. ### Заголовки метаданных запроса Streamable HTTP дублирует часть полей тела JSON-RPC в заголовках HTTP, чтобы посредники (балансировщики, шлюзы, наблюдение) могли маршрутизировать и проверять запросы, не разбирая тело. #### Заголовок версии протокола Каждый POST на конечную точку ДОЛЖЕН содержать заголовок `MCP-Protocol-Version`, например `MCP-Protocol-Version: 2026-07-28`. Значение ДОЛЖНО совпадать с `io.modelcontextprotocol/protocolVersion` в `_meta` тела. Иначе сервер ДОЛЖЕН отклонить запрос статусом `400 Bad Request` и ошибкой `HeaderMismatch`. Если сервер не реализует запрошенную версию, он ДОЛЖЕН ответить `400 Bad Request` и `UnsupportedProtocolVersionError` со списком поддерживаемых версий. Если не реализует запрошенный метод, ДОЛЖЕН ответить `404 Not Found` и ошибкой JSON-RPC с кодом `-32601`. По тексту ошибки клиент отличает такой ответ от `404` старого сервера HTTP+SSE. Сервер, который поддерживает клиентов версий до 2025-06-18 (в них заголовка не было), МОЖЕТ считать запрос без заголовка запросом версии 2025-03-26. #### Стандартные заголовки запроса | Заголовок | Источник | Обязателен для | | --- | --- | --- | | `Mcp-Method` | `method` | всех запросов | | `Mcp-Name` | `params.name` или `params.uri` | `tools/call`, `resources/read`, `prompts/get` | Эти заголовки ОБЯЗАТЕЛЬНЫ. Пример `tools/call`: ```http POST /mcp HTTP/1.1 Content-Type: application/json MCP-Protocol-Version: 2026-07-28 Mcp-Method: tools/call Mcp-Name: get_weather { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_weather", "arguments": { "location": "Seattle, WA" }, "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "ExampleClient", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": {} } } } ``` #### Заголовки из параметров инструмента Сервер МОЖЕТ пометить параметры инструмента свойством `x-mcp-header` в `inputSchema`. Значение определяет имя заголовка `Mcp-Param-{имя}`. Серверу это необязательно, а клиенты ДОЛЖНЫ это поддерживать: если определение инструмента содержит такие пометки, клиент ДОЛЖЕН продублировать значения параметров в заголовки. Ограничения на значения `x-mcp-header`: - не пустое и совпадает с синтаксисом имени поля HTTP (`1*tchar`, RFC 9110, раздел 5.1); - без управляющих символов, включая CR и LF; - уникально без учёта регистра в пределах `inputSchema`; - только для параметров примитивных типов: целое, строка, логическое значение (тип `number` не допускается); целые ДОЛЖНЫ лежать в безопасном диапазоне JavaScript (от −2⁵³+1 до 2⁵³−1); - только для свойств, статически достижимых от корня схемы через цепочку ключей `properties`, без `items`, `oneOf`, `anyOf`, `allOf`, `not`, `if/then/else` и `$ref`. Клиенты на Streamable HTTP ДОЛЖНЫ отклонять определения инструментов, где значение нарушает эти ограничения: такой инструмент исключается из результата `tools/list`, и клиенту СЛЕДУЕТ записать предупреждение. Клиенты на других транспортах (например, stdio) МОГУТ игнорировать `x-mcp-header`. Пример определения и итогового запроса: ```json { "name": "execute_sql", "description": "Execute SQL on Google Cloud Spanner", "inputSchema": { "type": "object", "properties": { "region": { "type": "string", "description": "The region to execute the query in", "x-mcp-header": "Region" }, "query": { "type": "string", "description": "The SQL query to execute" } }, "required": ["region", "query"] } } ``` ```http POST /mcp HTTP/1.1 Content-Type: application/json MCP-Protocol-Version: 2026-07-28 Mcp-Method: tools/call Mcp-Name: execute_sql Mcp-Param-Region: us-west1 ``` #### Кодирование значений Клиенты ДОЛЖНЫ кодировать значения перед включением в заголовки. Значение приводится к строке: строка как есть, целое в десятичной записи, логическое в виде `"true"` или `"false"`. Если значение нельзя безопасно передать обычным ASCII (содержит не-ASCII, управляющие символы или пробелы по краям), клиент ДОЛЖЕН использовать Base64 от UTF-8 в формате: ```text Mcp-Param-{Name}: =?base64?{Base64EncodedValue}?= ``` Так же кодируется `Mcp-Name`. Метки `=?base64?` и `?=` чувствительны к регистру. Чтобы избежать неоднозначности, клиент ДОЛЖЕН закодировать и обычное значение, похожее на этот шаблон. | Исходное значение | Причина | Заголовок | | --- | --- | --- | | `us-west1` | Обычный ASCII | `Mcp-Param-Region: us-west1` | | `Hello, 世界` | Не-ASCII | `Mcp-Param-Greeting: =?base64?SGVsbG8sIOS4lueVjA==?=` | | ` padded ` | Пробелы по краям | `Mcp-Param-Text: =?base64?IHBhZGRlZCA=?=` | Если значение параметра равно `null` или параметра нет в аргументах, клиент НЕ ДОЛЖЕН добавлять заголовок. #### Проверка на сервере Сервер, который обрабатывает тело запроса, ДОЛЖЕН отклонять запросы, где значения в заголовках не совпадают со значениями в теле. Это защищает от ситуации, когда балансировщик маршрутизирует по заголовку, а сервер исполняет по телу. Отказ оформляется статусом `400 Bad Request` и ошибкой JSON-RPC `-32020` (`HeaderMismatch`): ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32020, "message": "Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'" } } ``` Причины отказа: нет обязательного заголовка; значение не совпадает с телом (закодированные значения сначала декодируют); недопустимые символы. Целые сравниваются как числа, а не как строки. Имена заголовков регистронезависимы, значения регистрозависимы. Посредникам, которые применяют политику по заголовкам, СЛЕДУЕТ убедиться, что версия протокола требует такой проверки, и отклонять запросы без заголовка. ## Обратная совместимость Клиент, который поддерживает и современные версии, и прежние (с рукопожатием `initialize`), МОЖЕТ определить эпоху сервера, попробовав сначала современный запрос. При `400 Bad Request` ему СЛЕДУЕТ посмотреть тело: распознанная современная ошибка JSON-RPC значит современный сервер, и нужно повторить запрос с другой версией, а не откатываться. Если тело пустое или ошибка не распознана, нужно вернуться к `initialize`. Сервер, который поддерживает только эту ревизию и получает трафик старого клиента, СЛЕДУЕТ действовать так: - GET и DELETE на конечную точку: отвечать `405 Method Not Allowed`; - заголовок `Mcp-Session-Id`: игнорировать, не создавать и не возвращать идентификаторы сессий; - заголовок `Last-Event-ID`: игнорировать, потоки не возобновляются. **HTTP+SSE (2024-11-05)** устарел с версии 2025-03-26 и признан Deprecated по политике жизненного цикла функций. Новым реализациям его применять НЕ СЛЕДУЕТ, существующим СЛЕДУЕТ перейти на Streamable HTTP. Клиент, который хочет поддерживать старые серверы, сначала отправляет POST, а при `400`, `404` или `405` без современной ошибки в теле пробует GET и ожидает событие `endpoint`: так он узнаёт старый транспорт. --- # Шаблоны обмена Запрос и ответ, многошаговые запросы, подписки > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/protocol/patterns/). Тип: Перевод и пересказ. Основа: Спецификация, раздел «Message patterns»; список изменений 2026-07-28 (https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/index). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Базовый протокол поддерживает три шаблона обмена. Они заменили механизмы, которые зависели от долгого открытого соединения, и поэтому подходят для протокола без состояния. ## Запрос и ответ Клиент отправляет запрос, сервер возвращает результат или ошибку. По Streamable HTTP каждый запрос — отдельный POST, а ответ — один объект JSON или поток SSE, привязанный к запросу. Запросы, которые идут по потоку, могут нести уведомления о ходе выполнения до итогового ответа. ## Многошаговые запросы (MRTR) Многошаговый запрос (Multi Round-Trip Requests, MRTR) заменил прежний подход, где сервер сам посылал клиенту запросы `roots/list`, `sampling/createMessage` и `elicitation/create`. Такие запросы требовали открытого потока от сервера к клиенту, а протокол без состояния его не предоставляет. Работает это так. 1. Клиент отправляет обычный запрос, например `tools/call`. 2. Если серверу нужны дополнительные данные, он возвращает не итог, а результат с `resultType: "input_required"`. Это объект `InputRequiredResult`. В поле `inputRequests` лежат запросы на недостающую информацию, каждому присвоен ключ. 3. Клиент собирает данные (например, спрашивает пользователя) и **повторяет исходный запрос** с новым идентификатором JSON-RPC, добавив `inputResponses` и, если сервер прислал, `requestState`. 4. Сервер возвращает итоговый результат или снова `input_required`. ```json { "jsonrpc": "2.0", "id": 2, "result": { "resultType": "input_required", "inputRequests": { "github_login": { "method": "elicitation/create", "params": { "mode": "form", "message": "Please provide your GitHub username", "requestedSchema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] } } } }, "requestState": "eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0..." } } ``` Повтор запроса с ответами: ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "get_weather", "arguments": { "location": "New York" }, "inputResponses": { "github_login": { "action": "accept", "content": { "name": "octocat" } } }, "requestState": "eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0..." } } ``` Идентификатор JSON-RPC повторного запроса ДОЛЖЕН отличаться от идентификатора первого. Поле `requestState` непрозрачно для клиента: сервер кладёт в него то, что нужно для продолжения, и получает обратно. > **Заметка переводчика.** Уведомление `notifications/elicitation/complete` и поле `elicitationId` у запросов элицитации в режиме URL (они появились в 2025-11-25) в ревизии 2026-07-28 удалены. Клиент узнаёт итог внешнего взаимодействия, когда повторяет исходный запрос. Если серверу нужно связать несколько повторов, свой идентификатор он кодирует в `requestState`. ## Подписка на изменения (subscriptions/listen) Уведомления об изменениях подписочные: клиент заранее выбирает, какие из них хочет получать. Для этого он отправляет запрос `subscriptions/listen` с фильтром `notifications`. Ответ на него — долгий поток, который остаётся открытым. Типы уведомлений, которые клиент может выбрать: | Фильтр | Что присылает сервер | | --- | --- | | `toolsListChanged` | `notifications/tools/list_changed` при изменении перечня инструментов. | | `promptsListChanged` | Уведомление при изменении перечня шаблонов запросов. | | `resourcesListChanged` | Уведомление при изменении перечня ресурсов. | | `resourceSubscriptions` | `notifications/resources/updated` по перечисленным URI. | Запрос: ```json { "jsonrpc": "2.0", "id": 4, "method": "subscriptions/listen", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": { "elicitation": {} } }, "notifications": { "toolsListChanged": true } } } ``` Сервер подтверждает подписку уведомлением `notifications/subscriptions/acknowledged`: оно первое в потоке с идентификатором подписки в `_meta`, а в его поле `notifications` указана та часть фильтра, которую сервер согласен выполнять (неподдерживаемые типы пропущены). Дальше каждое уведомление в потоке несёт `io.modelcontextprotocol/subscriptionId` в `_meta`. Значение равно идентификатору запроса `subscriptions/listen`, поэтому клиент сопоставляет уведомление с подпиской. - Уведомление доступно, только если сервер объявил соответствующую возможность, например `"listChanged": true` у `tools`. - Доставка «по возможности»: нет гарантии, что каждое уведомление будет отправлено или получено, особенно при переподключении. Свежесть результатов клиентам СЛЕДУЕТ дополнительно поддерживать опросом. - Уведомления, привязанные к запросу, такие как `notifications/progress` и `notifications/message`, идут в потоке ответа на тот запрос, к которому относятся, а не в потоке подписки. - Получив уведомление, клиент обычно запрашивает обновлённый перечень (`tools/list`). ## Отмена По Streamable HTTP закрытие потока ответа SSE — это отмена запроса. По stdio используется уведомление `notifications/cancelled`. Подробности: [«Транспорты»](https://mcpdocs.ru/protocol/transports/#otmena). ## Прогресс Клиент может подписать запрос на уведомления о ходе выполнения, передав `progressToken` в `_meta`. Сервер присылает `notifications/progress` в потоке ответа на этот запрос. Подробное описание: [оригинал](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/progress). --- # Ошибки Коды, их распределение и виды ошибок > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/protocol/errors/). Тип: Перевод и пересказ. Основа: Спецификация, разделы «Overview» и «Streamable HTTP»; список изменений (https://modelcontextprotocol.io/specification/2026-07-28/basic/index). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Ответ с ошибкой — стандартное сообщение JSON-RPC 2.0. В версии 2026-07-28 спецификация ввела политику распределения кодов, чтобы реализации не конфликтовали с кодами протокола. Как сервер отвечает на неизвестную версию, расхождение заголовков и неизвестный метод, проверяет бесплатная [проверка MCP-сервера](https://mcpprotocol.ru/mcp-check/). ## Структура ```typescript { jsonrpc: "2.0"; id?: string | number; error: { code: number; message: string; data?: unknown; } } ``` - Ответ с ошибкой ДОЛЖЕН содержать тот же идентификатор, что и запрос (кроме случая, когда идентификатор нельзя прочитать из-за некорректного запроса). - Код ошибки ДОЛЖЕН быть целым числом. - `data` МОЖЕТ содержать дополнительные сведения любого типа, например вложенные ошибки. ## Распределение кодов Для общих сбоев протокола MCP использует стандартные коды JSON-RPC 2.0: `-32700` и от `-32600` до `-32603`. Диапазон от `-32000` до `-32099` JSON-RPC резервирует для реализационных ошибок сервера, и MCP делит его так. | Диапазон | Статус | | --- | --- | | от `-32000` до `-32019` | **Прежние.** Коды, которые реализации выбрали до введения политики. Новые коды в этом поддиапазоне выделять НЕЛЬЗЯ, а новым реализациям их СЛЕДУЕТ не использовать вовсе. Кроме `-32002` (см. ниже), получатель НЕ ДОЛЖЕН предполагать у этих кодов конкретный смысл. | | от `-32020` до `-32099` | **Зарезервированы для спецификации MCP.** Определяются только ею и записываются в схеме. Реализации НЕ ДОЛЖНЫ выдавать коды из этого диапазона, не определённые спецификацией, и ДОЛЖНЫ использовать определённые только с заданным смыслом. | Новые коды для других целей СЛЕДУЕТ выделять вне диапазона, зарезервированного JSON-RPC (от `-32768` до `-32000`): остальная часть целых чисел доступна для прикладных ошибок. ## Коды MCP | Код | Название | Когда возникает | | --- | --- | --- | | `-32020` | `HeaderMismatch` | Заголовки HTTP не совпадают со значениями в теле запроса или обязательные заголовки отсутствуют либо искажены. HTTP-статус `400`. | | `-32021` | `MissingRequiredClientCapability` | Для запроса нужна возможность, которую клиент не объявил. В `data.requiredCapabilities` перечень недостающих. HTTP-статус `400`. | | `-32022` | `UnsupportedProtocolVersion` | Сервер не поддерживает версию из запроса. В `data` поля `supported` и `requested`. HTTP-статус `400`. | Пример `UnsupportedProtocolVersionError`: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32022, "message": "Unsupported protocol version", "data": { "supported": ["2026-07-28", "2025-11-25"], "requested": "1900-01-01" } } } ``` Клиенту СЛЕДУЕТ выбрать из `supported` общую версию и повторить запрос или показать пользователю ошибку, если совместимой версии нет. ## Другие ошибки по умолчанию | Ситуация | Код и статус HTTP | | --- | --- | | В запросе нет обязательного поля `_meta` (версии протокола или возможностей клиента) | `-32602` (неверные параметры), HTTP `400` | | Сервер не реализует запрошенный метод | `-32601` (метод не найден), HTTP `404` | | Неизвестный инструмент, некорректный запрос | `-32602` | | Ресурс не найден | `-32602` (до 2026-07-28 `-32002`) | ## Устаревшие коды Коды, определённые прежними версиями, остаются зарезервированными и не будут использованы заново. Реализации ревизии 2026-07-28 НЕ ДОЛЖНЫ выдавать эти коды: - `-32002` — ресурс не найден (2025-11-25 и ранее; заменён на `-32602`). Клиентам СЛЕДУЕТ по-прежнему принимать `-32002` от серверов прежних версий. - `-32042` — требуется элицитация по URL (только 2025-11-25). Коды, введённые в черновике этой ревизии, перенумерованы: `HeaderMismatch` из `-32001` в `-32020`, `MissingRequiredClientCapability` из `-32003` в `-32021`, `UnsupportedProtocolVersion` из `-32004` в `-32022`. Ошибка `HeaderMismatchError` добавлена в схему, раньше она существовала только в тексте о транспорте. Ошибки, которые чисто локальны для реализации (например, таймаут внутри SDK), спецификация пока не кодирует. Реализации, которые показывают такие ошибки в виде структур JSON-RPC, должны сделать так, чтобы их нельзя было принять за ошибки от собеседника. ## Ошибки инструментов Вызов инструмента различает ошибки протокола (неизвестный инструмент, некорректный запрос, сбой сервера, возвращаются как ошибки JSON-RPC) и ошибки выполнения (сбои API, неверные данные, бизнес-логика, возвращаются в результате с `isError: true`). Подробнее: [«Инструменты»](https://mcpdocs.ru/concepts/tools/#oshibki). --- # Версии и совместимость Как клиент и сервер договариваются, на каком протоколе говорят > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/protocol/versions/). Тип: Перевод. Основа: Спецификация, раздел «Versioning and Compatibility» (https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Здесь описано, как клиент и сервер согласуют протокол: версию, объявляемую в каждом запросе, необязательные расширения и совместимость с прежними версиями, где было рукопожатие. **Согласования-рукопожатия больше нет.** Каждый запрос несёт свою версию, а сервер принимает или отклоняет каждый запрос независимо. ## Термины - **Современные** версии передают версию, идентичность и возможности как метаданные каждого запроса (ревизия 2026-07-28 и новее). - **Прежние** версии устанавливают сессию рукопожатием `initialize` (2025-11-25 и ранее). - **Двухэпохная** реализация поддерживает и современные, и прежние версии. > **Заметка переводчика.** В оригинале эти три понятия называются modern, legacy и dual-era. Мы называем их «современные», «прежние» и «двухэпохные» и пишем «эпоха» там, где речь о принадлежности к группе версий. ## Согласование версии Каждый запрос объявляет версию в `_meta`, а по HTTP ещё и в заголовке `MCP-Protocol-Version` ([подробнее](https://mcpdocs.ru/protocol/transports/#zagolovok-versii-protokola)). Если сервер не реализует запрошенную версию (неизвестную ему или известную, но отключённую), он ДОЛЖЕН ответить ошибкой `UnsupportedProtocolVersionError` со списком поддерживаемых версий: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32022, "message": "Unsupported protocol version", "data": { "supported": ["2026-07-28", "2025-11-25"], "requested": "1900-01-01" } } } ``` Клиенту СЛЕДУЕТ выбрать из `supported` общую версию и повторить запрос либо показать пользователю ошибку, если совместимой версии нет. Серверы ДОЛЖНЫ реализовывать [`server/discover`](https://mcpdocs.ru/concepts/discovery/). Клиенты МОГУТ вызвать его до других запросов, чтобы заранее узнать версии, но не обязаны: можно сразу вызвать любой метод и обработать `UnsupportedProtocolVersionError`. ## Согласование расширений Клиенты и серверы могут договариваться о необязательных [расширениях](https://modelcontextprotocol.io/docs/extensions/overview). Расширения объявляются в поле `extensions` возможностей. Это словарь «идентификатор расширения → настройки». Идентификатор ДОЛЖЕН подчиняться [правилам именования ключей `_meta`](https://mcpdocs.ru/protocol/#format-imen-klyuchey) с обязательным префиксом. Пример клиента, который объявляет расширение MCP Apps (`io.modelcontextprotocol/ui`): ```json { "capabilities": { "roots": {}, "extensions": { "io.modelcontextprotocol/ui": { "mimeTypes": ["text/html;profile=mcp-app"] } } } } ``` Пример расширения Tasks (`io.modelcontextprotocol/tasks`): ```json { "capabilities": { "tools": {}, "extensions": { "io.modelcontextprotocol/tasks": {} } } } ``` Каждое расширение определяет схему своих настроек, а пустой объект значит поддержку без дополнительных настроек. Если одна сторона поддерживает расширение, а другая нет, поддерживающая сторона ДОЛЖНА либо вернуться к поведению базового протокола, либо отклонить запрос подходящей ошибкой. Расширениям СЛЕДУЕТ описывать, как они ведут себя в таком случае. ## Совместимость с версиями на основе рукопожатия Сервер, который хочет поддерживать и прежних клиентов (ждущих `initialize`), и современных (с метаданными в запросах), МОЖЕТ реализовать оба поведения. Клиент, которому нужно работать с серверами обоих видов, определяет эпоху сервера способом, зависящим от транспорта. - **stdio.** Отправить пробный `server/discover` и откатиться, если пришла любая ошибка, не распознанная как современная. - **Streamable HTTP.** Отправить современный запрос и при `400 Bad Request` проверить тело, прежде чем откатываться ([подробнее](https://mcpdocs.ru/protocol/transports/#obratnaya-sovmestimost)). В обоих случаях распознанная современная ошибка JSON-RPC (например, `UnsupportedProtocolVersionError`) означает современный сервер: нужно повторить запрос с поддерживаемой версией, а не откатываться. Всё остальное означает прежний сервер. Эпоха — свойство сервера, а не отдельного запроса. Клиентам СЛЕДУЕТ кэшировать результат на время жизни процесса сервера (stdio) или источника (HTTP) и МОГУТ сохранять его между перезапусками той же конфигурации, повторяя пробу, если предположение перестало работать. Сервер, который поддерживает только современные версии, СЛЕДУЕТ называть поддерживаемые версии в любой ошибке на запрос `initialize`, на любом транспорте: у прежних клиентов нет способа перейти вперёд, и это сообщение может оказаться единственным, что они смогут показать пользователю. ## Матрица совместимости Результат для каждого сочетания клиента и сервера. Нажмите на ячейку, чтобы прочитать подробности. Та же матрица в виде таблицы: | Клиент | Сервер | Итог | | --- | --- | --- | | Современный | Современный | Работает. `server/discover` необязателен; несовпадение версий возвращается как `UnsupportedProtocolVersionError`, и клиент повторяет запрос с общей версией. | | Современный | Прежний | Не работает. Сервер может отклонить запрос по-своему, промолчать или даже обработать неоднозначный по эпохе метод по прежним правилам. На stdio клиентам СЛЕДУЕТ отправить `server/discover` первым, чтобы отказ был предсказуемым. Затем клиент показывает пользователю понятную ошибку. | | Двухэпохный | Современный | Работает. Проба на stdio возвращает `DiscoverResult` (или `UnsupportedProtocolVersionError`); по HTTP первый современный запрос проходит или возвращает современную ошибку. Клиент остаётся современным. | | Двухэпохный | Прежний | Работает. stdio: проба возвращает не-современную ошибку или молчит, клиент возвращается к `initialize`. HTTP: современный запрос получает `4xx` без распознанной современной ошибки, клиент возвращается к `initialize` (и, возможно, дальше к устаревшему HTTP+SSE). | | Прежний | Современный | Не работает. stdio: сервер отвечает на `initialize` ошибкой JSON-RPC, код зависит от реализации. HTTP: запрос без обязательных заголовков отклоняется статусом `400 Bad Request` (клиент на HTTP+SSE споткнётся уже на начальном GET). У прежних клиентов нет способа перейти вперёд. | | Прежний | Двухэпохный | Работает. Сервер отвечает на `initialize` и обслуживает клиента по согласованной прежней ревизии. | | Прежний | Прежний | Работает по правилам прежней ревизии; вне рамок этого документа. | Двухэпохный **сервер** выбирает поведение по тому, как клиент начинает обмен. Запрос с современными `_meta` обслуживается без состояния по этой ревизии. Запрос `initialize` выбирает прежние правила, ограниченные процессом stdio или сессией HTTP по согласованной прежней версии. Такой сервер МОЖЕТ обслуживать обе эпохи одновременно на одной конечной точке или в одном процессе. > **Заметка переводчика.** В таблице спецификации нет строк «современный клиент — двухэпохный сервер» и «двухэпохный клиент — двухэпохный сервер», поэтому на схеме эти ячейки пустые. Из описания двухэпохного сервера логично, что клиент любой эпохи с ним работает, но это вывод, а не норма. --- # Миграция на 2026-07-28 Что изменилось в протоколе и что менять в клиентах и серверах > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/migration/). Тип: Перевод. Основа: Спецификация, «Key Changes» ревизии 2026-07-28 (https://modelcontextprotocol.io/specification/2026-07-28/changelog). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Ревизия 2026-07-28 — самое значительное изменение протокола MCP на сегодня. Она делает протокол **без состояния**: исчезают сессии и рукопожатие, а версия и возможности клиента путешествуют в каждом запросе. Страница систематизирует и переводит документ «Key Changes» официальной спецификации, опубликованный относительно предыдущей ревизии 2025-11-25. > **Заметка переводчика.** Ревизия содержит несовместимые изменения. Ничего не меняйте «вслепую»: сначала решите, для какой эпохи ([«Версии и совместимость»](https://mcpdocs.ru/protocol/versions/)) вы пишете клиент или сервер и нужна ли двухэпохная поддержка. ## Главные изменения | № | Что изменилось | Подробнее | | --- | --- | --- | | 1 | Убраны сессии на уровне протокола и заголовок `Mcp-Session-Id` из Streamable HTTP. Перечни `tools/list`, `resources/list`, `prompts/list` больше не зависят от соединения. Серверы, которым нужно состояние между вызовами, используют явные дескрипторы, выданные сервером, как обычные аргументы инструментов. | [ниже](#sessii-i-rukopozhatie) | | 2 | Протокол без состояния: убрано рукопожатие `initialize` / `notifications/initialized`. Каждый запрос несёт версию протокола и возможности клиента в `_meta`. | [ниже](#sessii-i-rukopozhatie) | | 3 | Добавлен `server/discover`: серверы ДОЛЖНЫ его реализовать. | [«Обнаружение»](https://mcpdocs.ru/concepts/discovery/) | | 4 | HTTP GET и `resources/subscribe` / `resources/unsubscribe` заменены на `subscriptions/listen`. | [«Шаблоны обмена»](https://mcpdocs.ru/protocol/patterns/#podpiska-na-izmeneniya-subscriptions-listen) | | 5 | Удалены `ping`, `logging/setLevel` и `notifications/roots/list_changed`. Уровень журнала теперь задаётся в запросе. | [ниже](#udalennye-metody) | | 6 | Экспериментальные задачи вынесены из ядра в официальное расширение `io.modelcontextprotocol/tasks`. | [ниже](#zadachi-stali-rasshireniem) | | 7 | Введён шаблон многошаговых запросов (Multi Round-Trip Requests, MRTR) вместо запросов сервера `roots/list`, `sampling/createMessage` и `elicitation/create`. | [«Шаблоны обмена»](https://mcpdocs.ru/protocol/patterns/#mnogoshagovye-zaprosy-mrtr) | | 8 | У всех результатов появилось обязательное поле `resultType`. | [«Протокол»](https://mcpdocs.ru/protocol/#otvety) | | 9 | Убрано возобновление потоков SSE и повторная доставка (заголовок `Last-Event-ID`, идентификаторы событий). | [ниже](#potoki-sse) | ## Сессии и рукопожатие **Было (2025-11-25 и ранее).** Клиент открывал соединение, отправлял `initialize`, согласовывал версию и возможности, затем присылал `notifications/initialized`. Сервер мог выдать идентификатор сессии в заголовке `Mcp-Session-Id`, и последующие запросы опирались на это состояние. **Стало (2026-07-28).** Рукопожатия нет. Каждый запрос самодостаточен: - версия протокола и возможности клиента передаются в `_meta` (`io.modelcontextprotocol/protocolVersion`, `io.modelcontextprotocol/clientCapabilities`); - клиентам СЛЕДУЕТ указывать себя в каждом запросе (`io.modelcontextprotocol/clientInfo`), а серверам СЛЕДУЕТ указывать себя в `_meta` каждого результата (`io.modelcontextprotocol/serverInfo`); - несовпадение версий возвращает `UnsupportedProtocolVersionError`. Пример запроса `tools/list` в новой ревизии: ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": { "elicitation": {} } } } } ``` По HTTP заголовок `MCP-Protocol-Version` обязателен и ДОЛЖЕН совпадать со значением в `_meta`. Кроме него, появились обязательные заголовки `Mcp-Method` и `Mcp-Name` ([«Транспорты»](https://mcpdocs.ru/protocol/transports/#standartnye-zagolovki-zaprosa)). > **Заметка переводчика.** «Протокол без состояния» не значит «приложение без состояния». Если инструментам нужно состояние (корзина, транзакция), сервер возвращает явный дескриптор, а модель передаёт его в следующих вызовах ([«Инструменты»](https://mcpdocs.ru/concepts/tools/#instrumenty-s-sostoyaniem)). ## Удалённые методы Удалены `ping`, `logging/setLevel` и `notifications/roots/list_changed`. Уровень журнала теперь задаётся для каждого запроса ключом `io.modelcontextprotocol/logLevel` в `_meta`. Серверы НЕ ДОЛЖНЫ отправлять `notifications/message` для запросов, где это поле не указано. ## Задачи стали расширением Экспериментальные задачи вынесены из ядра в официальное расширение `io.modelcontextprotocol/tasks`. Переработанное расширение: - вместо блокирующего `tasks/result` использует опрос через `tasks/get`; - добавляет `tasks/update` для передачи входных данных от клиента серверу; - удаляет `tasks/list`; - позволяет серверам возвращать дескрипторы задач без запроса. ## Потоки SSE Убраны возобновление потоков и повторная доставка. Оборванный поток ответа теряет находящийся в обработке запрос: клиенты ДОЛЖНЫ отправить его заново как новый запрос с новым идентификатором. Подробнее: [«Транспорты»](https://mcpdocs.ru/protocol/transports/#poluchenie-soobscheniy-potok-sse). ## Что ещё изменилось 1. В `ClientCapabilities` и `ServerCapabilities` добавлено поле `extensions` для необязательных расширений. 2. Задокументированы соглашения о передаче контекста трассировки OpenTelemetry в `_meta` (`traceparent`, `tracestate`, `baggage`). 3. Серверам СЛЕДУЕТ возвращать инструменты из `tools/list` в детерминированном порядке: это упрощает кэширование и повышает попадание в кэш подсказок модели. 4. Обязательные стандартные заголовки `Mcp-Method` и `Mcp-Name` в POST-запросах Streamable HTTP и поддержка собственных заголовков из параметров инструментов через `x-mcp-header`. 5. Обязательные поля `ttlMs` и `cacheScope` в результатах `tools/list`, `prompts/list`, `resources/list`, `resources/read` и `resources/templates/list` (интерфейс `CacheableResult`). `ttlMs` — подсказка свежести в миллисекундах, `cacheScope` (`"public"` или `"private"`) определяет, могут ли общие посредники кэшировать ответ. Поля дополняют уведомления `listChanged`. 6. Код ошибки «ресурс не найден» изменён с `-32002` на `-32602`. 7. Серверам авторизации СЛЕДУЕТ включать параметр `iss` в ответы авторизации (RFC 9207), а клиенты ДОЛЖНЫ сверять присутствующий `iss` с записанным эмитентом до обмена кода авторизации. 8. Клиенты ДОЛЖНЫ указывать подходящий `application_type` при динамической регистрации клиента, чтобы избежать конфликтов redirect URI в OpenID Connect. 9. Учётные данные клиента привязаны к серверу авторизации, который их выдал: клиенты ДОЛЖНЫ хранить сохранённые данные с ключом по идентификатору эмитента, НЕ ДОЛЖНЫ использовать их с другим сервером авторизации и ДОЛЖНЫ заново регистрироваться при смене сервера авторизации. 10. `inputSchema` и `outputSchema` допускают любые ключевые слова JSON Schema 2020-12, а `structuredContent` любое значение JSON. Добавлены требования к разрешению `$ref` и пределы ресурсов для конструкций композиции. 11. Удалены уведомление `notifications/elicitation/complete` и поле `elicitationId` у запросов элицитации в режиме URL (появились в 2025-11-25). 12. Введена политика распределения кодов ошибок: `-32000…-32019` остаются реализационными, `-32020…-32099` зарезервированы за спецификацией. ## Новые коды ошибок | Ошибка | Было в черновике | Стало | | --- | --- | --- | | `HeaderMismatch` | `-32001` | `-32020` | | `MissingRequiredClientCapability` | `-32003` | `-32021` | | `UnsupportedProtocolVersion` | `-32004` | `-32022` | Ошибка `HeaderMismatchError` добавлена в схему. Подробнее: [«Ошибки»](https://mcpdocs.ru/protocol/errors/). ## Устаревшие возможности Эти возможности остаются частью спецификации, но их планируют удалить по [политике жизненного цикла функций](https://modelcontextprotocol.io/community/feature-lifecycle). Новым реализациям их принимать НЕ СЛЕДУЕТ. Минимальное окно устаревания — двенадцать месяцев, а все устаревшие функции собраны в [реестре](https://modelcontextprotocol.io/specification/2026-07-28/deprecated). | Что устарело | Чем заменить | | --- | --- | | **Корневые каталоги** (Roots) | Передавать каталоги и файлы параметрами инструментов, URI ресурсов или настройками сервера. | | **Сэмплинг** (Sampling, запрос ответа у модели клиента) | Интегрироваться напрямую с API поставщиков языковых моделей. | | **Журналирование** (Logging, передача журналов клиенту) | Писать в `stderr` (stdio) или использовать OpenTelemetry. | | **Транспорт HTTP+SSE** (устарел с 2025-03-26) | Streamable HTTP. | | Значения `"thisServer"` и `"allServers"` поля `includeContext` (мягко устарели с 2025-11-25) | Не указывать поле или использовать `"none"`. Значения удалят не позднее самого sampling. | | **Динамическая регистрация клиента OAuth** (RFC 7591) | [Документы метаданных ID клиента](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents). Динамическая регистрация остаётся для совместимости с серверами авторизации, которые их не поддерживают. | ## Что менять по ролям Сводка составлена по перечню изменений. **Клиент** - Добавьте в каждый запрос `protocolVersion` и `clientCapabilities` в `_meta`, а по HTTP заголовки `MCP-Protocol-Version`, `Mcp-Method` и `Mcp-Name`. Кодируйте значения по правилам Base64. - Если поддерживаете `x-mcp-header`, дублируйте помеченные параметры в `Mcp-Param-*`; инструменты с некорректной пометкой исключайте из перечня. - Обработайте `UnsupportedProtocolVersionError` и повторяйте запрос с общей версией. - Для двухэпохной поддержки определите эпоху сервера (пробой `server/discover` на stdio, современным запросом по HTTP) и кэшируйте результат. - Считайте отсутствие `resultType` значением `"complete"`; обрабатывайте `"input_required"` повтором запроса. - Подписывайтесь на изменения через `subscriptions/listen`, а не через GET и `resources/subscribe`. Свежесть дополнительно поддерживайте опросом с учётом `ttlMs`. - Заново отправляйте запрос, если поток SSE оборвался. **Сервер** - Реализуйте `server/discover` и перестаньте опираться на состояние соединения и `Mcp-Session-Id`. - Принимайте версию и возможности из `_meta` каждого запроса, возвращайте `serverInfo` в `_meta` результатов и `resultType` во всех результатах. - Добавьте `ttlMs` и `cacheScope` в результаты перечней и `resources/read`, держите детерминированный порядок инструментов. - Проверяйте совпадение заголовков с телом (`HeaderMismatch`, `-32020`), отвечайте `400` на запросы без обязательных полей `_meta`. - Не посылайте запросы клиенту по потоку: используйте `input_required`. Не отправляйте `notifications/message` без `logLevel` в запросе. - На запросы старых клиентов: GET и DELETE на конечную точку `405`, `Mcp-Session-Id` и `Last-Event-ID` игнорируйте. - Для состояния между вызовами используйте явные дескрипторы с авторизацией при каждом вызове. - Проверьте результат бесплатной [проверкой MCP-сервера](https://mcpprotocol.ru/mcp-check/): если сервер отвечает только по прежней ревизии, она скажет об этом отдельным пунктом. > **Заметка переводчика.** Перечень по ролям составлен нами из официального списка изменений, он не копирует отдельного раздела спецификации. Для каждого пункта в оригинале есть соответствующий абзац, а проверка совместимости прежних и современных реализаций описана в [«Версиях и совместимости»](https://mcpdocs.ru/protocol/versions/). ## Расхождения в источниках - В публикациях о ревизии встречается утверждение, что `server/discover` необязателен. В спецификации серверы ДОЛЖНЫ его реализовать, а необязателен лишь его вызов клиентом. --- # Справочник Версии спецификации, SDK, расширения и нормативные источники > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/reference/). Тип: Справочник. Основа: Официальная документация MCP (https://modelcontextprotocol.io/docs/2026-07-28/sdk). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Здесь собраны сведения, к которым удобно возвращаться: какие бывают версии спецификации, где взять SDK, какие расширения есть у протокола и что считать нормативным источником. ## Версии спецификации Версия протокола — дата в формате ГГГГ-ММ-ДД. Текущая — 2026-07-28. Предыдущая — 2025-11-25. | Версия | Эпоха | Что важно знать | Спецификация | | --- | --- | --- | --- | | 2026-07-28 | Современная | Основа этого сайта. Протокол без состояния: нет `initialize` и сессий, версия и возможности в `_meta` каждого запроса. | [specification/2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/index) | | 2025-11-25 | Прежняя | Рукопожатие `initialize`, сессии, Streamable HTTP с `Mcp-Session-Id`. В этой версии появились задачи и элицитация по URL. | [specification/2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/index) | | 2025-06-18 | Прежняя | Версия, в которой определён заголовок `MCP-Protocol-Version`. | [specification/2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/index) | | 2025-03-26 | Прежняя | Здесь появился транспорт Streamable HTTP; HTTP+SSE помечен устаревшим. | [specification/2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/index) | | 2024-11-05 | Прежняя | Самая ранняя ревизия в документации. Транспорт HTTP+SSE. | [specification/2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05/index) | Изменения между версиями собраны в разделе «Key Changes» каждой ревизии. Разбор последнего перехода: [«Миграция на 2026-07-28»](https://mcpdocs.ru/migration/). Совместимость эпох: [«Версии и совместимость»](https://mcpdocs.ru/protocol/versions/). ## Официальные SDK У проекта есть официальные SDK на десяти языках. Какую версию спецификации поддерживает конкретная версия SDK, смотрите в документации самого SDK: не все библиотеки обновились одновременно. Для TypeScript SDK сказано, что v2 — стабильная линия, выпущенная вместе со спецификацией 2026-07-28, а ветка v1.x получает исправления ошибок и безопасности не менее шести месяцев после выхода v2. | Язык | Репозиторий | | --- | --- | | TypeScript и JavaScript | [modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) | | Python | [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) | | Go | [modelcontextprotocol/go-sdk](https://github.com/modelcontextprotocol/go-sdk) | | Java | [modelcontextprotocol/java-sdk](https://github.com/modelcontextprotocol/java-sdk) | | Kotlin | [modelcontextprotocol/kotlin-sdk](https://github.com/modelcontextprotocol/kotlin-sdk) | | C# | [modelcontextprotocol/csharp-sdk](https://github.com/modelcontextprotocol/csharp-sdk) | | Swift | [modelcontextprotocol/swift-sdk](https://github.com/modelcontextprotocol/swift-sdk) | | Rust | [modelcontextprotocol/rust-sdk](https://github.com/modelcontextprotocol/rust-sdk) | | Ruby | [modelcontextprotocol/ruby-sdk](https://github.com/modelcontextprotocol/ruby-sdk) | | PHP | [modelcontextprotocol/php-sdk](https://github.com/modelcontextprotocol/php-sdk) | Эталонные серверы и примеры: [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers). Проверка и отладка: [MCP Inspector](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector). > **Заметка переводчика.** Для SDK введена [система уровней](https://modelcontextprotocol.io/community/sdk-tiers): полнота функций, поддержка версий протокола и обязательства по сопровождению. Прежде чем выбирать библиотеку, посмотрите её уровень. ## Официальные расширения Расширения — необязательные возможности поверх базового протокола. Они объявляются в поле `extensions` в возможностях ([«Версии и совместимость»](https://mcpdocs.ru/protocol/versions/#soglasovanie-rasshireniy)). | Расширение | Для чего | | --- | --- | | [Tasks](https://modelcontextprotocol.io/extensions/tasks/overview) (`io.modelcontextprotocol/tasks`) | Асинхронное выполнение долгих операций: сервер возвращает дескриптор задачи, клиент опрашивает её состояние. | | [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) (`io.modelcontextprotocol/ui`) | Интерактивные интерфейсы, которые отображаются внутри хостов вроде Claude Desktop. | | [Расширения авторизации](https://modelcontextprotocol.io/extensions/auth/overview) | Дополнительные механизмы: клиентские учётные данные OAuth для машинной аутентификации, корпоративное управление авторизацией через поставщиков удостоверений. | | [Skills](https://modelcontextprotocol.io/extensions/skills/overview) | Обнаружение и чтение агентных навыков (Agent Skills) с серверов MCP. | Список клиентов, которые реализуют эти расширения, ведёт [матрица поддержки](https://modelcontextprotocol.io/extensions/client-matrix). ## Реестр серверов [Реестр MCP](https://modelcontextprotocol.io/registry/about) — официальный каталог серверов; обзор на русском есть в [справочнике](https://mcpprotocol.ru/registry/). В документации есть краткое руководство по публикации сервера, описание поддерживаемых типов пакетов, публикации удалённых серверов и автоматизации через GitHub Actions. ## Нормативные источники | Источник | Что это | Статус | | --- | --- | --- | | [Спецификация](https://modelcontextprotocol.io/specification/2026-07-28/index) | Человекочитаемый текст протокола. | Нормативная | | [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/2026-07-28/schema.ts) | Схема на TypeScript. | Источник истины обо всех сообщениях и структурах | | [schema.json](https://github.com/modelcontextprotocol/specification/blob/main/schema/2026-07-28/schema.json) | JSON Schema, создаётся автоматически из схемы TypeScript. | Производный | | [llms.txt](https://modelcontextprotocol.io/llms.txt) | Указатель страниц документации для агентов. | Справочный | | [Предложения по улучшению (SEP)](https://modelcontextprotocol.io/seps/index) | Обоснования изменений протокола. | Справочный | > **Заметка переводчика.** Если текст спецификации и схема расходятся, ориентируйтесь на схему на TypeScript: спецификация называет её источником истины, а JSON Schema создаётся из неё автоматически. --- # Инструменты Проверка сервера и официальные средства > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/tools/). Тип: Справочник. Основа: Проверка MCP-сервера, справочник mcpprotocol.ru (https://mcpprotocol.ru/mcp-check/). Ревизия спецификации 2026-07-28, сверено 05.10.2026. Чтобы убедиться, что сервер соответствует ревизии 2026-07-28, не нужно собирать собственные запросы: есть бесплатная проверка, которая читает ответы сервера и показывает расхождения со спецификацией. Страница рассказывает, что она делает и где описано каждое проверяемое требование. ## Проверка MCP-сервера Проверка находится в справочнике: [mcpprotocol.ru/mcp-check/](https://mcpprotocol.ru/mcp-check/). Её выполняет сервис [AgentReadyScan](https://agentreadyscan.ru/); те же результаты доступны программно. Сайты ведёт один владелец. - Проверка отправляет серверу несколько обычных запросов по Streamable HTTP и сверяет ответы с требованиями ревизии 2026-07-28. - **Инструменты сервера она не вызывает**: читается только список, поэтому не создаются заказы, записи и платежи. - Токены и пароли не принимаются. Закрытый сервер проверяется только в части метаданных авторизации. - Принимаются только публичные адреса и порты 80 и 443. Серверы во внутренних сетях и локальные серверы stdio не проверяются. - Лимит: 10 проверок в час с одного адреса (по данным страницы проверки). - Баллов и процентов нет. Результат говорит, с какими требованиями сервер согласован на дату проверки, а не о «качестве» сервера. Если сервер отвечает только по прежней ревизии (метод `initialize`, сессии), проверка скажет об этом отдельным пунктом: именно с этого стоит начинать обновление ([«Миграция на 2026-07-28»](https://mcpdocs.ru/migration/)). ## Что проверяется и где это описано Состав проверки по описанию на странице сервиса. Правая колонка — страницы этой документации, где требование объяснено. | Группа | Что смотрим | Где описано | | --- | --- | --- | | Доступность | Сервер отвечает на POST и работает по HTTPS. | [«Транспорты»](https://mcpdocs.ru/protocol/transports/#otpravka-soobscheniy) | | Обнаружение | Метод `server/discover` работает; указаны версии, возможности, `ttlMs`, `cacheScope`, `resultType`; сервер называет себя. | [«Обнаружение»](https://mcpdocs.ru/concepts/discovery/) | | Версия и заголовки | Неизвестная версия даёт `400` и `-32022`; расхождения в `MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name` дают `400` и `-32020`; неизвестный метод даёт `404` и `-32601`; GET даёт `405`; чужой `Origin` даёт `403`. | [«Транспорты»](https://mcpdocs.ru/protocol/transports/#zagolovki-metadannyh-zaprosa), [«Ошибки»](https://mcpdocs.ru/protocol/errors/), [«Версии и совместимость»](https://mcpdocs.ru/protocol/versions/) | | Инструменты | Список работает; есть `ttlMs` и `cacheScope`; порядок стабилен; у каждого инструмента есть описание и схема параметров. | [«Инструменты»](https://mcpdocs.ru/concepts/tools/) | | Авторизация | Если сервер закрыт: ответ `401` указывает метаданные ресурса, в них есть `authorization_servers`, сервер авторизации объявляет PKCE S256. | [«Авторизация» справочника](https://mcpprotocol.ru/authorization/); раздел [«Безопасность»](https://mcpdocs.ru/security/) здесь готовится | Результат каждого пункта называется «Нарушено» (не выполнено требование MUST), «Проверьте» (рекомендация SHOULD или спорный случай), «Выполнено» или «К сведению». > **Заметка переводчика.** Сайты написаны разными жанрами, поэтому формулировки пунктов проверки здесь пересказаны со страницы сервиса, а нормативный текст требований смотрите в таблицах «Где описано». ## Официальные средства проекта - [MCP Inspector](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector): интерактивный инструмент проверки и отладки серверов в браузере, в командной строке и в терминале. - [Debugging](https://modelcontextprotocol.io/docs/2026-07-28/tools/debugging): руководство по отладке интеграций. - [Эталонные серверы](https://github.com/modelcontextprotocol/servers): примеры реализаций. ## Что ещё Проверка только одного пункта списка не заменяет чтения спецификации. Требования к самим инструментам (права, безопасность вызовов) нужно проверять отдельно: список рекомендаций есть на странице [«Инструменты (tools)»](https://mcpdocs.ru/concepts/tools/#bezopasnost). --- # О проекте Статус перевода, принципы и лицензия > Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/about/). Тип: Справочник. Ревизия спецификации 2026-07-28, сверено 05.10.2026. MCP Docs — русскоязычный справочный сайт по Model Context Protocol (MCP). Он содержит перевод и пересказ официальной документации и спецификации, а со временем и авторские разборы. Сайт неофициальный. ## Статус - Сайт не является официальным ресурсом проекта MCP. Оригинал находится на [modelcontextprotocol.io](https://modelcontextprotocol.io/). - Основа перевода — ревизия спецификации 2026-07-28. Дата последней сверки указана в шапке каждой страницы. - Если перевод и оригинал расходятся, верен оригинал. - Источником истины о сообщениях и структурах служит схема на TypeScript (`schema.ts`), а не текст сайта. ## Как отмечены страницы В шапке каждой страницы стоит отметка о том, чем она является. | Отметка | Что это | | --- | --- | | Перевод | Близкий к тексту перевод раздела оригинала. Таблицы и перечни сохранены. | | Перевод и пересказ | Часть материала переведена близко к тексту, часть пересказана и собрана из нескольких мест оригинала. | | Авторский разбор | Текст, написанный нами на основе документации. Такие страницы будут отмечены отдельно. | | Справочник | Сводные сведения со ссылками на источники. | | Раздел готовится | Страница-заглушка: перевода ещё нет. Такие страницы закрыты от индексации. | Рядом с отметкой указан раздел оригинала, на котором основана страница. ## Принципы перевода - **Нормативные слова** в стиле RFC 2119 передаются так: MUST — ДОЛЖЕН, MUST NOT — НЕ ДОЛЖЕН, SHOULD — СЛЕДУЕТ, SHOULD NOT — НЕ СЛЕДУЕТ, MAY — МОЖЕТ. В тексте сайта они выделены заглавными буквами. - **Имена** методов, полей, ошибок, заголовков и значений остаются как в оригинале и набираются моноширинным шрифтом. - **Термины** при первом появлении даются с оригинальным названием: «инструмент (tool)», «ресурс (resource)», «шаблон запроса (prompt)». Слова host, client и server переводятся как «хост», «клиент» и «сервер». - **Заметки переводчика** на полях отмечают места, где перевод неоднозначен или где в источниках есть расхождения. - **Примеры кода** берутся из оригинала. Если мы составляем пример сами, это сказано рядом. - Терминология согласована с [глоссарием mcpprotocol.ru](https://mcpprotocol.ru/glossary/) (38 терминов с английскими оригиналами): при первом упоминании термина у слова стоит определение со ссылкой на глоссарий. Там, где в оригинале нет устоявшегося русского слова, мы следуем глоссарию. ## Лицензии и авторство Проект MCP передан компанией Anthropic в Agentic AI Foundation, фонд при Linux Foundation. Для материалов проекта действуют условия, которые описаны в его документации для участников. - **Код и спецификации:** Apache License 2.0. - **Документация** (кроме спецификаций): Creative Commons Attribution 4.0 (CC BY 4.0). - Проект переходит с лицензии MIT на Apache-2.0: ранние вклады авторов, которые не согласились на смену лицензии, остаются под MIT. Материалы этого сайта — производная работа от оригинальной документации и спецификации. - Лицензии: [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) и [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). - Оригинальный проект: [github.com/modelcontextprotocol/modelcontextprotocol](https://github.com/modelcontextprotocol/modelcontextprotocol). - **Внесённые изменения:** перевод на русский язык; сокращение, пересказ и перегруппировка материала; добавление пояснений и заметок переводчика; оформление. - Название MCP и знаки принадлежат их правообладателям. Сайт не использует логотипы проекта и не выдаёт себя за официальный. ## Связанные сайты - [mcpprotocol.ru](https://mcpprotocol.ru/): справочник по MCP. Он отвечает на вопросы «что это» и «как называется»: определения, глоссарий, сравнение с A2A, авторизация, реестр серверов, MCP в коммерции и бесплатная [проверка сервера](https://mcpprotocol.ru/mcp-check/). Здесь, на MCP Docs, разбирается устройство протокола: методы, заголовки, ошибки, миграция. Определения лучше цитировать по справочнику, а описание сообщений и заголовков по этому сайту. - [A2A Docs](https://a2adocs.ru/): документация протокола Agent2Agent на русском. MCP связывает агента с инструментами и данными, A2A связывает агентов между собой; сравнение протоколов есть на странице [«A2A и MCP»](https://a2aprotocol.ru/a2a-vs-mcp/) справочника a2aprotocol.ru. Все три сайта ведёт один владелец. ## Сообщить об ошибке Нашли неточность в переводе или устаревшее место? Напишите на [info@mcpdocs.ru](mailto:info@mcpdocs.ru). Укажите адрес страницы и фрагмент: так мы быстрее проверим его по оригиналу. ## Кто ведёт сайт Справочный сайт. Владелец: ООО «САРМАТЕХ», ИНН 4725011864. ## Машиночитаемые версии Каждая страница сайта доступна и в виде Markdown: добавьте к адресу страницы `index.md` или нажмите «Открыть .md» в шапке страницы. Весь сайт одним файлом: [llms-full.txt](https://mcpdocs.ru/llms-full.txt). Список страниц для ИИ-агентов: [llms.txt](https://mcpdocs.ru/llms.txt). --- # Руководства Подключить готовый сервер, написать свой, подключить 1С > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/guides/). Тип: Руководство. Код проверен: Python 3.13, пакет mcp 2.3.0; Node.js 22, @modelcontextprotocol/server 2.3.1, @modelcontextprotocol/client 2.3.1. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Авторские руководства MCP Docs. В отличие от перевода, здесь пошаговые инструкции и код. Весь код в руководствах запущен на официальных SDK, которые поддерживают ревизию 2026-07-28, и проверен клиентом. _Маршрут по руководствам: подключить готовый сервер, написать свой, закрыть авторизацией, хранить состояние, подключить базу 1С._ ## Подключение готовых серверов - [Как подключить MCP-сервер](https://mcpdocs.ru/podklyuchenie/): общий порядок, форматы настроек, частые ошибки - [Claude Desktop](https://mcpdocs.ru/podklyuchenie/claude-desktop/) · [Claude Code](https://mcpdocs.ru/podklyuchenie/claude-code/) · [Cursor](https://mcpdocs.ru/podklyuchenie/cursor/) · [VS Code](https://mcpdocs.ru/podklyuchenie/vs-code/) · [OpenCode](https://mcpdocs.ru/podklyuchenie/opencode/) - [MCP-серверы Yandex Cloud](https://mcpdocs.ru/podklyuchenie/yandex/): поиск Яндекса, документация, бессерверные функции Готовые серверы с описанием и датой проверки — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/) справочника. ## Свой MCP-сервер - [Свой сервер на Python](https://mcpdocs.ru/svoy-server/): инструмент, ресурс и шаблон запроса, проверка, запуск по stdio и HTTP - [Свой сервер на TypeScript](https://mcpdocs.ru/svoy-server/typescript/): тот же сервер на SDK v2 - [Авторизация (OAuth)](https://mcpdocs.ru/svoy-server/avtorizatsiya/): как закрыть удалённый сервер токенами - [Память и состояние](https://mcpdocs.ru/svoy-server/pamyat/): данные между вызовами без сессий, сервер памяти на SQLite ## MCP и 1С - [MCP и 1С](https://mcpdocs.ru/1c/): что можно сделать и с чего начать - [Что даёт MCP программисту 1С](https://mcpdocs.ru/1c/chto-dayot/) · [MCP в 1С:EDT](https://mcpdocs.ru/1c/edt/) · [MCP-сервер для базы 1С](https://mcpdocs.ru/1c/napisat-server/) · [Примеры и разборы](https://mcpdocs.ru/1c/primery/) ## Как мы проверяли код **Версии, на которых запускался код руководств (13.10.2026)** | Что | Версия | |---|---| | Python SDK | `mcp` 2.3.0 на Python 3.13 | | TypeScript SDK | `@modelcontextprotocol/server` 2.3.1, `@modelcontextprotocol/client` 2.3.1, `@modelcontextprotocol/node` 2.1.1, `zod` 4.6.7 на Node.js 22 | | Ревизия протокола | 2026-07-28 | | Проверка | каждый пример запущен по stdio и Streamable HTTP, вызван клиентом SDK; для авторизации и 1С — против имитации сервера авторизации и интерфейса OData | > Многие клиенты на дату проверки ещё работают по ревизии 2025-11-25 и открывают сессии. SDK второй версии обслуживает обе эпохи из одного кода: писать сервер отдельно под старых клиентов не нужно. Подробнее — в разделе [«Версии и совместимость»](https://mcpdocs.ru/protocol/versions/). --- # Как подключить MCP-сервер Общий порядок для любого клиента: команда или адрес, файл настроек, проверка > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/podklyuchenie/). Тип: Руководство. Форматы сверены с документацией клиентов и SDK 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Любой MCP-сервер подключается одинаково: клиенту нужно знать либо команду, которая запускает локальный сервер, либо адрес удалённого. Отличаются только файл настроек и его формат. _Подключение в пять шагов: узнать команду или адрес сервера, вписать в настройки клиента, перезапустить клиент, увидеть инструменты, разрешить вызов._ ## Что нужно знать о сервере **Два вида серверов** | | Локальный | Удалённый | |---|---|---| | Что указать клиенту | Команду запуска и её аргументы | Адрес, обычно с окончанием `/mcp` | | Транспорт | stdio | Streamable HTTP | | Вход | Обычно не нужен; ключи передают в переменных окружения | OAuth в браузере или токен в заголовке `Authorization` | | Пример | `npx @playwright/mcp@latest` | `https://mcp.atlassian.com/v2/mcp` | Команду или адрес берите из документации сервера. В [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/) они вынесены в карточку каждого сервера. ## Порядок подключения 1. **Найдите настройки клиента.** У каждого клиента свой файл или своя команда — ссылки ниже. 2. **Добавьте сервер.** Для локального — команду, аргументы и переменные окружения, для удалённого — адрес и, если нужно, заголовки. 3. **Перезапустите клиент.** Многие клиенты читают настройки только при запуске; Claude Desktop нужно закрыть полностью, а не только окно. 4. **Проверьте список инструментов.** В клиенте должен появиться сервер и его инструменты. 5. **Разрешайте вызовы осознанно.** Клиент спросит согласие перед вызовом инструмента. Постоянное разрешение давайте только инструментам, которые ничего не меняют. ## Форматы настроек **Где клиенты хранят список серверов** | Клиент | Где | Ключ | Руководство | |---|---|---|---| | Claude Desktop | `claude_desktop_config.json` | `mcpServers` | [Claude Desktop](https://mcpdocs.ru/podklyuchenie/claude-desktop/) | | Claude Code | команда `claude mcp add` или `.mcp.json` | `mcpServers` | [Claude Code](https://mcpdocs.ru/podklyuchenie/claude-code/) | | Cursor | `~/.cursor/mcp.json` или `.cursor/mcp.json` | `mcpServers` | [Cursor](https://mcpdocs.ru/podklyuchenie/cursor/) | | VS Code | `.vscode/mcp.json` | `servers` | [VS Code](https://mcpdocs.ru/podklyuchenie/vs-code/) | | OpenCode | `opencode.json` | `mcp` | [OpenCode](https://mcpdocs.ru/podklyuchenie/opencode/) | Самый распространённый формат — объект `mcpServers`. Так выглядит локальный сервер: _Локальный сервер в формате mcpServers_ ```json { "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"], "env": { "PLAYWRIGHT_BROWSERS_PATH": "/opt/browsers" } } } } ``` А так — удалённый в Cursor и других клиентах, которые принимают поле `url`: _Удалённый сервер в формате mcpServers_ ```json { "mcpServers": { "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" } } } ``` ## Где хранить ключи - Не вписывайте ключи в файлы, которые попадают в репозиторий: `.mcp.json`, `.vscode/mcp.json`, `.cursor/mcp.json` в папке проекта. - Передавайте ключ через переменную окружения (`env` для локального сервера) или используйте подстановку, если клиент её поддерживает: в VS Code — `${input:…}` с запросом пароля, в OpenCode — `{env:ИМЯ}`. - Если удалённый сервер поддерживает OAuth, выбирайте вход через браузер, а не постоянный токен: доступ можно отозвать, а токен живёт недолго. ## Как проверить сервер без клиента MCP Inspector — официальное приложение, которое запускает сервер и показывает его инструменты, ресурсы и шаблоны. Удобно, чтобы отделить ошибки сервера от ошибок настройки клиента: _Запуск MCP Inspector для локального сервера_ ```bash npx @modelcontextprotocol/inspector npx @playwright/mcp@latest ``` Удалённый сервер на соответствие ревизии 2026-07-28 можно проверить [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/) справочника. ## Частые ошибки **Признаки и причины** | Признак | Причина | Что сделать | |---|---|---| | Сервер не запускается, в журнале `ENOENT` или «command not found» | Клиент не находит `npx`, `uvx` или `python`: он запускает сервер с урезанной переменной `PATH` | Укажите полный путь к команде (`which uvx` на macOS и Linux, `where uvx` в Windows) | | В Windows не запускается `npx` | Команду нужно запускать через оболочку | `"command": "cmd", "args": ["/c", "npx", …]` | | Сервер запускается и сразу отключается | Сервер пишет журнал в стандартный вывод и ломает обмен | Писать журнал только в stderr; для чужого сервера — сообщить автору | | Файл или папка «не найдены» | Относительный путь: клиент запускает сервер из своей рабочей папки | Только абсолютные пути | | Удалённый сервер отвечает `401` | Нужен вход или токен | Пройти вход в браузере или добавить заголовок `Authorization` | | В инструкции адрес оканчивается на `/sse` | Устаревший транспорт HTTP+SSE | Взять у поставщика адрес Streamable HTTP; если его нет, нужен клиент, который ещё поддерживает SSE | | Инструментов слишком много, модель путается | Сервер открывает десятки инструментов | Отключить лишние в настройках клиента или сервера (у многих серверов есть группы инструментов) | --- # Подключение MCP-сервера в Claude Desktop Локальные серверы — в файле настроек, удалённые — через коннекторы > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/podklyuchenie/claude-desktop/). Тип: Руководство. Сверено с документацией SDK и поставщиков серверов 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. В Claude для компьютера два пути. Локальные серверы, которые приложение запускает само, описывают в файле `claude_desktop_config.json`. Удалённые подключают в разделе «Коннекторы» по адресу HTTPS. _Claude Desktop: локальный сервер запускается по команде из файла настроек, удалённый подключается как коннектор по адресу HTTPS._ ## Где файл настроек **Расположение claude_desktop_config.json** | Система | Путь | |---|---| | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | Если папки нет, установите Claude Desktop и запустите его один раз: папка появится. ## Локальный сервер Добавьте сервер в объект `mcpServers`. Пример для эталонного сервера файлов: он видит только перечисленные папки. _claude_desktop_config.json_ ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"] }, "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"], "env": { "MEMORY_FILE_PATH": "/Users/me/.claude-memory.jsonl" } } } } ``` Полностью закройте Claude Desktop (не только окно) и откройте снова. Сервер появится в списке инструментов окна чата. > Claude Desktop запускает сервер в собственном процессе: переменные окружения вашей оболочки туда не попадают. Всё, что нужно серверу, передавайте в `env`, а пути к командам и файлам пишите полностью. ## Свой сервер на Python: команда mcp install Если сервер написан на официальном Python SDK, запись в файл настроек можно не писать руками: _Регистрация сервера в Claude Desktop_ ```bash uv run mcp install server.py # с переменными окружения: uv run mcp install server.py -v API_KEY=abc123 ``` Команда сама находит файл настроек, превращает путь в абсолютный и закрепляет версию SDK. Как написать такой сервер — в руководстве [«Свой сервер на Python»](https://mcpdocs.ru/svoy-server/). ## Удалённый сервер Удалённые серверы добавляют в настройках приложения: Settings → Connectors → Add custom connector — и указывают адрес сервера. Если сервер закрыт OAuth, Claude откроет вход в браузере. > Свой коннектор подключается из облака Anthropic, поэтому адрес должен быть доступен из интернета по HTTPS. Сервер на `localhost` так не подключить. ## Сервер на localhost по HTTP: мост mcp-remote Файл настроек принимает только локальные серверы с командой. Чтобы подключить сервер, который слушает HTTP на вашем компьютере (например, [EDT MCP Server](https://mcpdocs.ru/1c/edt/) на порту 8765), используют мост `mcp-remote`: он запускается как локальный сервер и пересылает запросы по HTTP. _claude_desktop_config.json — мост к серверу на localhost_ ```json { "mcpServers": { "edt": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:8765/mcp"] } } } ``` ## Если сервер не появился - Проверьте, что файл — корректный JSON: лишняя запятая ломает весь файл. - Укажите полный путь к `npx`, `uvx` или `python`, если приложение их не находит. - Запустите сервер в [MCP Inspector](https://mcpdocs.ru/podklyuchenie/#inspector): если он не работает и там, дело в сервере, а не в настройках. Другие ошибки — в разделе [«Частые ошибки»](https://mcpdocs.ru/podklyuchenie/#oshibki). --- # Подключение MCP-сервера в Claude Code Команда claude mcp add, области видимости и общий файл проекта > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/podklyuchenie/claude-code/). Тип: Руководство. Сверено с документацией SDK и поставщиков серверов 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. В Claude Code серверы подключают командой в терминале, не в окне Claude Code. Всё, что стоит после двух дефисов, — команда запуска локального сервера. _Claude Code хранит серверы в трёх областях: только для вас в этом проекте, для всех участников проекта через .mcp.json и для вас во всех проектах._ ## Локальный сервер _Добавить локальный сервер_ ```bash claude mcp add playwright -- npx @playwright/mcp@latest # с переменной окружения claude mcp add godot -e GODOT_PATH=/opt/godot/godot -- npx @coding-solo/godot-mcp # свой сервер на Python SDK claude mcp add catalog -- uv run --with "mcp[cli]" mcp run /абсолютный/путь/server.py ``` ## Удалённый сервер В версиях Claude Code 2.1.1 и новее удалённый сервер удобно добавлять описанием в JSON: _Добавить удалённый сервер с токеном_ ```bash claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer ВАШ_ТОКЕН"}}' ``` В более старых версиях — так: _Прежний формат команды_ ```bash claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer ВАШ_ТОКЕН" ``` Если сервер поддерживает OAuth, заголовок не нужен: Claude Code предложит войти через браузер. ## Области видимости **Ключ --scope** | Область | Где действует | Где хранится | |---|---|---| | `local` (по умолчанию) | Только у вас и только в текущем проекте | Ваши настройки Claude Code | | `project` | У всех, кто работает с проектом | Файл `.mcp.json` в корне проекта | | `user` | У вас во всех проектах | Ваши настройки Claude Code | _Сервер для всех участников проекта_ ```bash claude mcp add --scope project playwright -- npx @playwright/mcp@latest ``` > Файл `.mcp.json` попадает в репозиторий. Не вписывайте в него токены: передавайте их через переменные окружения каждого участника. ## Проверка _Список серверов и подробности_ ```bash claude mcp list claude mcp get playwright ``` Внутри сеанса Claude Code команда `/mcp` показывает, к каким серверам есть подключение и какие у них инструменты. ## Если что-то не так - В Windows команда `claude mcp add-json` для HTTP-сервера иногда отвечает `Invalid input` — используйте прежний формат с `--transport http`. - Если команда запуска сервера не находится, укажите её полный путь. - Остальное — в разделе [«Частые ошибки»](https://mcpdocs.ru/podklyuchenie/#oshibki). --- # Подключение MCP-сервера в Cursor Файл mcp.json для всех проектов или для одного > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/podklyuchenie/cursor/). Тип: Руководство. Сверено с документацией поставщиков серверов 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Cursor хранит список серверов в файле `mcp.json` с объектом `mcpServers`. Файл в домашней папке действует во всех проектах, файл в папке проекта — только в нём. _Cursor читает серверы из двух файлов: общего для всех проектов и файла в папке проекта._ ## Где файл **Файлы настроек Cursor** | Область | Файл | |---|---| | Все проекты | `~/.cursor/mcp.json` | | Один проект | `.cursor/mcp.json` в корне проекта | Сервер можно добавить и из интерфейса: Cursor Settings → Tools & Integrations → MCP → добавить сервер. Многие поставщики публикуют кнопку установки в Cursor, которая заполняет эти настройки сама. ## Локальный сервер _.cursor/mcp.json_ ```json { "mcpServers": { "framelink-figma": { "command": "npx", "args": ["-y", "figma-developer-mcp", "--figma-api-key=ВАШ_КЛЮЧ", "--stdio"] } } } ``` ## Удалённый сервер Для удалённого сервера достаточно адреса. Если сервер принимает токен, добавьте заголовок: _~/.cursor/mcp.json_ ```json { "mcpServers": { "github": { "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ВАШ_ТОКЕН" } }, "edt": { "url": "http://localhost:8765/mcp" } } } ``` Cursor поддерживает вход через OAuth для части серверов; тогда заголовок не нужен. ## Проверка 1. Полностью перезапустите Cursor. 2. В Settings → Tools & Integrations → MCP у сервера должна гореть зелёная точка. 3. В чате агента сервер и его инструменты появятся в списке доступных. > По опыту разработчиков EDT MCP Server, Cursor не показывает модели встроенные ресурсы в ответах инструментов (embedded resources). Если сервер возвращает результат так, ищите у него режим «простого текста» — у EDT MCP Server он есть. Не вписывайте токены в `.cursor/mcp.json` проекта, если папка попадает в репозиторий. Другие ошибки — в разделе [«Частые ошибки»](https://mcpdocs.ru/podklyuchenie/#oshibki). --- # Подключение MCP-сервера в VS Code Файл .vscode/mcp.json, ключ servers и запрос токена при запуске > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/podklyuchenie/vs-code/). Тип: Руководство. Сверено с документацией поставщиков серверов 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. VS Code подключает MCP-серверы для GitHub Copilot в режиме агента. Формат отличается от других клиентов: список лежит в ключе `servers`, а у сервера указывают тип. _VS Code берёт серверы из .vscode/mcp.json; секреты запрашивает у пользователя при запуске и не хранит в файле._ ## Файл .vscode/mcp.json _.vscode/mcp.json — локальный и удалённый сервер_ ```json { "servers": { "playwright": { "type": "stdio", "command": "npx", "args": ["@playwright/mcp@latest"] }, "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" } } } ``` Файл можно положить в репозиторий: участники проекта получат те же серверы. ## Токен без записи в файл Чтобы не хранить токен в репозитории, объявите его в `inputs`. VS Code спросит значение при первом запуске сервера и сохранит его в защищённом хранилище: _.vscode/mcp.json — запрос токена_ ```json { "servers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${input:github_pat}" } } }, "inputs": [ { "type": "promptString", "id": "github_pat", "description": "Токен GitHub", "password": true } ] } ``` ## Добавить сервер из командной строки _Команда code --add-mcp_ ```bash code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}' ``` ## Проверка Откройте чат Copilot в режиме агента: подключённые серверы и их инструменты видны в списке инструментов. Если сервер не запустился, причину покажет вывод сервера в панели Output. Другие ошибки — в разделе [«Частые ошибки»](https://mcpdocs.ru/podklyuchenie/#oshibki). --- # Подключение MCP-сервера в OpenCode Раздел mcp в opencode.json: локальные и удалённые серверы > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/podklyuchenie/opencode/). Тип: Руководство. Сверено с документацией поставщиков серверов 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. OpenCode — агент для работы с кодом в терминале. Серверы MCP он берёт из раздела `mcp` файла `opencode.json` (или `opencode.jsonc`): обычно `~/.config/opencode/opencode.json` или файл в корне проекта. _OpenCode описывает серверы в разделе mcp: local — команда массивом, remote — адрес; секреты подставляются из переменных окружения._ ## Удалённый сервер _opencode.json — ВкусВилл MCP_ ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "vkusvill": { "type": "remote", "url": "https://mcp.vkusvill.ru/mcp", "enabled": true } } } ``` Если сервер принимает токен, а не OAuth, укажите заголовок и отключите автоматический поиск OAuth: _opencode.json — токен из переменной окружения_ ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "github": { "type": "remote", "url": "https://api.githubcopilot.com/mcp/", "enabled": true, "oauth": false, "headers": { "Authorization": "Bearer {env:GITHUB_PERSONAL_ACCESS_TOKEN}" } } } } ``` ## Локальный сервер У локального сервера команда записывается массивом, переменные окружения — в `environment`: _opencode.json — локальный сервер_ ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "playwright": { "type": "local", "command": ["npx", "@playwright/mcp@latest"], "enabled": true }, "yandex-search": { "type": "local", "command": ["npx", "-y", "@yandex-cloud/mcp", "-s", "search"], "enabled": true } } } ``` ## На что обратить внимание - Серверы с десятками инструментов заметно расходуют контекст модели. Отключайте лишние серверы полем `"enabled": false` и сужайте набор инструментов, если сервер это позволяет. - Подстановка `{env:ИМЯ}` берёт значение из окружения, в котором запущен OpenCode: задайте переменную до запуска. Другие ошибки — в разделе [«Частые ошибки»](https://mcpdocs.ru/podklyuchenie/#oshibki). --- # MCP-серверы Яндекса: подключение Yandex Cloud MCP Поиск Яндекса, документация и бессерверные сервисы в любом MCP-клиенте > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/podklyuchenie/yandex/). Тип: Руководство. Сверено с документацией Yandex Cloud (обновлена 25.09.2026) и репозиторием yandex-cloud/mcp 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Яндекс публикует десять официальных MCP-серверов Yandex Cloud. Самый востребованный — сервер поиска Яндекса: классический и генеративный веб-поиск для ИИ-ассистента. Каждый сервер доступен удалённо по Streamable HTTP и локально через npm-пакет. _Два способа: локальный пакет @yandex-cloud/mcp с входом через браузер или удалённый адрес с IAM-токеном в заголовке._ ## Какие есть серверы **MCP-серверы Yandex Cloud (по документации от 25.09.2026)** | Имя для -s | Что делает | Адрес Streamable HTTP | |---|---|---| | `search` | Поиск Яндекса: классический и генеративный | `https://search.mcp.cloud.yandex.net/mcp` | | `docs` | Поиск по документации Yandex Cloud | `https://docs.mcp.cloud.yandex.net/mcp` | | `toolkit` | Развёртывание приложений: Compute Cloud, VPC, IAM, Object Storage, YDB | `https://toolkit.mcp.cloud.yandex.net/mcp` | | `functions` | Бессерверные функции (предварительная версия) | `https://functions.mcp.cloud.yandex.net/mcp` | | `containers` | Бессерверные контейнеры | `https://containers.mcp.cloud.yandex.net/mcp` | | `triggers` | Триггеры (предварительная версия) | `https://triggers.mcp.cloud.yandex.net/mcp` | | `workflows` | Рабочие процессы (предварительная версия) | `https://workflows.mcp.cloud.yandex.net/mcp` | | `apigateway` | API Gateway (предварительная версия) | `https://apigateway.mcp.cloud.yandex.net/mcp` | | `mcpgateway` | MCP Gateway (предварительная версия) | `https://mcpgateway.mcp.cloud.yandex.net/mcp` | | `datacatalog-consumer` | Поиск в Data Catalog | `https://datacatalog-consumer.mcp.cloud.yandex.net/mcp` | Для работы большинства серверов нужны роли Yandex Cloud для соответствующего сервиса. ## Локальный режим: вход через браузер Пакет `@yandex-cloud/mcp` запускает нужный сервер по stdio. По умолчанию вход выполняется через OAuth в браузере. Нужен Node.js 18 или новее. _Поиск Яндекса в Claude Desktop или Cursor_ ```json { "mcpServers": { "yandex-search": { "command": "npx", "args": ["-y", "@yandex-cloud/mcp", "-s", "search"] } } } ``` Варианты входа: `-S ` или `-u <почта>` — явный выбор учётной записи; `-p <профиль>` — вход через Yandex Cloud CLI (`yc`). ## Удалённый режим: IAM-токен Получите IAM-токен через Yandex Cloud CLI и передайте его в заголовке: _IAM-токен пользователя или сервисного аккаунта_ ```bash yc iam create-token yc iam create-token --impersonate-service-account-id ``` _Удалённый сервер в Cursor_ ```json { "mcpServers": { "yandex-search": { "url": "https://search.mcp.cloud.yandex.net/mcp", "headers": { "Authorization": "Bearer " } } } } ``` > IAM-токен живёт не более 12 часов, потом его нужно выпустить заново. Для постоянной работы удобнее локальный режим с входом через браузер или сервисный аккаунт с минимальными ролями. ## Yandex AI Studio как клиент В Yandex AI Studio есть MCP Hub: к агентам AI Studio можно подключать MCP-серверы, в том числе созданные из шаблонов. Порядок — в документации AI Studio: [MCP Hub](https://yandex.cloud/ru/docs/ai-studio/concepts/mcp-hub). ## Где ещё MCP у Яндекса В Yandex Cloud Marketplace опубликованы готовые MCP-серверы для развёртывания в облаке (например, для Redis и n8n). Карточка серверов Yandex Cloud в каталоге справочника: [MCP-серверы Yandex Cloud](https://mcpprotocol.ru/katalog/yandex-cloud/). --- # Как написать свой MCP-сервер на Python Инструмент, ресурс и шаблон запроса на официальном SDK — с проверкой и запуском по stdio и HTTP > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/svoy-server/). Тип: Руководство. Код проверен: Python 3.13, пакет mcp 2.3.0 — в памяти, по stdio и по HTTP. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Соберём небольшой сервер каталога товаров: один инструмент, один ресурс и один шаблон запроса. Официальный Python SDK второй версии сам строит схемы параметров, разбирает сообщения и отвечает по ревизии 2026-07-28 — остаётся написать функции. _Путь сервера: три функции с декораторами, проверка в памяти, запуск по stdio для локальных клиентов или по HTTP для удалённых._ ## Установка Нужен Python 3.10 или новее. _Установка SDK_ ```bash pip install "mcp[cli]" # или в проекте на uv: uv add "mcp[cli]" ``` Дополнение `[cli]` ставит команду `mcp`: `mcp dev` для проверки в MCP Inspector, `mcp run` для запуска и `mcp install` для регистрации в Claude Desktop. ## Код сервера _catalog_server.py_ ```python """MCP-сервер «Каталог»: инструмент, ресурс и шаблон запроса.""" import sys from mcp.server import MCPServer mcp = MCPServer("Каталог", instructions="Каталог мебели: поиск товаров и остатков.") PRODUCTS = [ {"sku": "A-100", "name": "Стол обеденный", "price": 18900, "stock": 4}, {"sku": "A-200", "name": "Стул мягкий", "price": 5400, "stock": 0}, {"sku": "B-310", "name": "Полка настенная", "price": 2300, "stock": 17}, ] @mcp.tool() def find_products(query: str, in_stock_only: bool = False) -> list[dict]: """Найти товары по части названия. price — цена в рублях, stock — остаток.""" q = query.lower() return [ p for p in PRODUCTS if q in p["name"].lower() and (p["stock"] > 0 or not in_stock_only) ] @mcp.resource("catalog://categories") def categories() -> str: """Разделы каталога.""" return "Столы\nСтулья\nПолки" @mcp.prompt() def compare(first_sku: str, second_sku: str) -> str: """Сравнить два товара по артикулу.""" return f"Сравни товары {first_sku} и {second_sku}: цена, наличие, назначение." if __name__ == "__main__": if "--http" in sys.argv: mcp.run(transport="streamable-http", host="127.0.0.1", port=8000) else: mcp.run() # stdio по умолчанию ``` Что здесь происходит: - `@mcp.tool()` превращает функцию в [инструмент](https://mcpdocs.ru/concepts/tools/). Имя, описание и схему параметров SDK берёт из имени функции, строки документации и подсказок типов: `query: str, in_stock_only: bool = False` и есть схема. - Возвращаемый тип `list[dict]` даёт структурированный результат: клиент получит и текст, и поле `structuredContent`. - `@mcp.resource("catalog://categories")` — [ресурс](https://mcpdocs.ru/concepts/resources/): данные, которые приложение само подкладывает модели. - `@mcp.prompt()` — [шаблон запроса](https://mcpdocs.ru/concepts/prompts/), который пользователь выбирает явно. - `mcp.run()` без аргументов — транспорт stdio. Запуск стоит под `if __name__ == "__main__"`, потому что команды `mcp dev` и `mcp run` импортируют файл. > По stdio стандартный вывод — это канал протокола. Не используйте `print()` для отладки: пишите журнал через модуль `logging`, он выводит в stderr. ## Проверка без клиента SDK содержит клиент, который подключается к объекту сервера прямо в памяти — без процесса и порта. Это основа автотестов: _test_server.py_ ```python """Проверка сервера без клиента и без процесса: Client(mcp) подключается в памяти.""" import asyncio from mcp import Client from catalog_server import mcp async def main() -> None: async with Client(mcp) as client: tools = await client.list_tools() print([t.name for t in tools.tools]) result = await client.call_tool("find_products", {"query": "стол", "in_stock_only": True}) print(result.structured_content) res = await client.read_resource("catalog://categories") print(res.contents[0].text) asyncio.run(main()) ``` _Вывод_ ```text ['find_products'] {'result': [{'sku': 'A-100', 'name': 'Стол обеденный', 'price': 18900, 'stock': 4}]} Столы Стулья Полки ``` Посмотреть сервер глазами клиента можно в MCP Inspector (нужен Node.js): `uv run mcp dev catalog_server.py`. ## Запуск по HTTP Тот же сервер становится удалённым одной строкой: `mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)`. В примере это включает ключ `--http`: _Запуск_ ```bash python catalog_server.py --http # адрес сервера: http://127.0.0.1:8000/mcp ``` _client_http.py_ ```python """Клиент для сервера, запущенного командой: python catalog_server.py --http""" import asyncio from mcp import Client async def main() -> None: async with Client("http://127.0.0.1:8000/mcp") as client: result = await client.call_tool("find_products", {"query": "полка"}) print(result.structured_content) asyncio.run(main()) ``` Параметры транспорта передаются в `run()`, а не в конструктор `MCPServer`: конструктор описывает, что это за сервер, `run()` — как его обслуживать. ## Что уходит по сети По ревизии 2026-07-28 рукопожатия нет: каждый запрос несёт версию и возможности клиента в `_meta`. Клиент может сначала вызвать `server/discover`. Вот настоящий ответ нашего сервера (тексты раскодированы): _Ответ на server/discover_ ```json { "jsonrpc": "2.0", "id": 1, "result": { "resultType": "complete", "supportedVersions": ["2026-07-28"], "capabilities": { "tools": {"listChanged": true}, "resources": {"listChanged": true, "subscribe": true}, "prompts": {"listChanged": true} }, "instructions": "Каталог мебели: поиск товаров и остатков.", "cacheScope": "private", "ttlMs": 0, "_meta": {"io.modelcontextprotocol/serverInfo": {"name": "Каталог", "version": ""}} } } ``` И ответ на вызов инструмента `find_products` с запросом «полка»: _Ответ на tools/call_ ```json { "jsonrpc": "2.0", "id": 2, "result": { "resultType": "complete", "isError": false, "content": [{"type": "text", "text": "{\n \"sku\": \"B-310\", …}"}], "structuredContent": { "result": [{"sku": "B-310", "name": "Полка настенная", "price": 2300, "stock": 17}] }, "_meta": {"io.modelcontextprotocol/serverInfo": {"name": "Каталог", "version": ""}} } } ``` Обязательные поля `resultType`, `ttlMs` и `cacheScope`, заголовки `Mcp-Method` и `Mcp-Name` SDK заполняет и проверяет сам. Разбор полей — в разделах [«Протокол»](https://mcpdocs.ru/protocol/) и [«Транспорты»](https://mcpdocs.ru/protocol/transports/). ## Подключение к клиенту _Claude Desktop и Claude Code_ ```bash uv run mcp install catalog_server.py # Claude Desktop claude mcp add catalog -- uv run --with "mcp[cli]" mcp run /абсолютный/путь/catalog_server.py ``` Для Cursor, VS Code и OpenCode — в разделе [«Подключение»](https://mcpdocs.ru/podklyuchenie/). ## Как проектировать инструменты - **Вокруг задач, а не методов API.** «Найти товар» и «проверить статус заказа» лучше десятка обёрток над каждым адресом API. - **Описание — для модели.** Одно-два предложения: что делает, когда вызывать, что значат поля результата. - **Ограничения в коде.** Лимит строк, только чтение, проверка прав — на сервере, а не в надежде на модель. - **Ошибки — понятным текстом.** `raise ToolError("Заказ 10452 не найден")` модель прочитает и исправит запрос; любое другое исключение она увидит как «вызов не удался». - **Стабильный порядок списка.** Спецификация требует отдавать инструменты в стабильном порядке: клиенты кэшируют список. ## Старые клиенты Многие клиенты на дату проверки ещё работают по ревизии 2025-11-25 и открывают сессии. SDK второй версии обслуживает их тем же кодом. Отдельно о совместимости — в разделе [«Версии и совместимость»](https://mcpdocs.ru/protocol/versions/). ## Перед публикацией 1. Сервер отвечает на `server/discover` и выдаёт инструменты в стабильном порядке. 2. По HTTP — только HTTPS и [авторизация](https://mcpdocs.ru/svoy-server/avtorizatsiya/), если данные закрытые. 3. Журнал пишется в stderr, а не в stdout. 4. Удалённый сервер прошёл [бесплатную проверку](https://mcpprotocol.ru/mcp-check/) по ревизии 2026-07-28. Тот же сервер на TypeScript — в руководстве [«Свой сервер на TypeScript»](https://mcpdocs.ru/svoy-server/typescript/). > Готовые серверы — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/) справочника. Свой удалённый сервер можно проверить на соответствие ревизии 2026-07-28 [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/). --- # Свой MCP-сервер на TypeScript Тот же сервер каталога на TypeScript SDK v2: stdio и Streamable HTTP > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/svoy-server/typescript/). Тип: Руководство. Код проверен: Node.js 22, @modelcontextprotocol/server 2.3.1, @modelcontextprotocol/client 2.3.1 — по stdio и по HTTP. Ревизия спецификации 2026-07-28, сверено 13.10.2026. TypeScript SDK второй версии разделён на пакеты: `@modelcontextprotocol/server` для серверов и `@modelcontextprotocol/client` для клиентов. Прежний пакет `@modelcontextprotocol/sdk` — это первая версия, её поддерживают в отдельной ветке. _TypeScript SDK v2: фабрика createServer регистрирует возможности; serveStdio обслуживает локальный запуск, createMcpHandler — HTTP._ ## Проект Нужен Node.js 20 или новее. SDK поставляется только как ES-модули. _Создание проекта_ ```bash mkdir catalog && cd catalog npm init -y npm pkg set type=module npm install @modelcontextprotocol/server @modelcontextprotocol/node zod tsx mkdir src ``` `tsx` запускает TypeScript без сборки. Схемы параметров пишутся на Zod 4 (`zod/v4`); подходят и другие библиотеки со стандартом Standard Schema. ## Код сервера _src/server.ts_ ```typescript // MCP-сервер «Каталог» на TypeScript SDK v2: инструмент, ресурс, шаблон запроса import { createServer as createHttpServer } from 'node:http'; import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; import { serveStdio } from '@modelcontextprotocol/server/stdio'; import { localhostHostValidation, localhostOriginValidation, toNodeHandler } from '@modelcontextprotocol/node'; import * as z from 'zod/v4'; const PRODUCTS = [ { sku: 'A-100', name: 'Стол обеденный', price: 18900, stock: 4 }, { sku: 'A-200', name: 'Стул мягкий', price: 5400, stock: 0 }, { sku: 'B-310', name: 'Полка настенная', price: 2300, stock: 17 } ]; function createServer(): McpServer { const server = new McpServer({ name: 'catalog', version: '1.0.0' }); server.registerTool( 'find_products', { description: 'Найти товары по части названия. price — цена в рублях, stock — остаток.', inputSchema: z.object({ query: z.string().min(1), in_stock_only: z.boolean().default(false) }) }, async ({ query, in_stock_only }) => { const q = query.toLowerCase(); const found = PRODUCTS.filter(p => p.name.toLowerCase().includes(q) && (p.stock > 0 || !in_stock_only)); return { content: [{ type: 'text', text: JSON.stringify(found) }], structuredContent: { result: found } }; } ); server.registerResource('categories', 'catalog://categories', { title: 'Разделы каталога', mimeType: 'text/plain' }, async uri => ({ contents: [{ uri: uri.href, text: 'Столы\nСтулья\nПолки' }] }) ); server.registerPrompt( 'compare', { description: 'Сравнить два товара по артикулу', argsSchema: z.object({ first_sku: z.string(), second_sku: z.string() }) }, ({ first_sku, second_sku }) => ({ messages: [{ role: 'user', content: { type: 'text', text: `Сравни товары ${first_sku} и ${second_sku}: цена, наличие, назначение.` } }] }) ); return server; } if (process.argv.includes('--http')) { // Удалённый режим: Streamable HTTP на http://127.0.0.1:3000/mcp const handler = toNodeHandler(createMcpHandler(createServer)); const validateHost = localhostHostValidation(); const validateOrigin = localhostOriginValidation(); createHttpServer((req, res) => { if (!validateHost(req, res) || !validateOrigin(req, res)) return; void handler(req, res); }).listen(3000, '127.0.0.1'); console.error('catalog: http://127.0.0.1:3000/mcp'); } else { // Локальный режим: stdio. В stdout писать нельзя — только в stderr void serveStdio(createServer); } ``` - `createServer` — фабрика: по HTTP она вызывается на каждый запрос, поэтому сервер ничего не хранит между запросами. Пулы соединений и кэши создавайте вне фабрики. - `registerTool` принимает имя, описание со схемой Zod и обработчик. SDK проверит аргументы до вызова обработчика и вернёт модели понятную ошибку. - Для HTTP перед обработчиком стоят проверки `Host` и `Origin`: на локальном адресе они защищают от DNS rebinding — когда вредная страница в браузере обращается к вашему серверу на `127.0.0.1`. > По stdio стандартный вывод — канал протокола. Один `console.log` ломает обмен: пишите журнал через `console.error`. ## Запуск и проверка _Запуск_ ```bash npx tsx src/server.ts # stdio npx tsx src/server.ts --http # http://127.0.0.1:3000/mcp npx @modelcontextprotocol/inspector npx tsx src/server.ts ``` Клиент для проверки ставится отдельным пакетом `@modelcontextprotocol/client`: _src/client.ts_ ```typescript // Клиент: запускает сервер как дочерний процесс и вызывает инструмент import { Client } from '@modelcontextprotocol/client'; import { StdioClientTransport } from '@modelcontextprotocol/client/stdio'; const client = new Client({ name: 'catalog-check', version: '1.0.0' }); await client.connect(new StdioClientTransport({ command: 'npx', args: ['tsx', 'src/server.ts'] })); const { tools } = await client.listTools(); console.log(tools.map(t => t.name)); const result = await client.callTool({ name: 'find_products', arguments: { query: 'стол' } }); console.log(result.structuredContent); await client.close(); ``` _Вывод_ ```text [ 'find_products' ] { result: [ { sku: 'A-100', name: 'Стол обеденный', price: 18900, stock: 4 } ] } ``` ## Подключение к клиенту Команда запуска для клиентов — `npx tsx /абсолютный/путь/src/server.ts`; для рабочего варианта соберите проект в JavaScript и запускайте `node dist/server.js`. Форматы настроек клиентов — в разделе [«Подключение»](https://mcpdocs.ru/podklyuchenie/). Авторизация по HTTP в TypeScript SDK передаётся в фабрику через `authInfo`: токен проверяет промежуточный обработчик до SDK. Подход и требования одинаковы для обоих языков — в руководстве [«Авторизация»](https://mcpdocs.ru/svoy-server/avtorizatsiya/). > Готовые серверы — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/) справочника. Свой удалённый сервер можно проверить на соответствие ревизии 2026-07-28 [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/). --- # Авторизация MCP-сервера: OAuth 2.1 Как закрыть удалённый сервер токенами и разграничить права инструментов > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/svoy-server/avtorizatsiya/). Тип: Руководство. Код проверен: Python 3.13, пакет mcp 2.3.0 — против имитации сервера авторизации. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Авторизация нужна удалённому серверу с закрытыми данными. В терминах OAuth ваш MCP-сервер — сервер ресурсов: он никого не впускает сам и токенов не выдаёт, а только проверяет токен в каждом запросе. Входом и выдачей токенов занимается сервер авторизации — Keycloak, Auth0, Entra ID или собственный. _Три участника: клиент получает токен у сервера авторизации и передаёт его MCP-серверу, а тот проверяет токен при каждом запросе._ > По stdio авторизации нет: у канала нет заголовков. Граница безопасности локального сервера — права процесса, который его запустил. ## Как клиент находит, где взять токен 1. Клиент обращается к серверу без токена и получает `401` с заголовком `WWW-Authenticate`, где указан адрес метаданных. 2. По этому адресу лежат метаданные защищённого ресурса (RFC 9728): какой сервер авторизации выдаёт токены и какие нужны права. 3. Клиент проводит пользователя через вход у сервера авторизации и получает токен для этого ресурса. 4. Повторяет запрос с заголовком `Authorization: Bearer <токен>`. SDK делает шаги 1 и 2 за вас. Требования спецификации к клиентам и серверам авторизации — в справочнике: [«Авторизация в MCP»](https://mcpprotocol.ru/authorization/). ## Код сервера Токен проверяется у сервера авторизации через интроспекцию (RFC 7662): MCP-сервер отправляет токен и получает ответ, активен ли он, кому и с какими правами выдан. _auth_server.py_ ```python """MCP-сервер, закрытый OAuth 2.1: проверка токена через интроспекцию (RFC 7662).""" import os import httpx2 from pydantic import AnyHttpUrl from mcp.server import MCPServer from mcp.server.auth.middleware.auth_context import get_access_token from mcp.server.auth.provider import AccessToken, TokenVerifier from mcp.server.auth.settings import AuthSettings from mcp.server.mcpserver.exceptions import ToolError # Публичный адрес этого MCP-сервера: ровно тот, к которому подключаются клиенты RESOURCE = os.environ.get("MCP_RESOURCE", "http://127.0.0.1:8000/mcp") ISSUER = os.environ.get("OAUTH_ISSUER", "http://127.0.0.1:9000") INTROSPECT_URL = f"{ISSUER}/introspect" # Учётные данные, с которыми MCP-сервер обращается к серверу авторизации CLIENT_ID = os.environ.get("INTROSPECT_CLIENT_ID", "mcp-server") CLIENT_SECRET = os.environ.get("INTROSPECT_CLIENT_SECRET", "change-me") class IntrospectionVerifier(TokenVerifier): async def verify_token(self, token: str) -> AccessToken | None: async with httpx2.AsyncClient(timeout=10) as http: r = await http.post(INTROSPECT_URL, data={"token": token}, auth=(CLIENT_ID, CLIENT_SECRET)) if r.status_code != 200: return None info = r.json() if not info.get("active"): return None aud = info.get("aud") if isinstance(aud, list): # токен выпущен для нескольких ресурсов aud = RESOURCE if RESOURCE in aud else None return AccessToken( token=token, client_id=info.get("client_id", ""), scopes=info.get("scope", "").split(), expires_at=info.get("exp"), resource=aud, subject=info.get("sub"), ) mcp = MCPServer( "Заметки", version="1.0.0", token_verifier=IntrospectionVerifier(), auth=AuthSettings( issuer_url=AnyHttpUrl(ISSUER), resource_server_url=AnyHttpUrl(RESOURCE), required_scopes=["notes:read"], validate_token_resource=True, # отклонять токены, выпущенные для другого сервера ), ) @mcp.tool() def whoami() -> str: """Кто вызывает сервер: пользователь и разрешения токена.""" token = get_access_token() if token is None: return "аноним" return f"{token.subject} (клиент {token.client_id}, права: {' '.join(token.scopes)})" @mcp.tool() def delete_note(note_id: int) -> str: """Удалить заметку. Нужно право notes:write.""" token = get_access_token() if token is None or "notes:write" not in token.scopes: raise ToolError("Недостаточно прав: нужно право notes:write") return f"Заметка {note_id} удалена" if __name__ == "__main__": mcp.run(transport="streamable-http", host="127.0.0.1", port=8000) ``` - `TokenVerifier` — единственное, что нужно реализовать: метод получает токен из заголовка и возвращает `AccessToken` или `None`. - `token_verifier` и `auth` передаются вместе; иначе конструктор откажется работать. - `validate_token_resource=True` отклоняет токен, выпущенный для другого сервера, — так ваш сервер не примет токен, украденный у соседнего. - `get_access_token()` внутри инструмента возвращает того, кто вызывает: по нему проверяются права отдельных инструментов. ## Что видит клиент Ответы сервера из нашей проверки. Запрос без токена: _Ответ без токена_ ```http HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer error="invalid_token", error_description="Authentication required", resource_metadata="http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp" ``` Метаданные по адресу из заголовка: _GET /.well-known/oauth-protected-resource/mcp_ ```json {"resource": "http://127.0.0.1:8000/mcp", "authorization_servers": ["http://127.0.0.1:9000/"], "scopes_supported": ["notes:read"], "bearer_methods_supported": ["header"]} ``` Токен, выпущенный для другого сервера, и неизвестный токен получают тот же `401`. С токеном, где есть только право `notes:read`: _Результаты вызовов_ ```text whoami → ivanov (клиент claude, права: notes:read) delete_note → ошибка: Недостаточно прав: нужно право notes:write ``` ## Перед запуском в работу - **Только HTTPS.** `RESOURCE` — точный публичный адрес, с которым работают клиенты. - **Секрет интроспекции** храните в переменных окружения или хранилище секретов, не в коде. - **Минимальные права.** Отдельные права (`scope`) на чтение и на изменение; инструменты, которые меняют данные, проверяют право в коде. - **Короткоживущие токены.** Отзыв доступа у сервера авторизации должен действовать быстро. - **Регистрация клиентов.** Спецификация 2026-07-28 считает устаревшей динамическую регистрацию (DCR) и предлагает документы метаданных клиента (CIMD); проверьте, что ваш сервер авторизации их поддерживает. > SDK не содержит страницы входа и не выдаёт токены — это задача сервера авторизации. Параметр `auth_server_provider`, встраивающий сервер авторизации внутрь MCP-сервера, документация SDK для новых серверов не рекомендует. > Готовые серверы — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/) справочника. Свой удалённый сервер можно проверить на соответствие ревизии 2026-07-28 [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/). --- # Память и состояние в MCP-сервере Данные между вызовами без сессий и свой сервер памяти на SQLite > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/svoy-server/pamyat/). Тип: Руководство. Код проверен: Python 3.13, пакет mcp 2.3.0 — по stdio, с перезапуском процесса. Ревизия спецификации 2026-07-28, сверено 13.10.2026. С ревизии 2026-07-28 в MCP нет сессий: любой запрос может прийти на любой экземпляр сервера. Значит, всё, что должно жить между вызовами, сервер хранит сам и выдаёт клиенту явный идентификатор. Здесь — два частых случая: черновик, который собирается за несколько вызовов, и долговременная память ассистента. _Без сессий состояние живёт в хранилище сервера под явным идентификатором, а клиент передаёт этот идентификатор в каждом вызове._ ## Почему не держать состояние в памяти процесса - Удалённый сервер обычно работает в нескольких экземплярах за балансировщиком; следующий вызов может попасть на другой. - Заголовка `Mcp-Session-Id` больше нет, и привязать клиента к экземпляру нечем. - После перезапуска процесса всё, что было в переменных, теряется. ## Явный идентификатор вместо сессии Первый вызов создаёт объект и возвращает его идентификатор; модель передаёт его в следующих вызовах. Владелец проверяется при каждом обращении: идентификатор — не пароль. _order_server.py_ ```python """Состояние без сессии: черновик заказа живёт под явным идентификатором.""" import secrets from pydantic import BaseModel from mcp.server import MCPServer from mcp.server.auth.middleware.auth_context import get_access_token from mcp.server.mcpserver.exceptions import ToolError mcp = MCPServer("Заказы", version="1.0.0") class Order(BaseModel): order_id: str items: dict[str, int] # артикул -> количество # В примере — словарь в памяти. В работе — база или Redis: запросы # одного клиента могут приходить на разные экземпляры сервера. DRAFTS: dict[str, dict] = {} def caller() -> str: token = get_access_token() return (token.subject or token.client_id) if token else "local" def draft_of(order_id: str) -> dict: draft = DRAFTS.get(order_id) # Проверяем владельца при каждом вызове: идентификатор — не пароль if draft is None or draft["owner"] != caller(): raise ToolError(f"Черновика {order_id} нет или он не ваш") return draft @mcp.tool() def start_order() -> Order: """Создать черновик заказа. Верните order_id в следующих вызовах.""" order_id = "ord_" + secrets.token_urlsafe(9) DRAFTS[order_id] = {"owner": caller(), "items": {}} return Order(order_id=order_id, items={}) @mcp.tool() def add_item(order_id: str, sku: str, qty: int = 1) -> Order: """Добавить товар в черновик заказа.""" if qty < 1: raise ToolError("Количество должно быть больше нуля") items = draft_of(order_id)["items"] items[sku] = items.get(sku, 0) + qty return Order(order_id=order_id, items=items) @mcp.tool() def show_order(order_id: str) -> Order: """Показать черновик заказа.""" return Order(order_id=order_id, items=draft_of(order_id)["items"]) if __name__ == "__main__": mcp.run() ``` _Проверка_ ```text start_order() → {"order_id": "ord_c20o5oyms6qC", "items": {}} add_item(order_id, "A-100", qty=2) → {"items": {"A-100": 2}} add_item(order_id, "A-100") → {"items": {"A-100": 3}} show_order("ord_fake") → ошибка: Черновика ord_fake нет или он не ваш ``` В примере черновики хранятся в словаре — для показа. В работе берите базу или Redis с временем жизни записей. ## Свой сервер памяти «Память» для ассистента — это сервер с инструментами «запомнить», «вспомнить», «забыть», который хранит записи на диске. Заметки каждого пользователя отделены: по HTTP владелец берётся из токена, по stdio это один локальный пользователь. _memory_server.py_ ```python """MCP-сервер «Память»: заметки, которые переживают перезапуск клиента и сервера.""" import sqlite3 from collections.abc import AsyncIterator from contextlib import asynccontextmanager from mcp.server import MCPServer from mcp.server.auth.middleware.auth_context import get_access_token from mcp.server.mcpserver import Context from mcp.server.mcpserver.exceptions import ToolError DB_PATH = "memory.sqlite3" @asynccontextmanager async def lifespan(server: MCPServer) -> AsyncIterator[sqlite3.Connection]: db = sqlite3.connect(DB_PATH, check_same_thread=False) db.execute("""CREATE TABLE IF NOT EXISTS notes ( id INTEGER PRIMARY KEY, owner TEXT NOT NULL, text TEXT NOT NULL, tags TEXT NOT NULL DEFAULT '', created TEXT DEFAULT CURRENT_TIMESTAMP)""") try: yield db finally: db.close() mcp = MCPServer("Память", version="1.0.0", lifespan=lifespan) def owner() -> str: """Чьи это заметки: субъект токена по HTTP, «local» по stdio.""" token = get_access_token() return (token.subject or token.client_id) if token else "local" @mcp.tool() def remember(ctx: Context, text: str, tags: list[str] | None = None) -> dict[str, int]: """Запомнить факт. tags — метки для поиска, например ["клиент", "договор"].""" db = ctx.request_context.lifespan_context cur = db.execute("INSERT INTO notes(owner, text, tags) VALUES (?, ?, ?)", (owner(), text, ",".join(tags or []))) db.commit() return {"id": cur.lastrowid} @mcp.tool() def recall(ctx: Context, query: str = "", limit: int = 10) -> list[dict]: """Найти заметки по слову в тексте или метке. Пустой запрос — последние заметки.""" db = ctx.request_context.lifespan_context rows = db.execute( "SELECT id, text, tags, created FROM notes WHERE owner = ? " "AND (text LIKE ? OR tags LIKE ?) ORDER BY id DESC LIMIT ?", (owner(), f"%{query}%", f"%{query}%", min(limit, 50)), ).fetchall() return [{"id": r[0], "text": r[1], "tags": r[2].split(",") if r[2] else [], "created": r[3]} for r in rows] @mcp.tool() def forget(ctx: Context, note_id: int) -> str: """Удалить заметку по id.""" db = ctx.request_context.lifespan_context cur = db.execute("DELETE FROM notes WHERE id = ? AND owner = ?", (note_id, owner())) db.commit() if cur.rowcount == 0: raise ToolError(f"Заметки {note_id} нет") return "Удалено" if __name__ == "__main__": mcp.run() ``` - Соединение с базой открывается один раз в `lifespan` и доступно инструментам через `ctx.request_context.lifespan_context`. В SDK второй версии `lifespan` для HTTP выполняется один раз при запуске, а не на каждое соединение. - `ctx: Context` в параметрах SDK подставляет сам; в схему инструмента он не попадает. - Запросы к базе только с параметрами (`?`), лимит записей ограничен в коде. Проверка: две заметки записаны одним процессом сервера, найдены после его перезапуска. _Проверка_ ```text remember("Договор с ООО Ромашка до 31.12", tags=["договор"]) → {"id": 1} remember("Позвонить Иванову в пятницу") → {"id": 2} # новый процесс сервера recall("договор") → [{"id": 1, "text": "Договор с ООО Ромашка до 31.12", "tags": ["договор"], …}] forget(99) → ошибка: Заметки 99 нет ``` Готовый эталонный сервер памяти на графе знаний — [Memory](https://mcpprotocol.ru/katalog/memory/) в каталоге справочника. ## Многошаговые запросы и несколько экземпляров Если инструменту не хватает данных, сервер может вернуть результат `input_required` и попросить клиента повторить запрос с ответом пользователя. Промежуточное состояние такого запроса SDK запечатывает в поле `requestState` и отдаёт клиенту. Ключ для запечатывания по умолчанию создаётся в каждом процессе, поэтому сервер в нескольких экземплярах должен получить общий ключ: `MCPServer(..., request_state_security=RequestStateSecurity(keys=[...]))`, где класс импортируется из `mcp.server.request_state`. Механизм — в разделе [«Шаблоны обмена»](https://mcpdocs.ru/protocol/patterns/). ## Безопасность данных - Не храните в памяти ассистента пароли, номера карт и паспортные данные: всё записанное модель потом может прочитать и пересказать. - Дайте пользователю способ удалить свои записи — инструмент `forget` и удаление по запросу. - Для удалённого сервера отделяйте данные пользователей по субъекту токена, а не по значению, которое прислал клиент. > Готовые серверы — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/) справочника. Свой удалённый сервер можно проверить на соответствие ревизии 2026-07-28 [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/). --- # MCP и 1С Как подключить ИИ-ассистента к конфигурации, справке платформы и данным базы 1С > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/1c/). Тип: Руководство. Пример сервера проверен: Python 3.13, пакет mcp 2.3.0; сведения о проектах — по репозиториям на 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Модель ничего не знает о вашей конфигурации: путает объекты, выдумывает реквизиты и методы платформы. MCP-сервер даёт ей точный контекст — метаданные, код модулей, справку платформы или данные базы. Раздел написан для программистов 1С. _Три задачи MCP в 1С: работа с проектом в 1С:EDT, справка по платформе, данные базы — у каждой свой тип сервера._ ## С чего начать **Какая задача — какой сервер** | Задача | Что подключить | Где читать | |---|---|---| | Писать и править код в 1С:EDT с ИИ-ассистентом | EDT MCP Server — дополнение к EDT | [MCP в 1С:EDT](https://mcpdocs.ru/1c/edt/) | | Генерировать код с учётом метаданных базы | mcp-1c и подобные серверы метаданных | [Примеры и разборы](https://mcpdocs.ru/1c/primery/) | | Справка по синтаксису и объектам платформы | mcp-bsl-platform-context | [Примеры и разборы](https://mcpdocs.ru/1c/primery/) | | Дать ассистенту читать данные базы: номенклатуру, контрагентов | Свой MCP-сервер поверх OData или HTTP-сервиса | [MCP-сервер для базы 1С](https://mcpdocs.ru/1c/napisat-server/) | Что MCP даёт и где его пределы — на странице [«Что даёт MCP программисту 1С»](https://mcpdocs.ru/1c/chto-dayot/). Карточки серверов для 1С с датой проверки — в [подборке каталога](https://mcpprotocol.ru/katalog/programmy/1c/). ## Как это устроено MCP-сервер — отдельная программа, к которой подключается ИИ-клиент: Claude, Cursor, VS Code с Copilot, OpenCode или клиент с локальной моделью. Сервер для 1С обращается к EDT, к установленной платформе или к опубликованной базе и отдаёт модели результат. Основы протокола — во [введении](https://mcpdocs.ru/intro/), о подключении клиентов — в разделе [«Подключение»](https://mcpdocs.ru/podklyuchenie/). > Модель можно запускать и локально (Ollama, LM Studio): тогда код и данные не покидают вашу сеть. Часть серверов для 1С прямо рассчитана на такой режим. ## Безопасность данных базы > MCP-сервер даёт модели доступ к данным от имени своего пользователя 1С. Всё, что этот пользователь может прочитать, может оказаться в контексте модели, а значит — у поставщика модели. - **Отдельный пользователь 1С** только для MCP-сервера, с правами на чтение нужных объектов. Не используйте учётную запись администратора или сотрудника. - **Только нужные объекты и поля.** Белый список справочников и реквизитов в коде сервера; персональные данные (паспорта, телефоны, зарплаты) не отдавайте без правового основания. - **Никакого произвольного запроса от модели.** Фильтры собирает сервер, строковые значения экранируются, идентификаторы проверяются по формату. - **Лимит строк** в каждом запросе. - **Только чтение.** Запись в базу — отдельный сервер, отдельные права и подтверждение человека. - **HTTPS** между MCP-сервером и публикацией базы, если они на разных машинах. - **Журнал вызовов**: кто, когда и что запрашивал. - **Сначала копия базы.** Проверяйте сервер на копии, а не на рабочей базе. > Готовые серверы для 1С с датой проверки — в [подборке каталога](https://mcpprotocol.ru/katalog/programmy/1c/) справочника, все серверы — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/). Свой удалённый сервер можно проверить на соответствие ревизии 2026-07-28 [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/). --- # Что даёт MCP программисту 1С Возможности, ограничения и где ИИ-ассистент действительно экономит время > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/1c/chto-dayot/). Тип: Руководство. Сведения о проектах — по репозиториям на 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Без MCP модель пишет код 1С «по памяти»: по типовым конфигурациям, которые видела в обучении, и по общим представлениям о языке. MCP меняет это: модель спрашивает сервер и получает факты о вашей конфигурации. _Без MCP модель угадывает имена объектов и методов; с MCP она запрашивает их у сервера и пишет код по фактической конфигурации._ ## Что получает программист **Возможности по типам серверов** | Возможность | Чем даётся | Пример запроса к ассистенту | |---|---|---| | Точные имена объектов, реквизитов, табличных частей | Сервер метаданных или EDT MCP Server | «Напиши запрос остатков по складу с отбором по номенклатуре» | | Чтение и поиск по модулям | EDT MCP Server | «Где вызывается процедура ЗаполнитьПоОснованию?» | | Ошибки и предупреждения проверки проекта | EDT MCP Server | «Разбери ошибки после последних правок и исправь» | | Проверка текста запроса до вставки в код | EDT MCP Server (validate_query) | «Проверь этот запрос на ошибки» | | Справка по синтаксису и объектам платформы | Сервер справки платформы | «Какие параметры у метода ЗаписьXML.ЗаписатьНачалоЭлемента?» | | Данные базы: номенклатура, контрагенты | Свой сервер для базы | «Найди контрагента по ИНН и покажи его договоры» | ## Ограничения - **Логику MCP не проверяет.** Код с правильными именами может делать не то. Ревью и тесты остаются за программистом; некоторые серверы умеют запускать тесты YAxUnit, но писать их всё равно нужно. - **Конфигуратор не поддерживается напрямую.** Самые развитые инструменты работают с проектами 1С:EDT; для конфигуратора есть серверы, которые читают выгрузку конфигурации в файлы или метаданные базы. - **Типовые конфигурации большие.** Модель не удержит всю конфигурацию в контексте: сервер должен отдавать нужное точечно, а не всё сразу. - **Изменение базы — риск.** Серверы, которые умеют обновлять конфигурацию базы или выполнять код в отладке, требуют подтверждения каждой опасной операции. Не отключайте его на рабочих базах. - **Данные уходят модели.** Всё, что сервер вернул, попадает в контекст и уходит поставщику модели, если она облачная. Для данных с персональными сведениями выбирайте локальную модель или не открывайте такие данные вовсе. ## Как начать без риска 1. Начните со справки платформы и метаданных — они не трогают данные. 2. Подключите EDT MCP Server к копии проекта и оставьте режим подтверждения опасных операций по умолчанию. 3. К данным базы переходите последними: отдельный пользователь с правом только на чтение и белый список объектов — [как это сделать](https://mcpdocs.ru/1c/napisat-server/). > Готовые серверы для 1С с датой проверки — в [подборке каталога](https://mcpprotocol.ru/katalog/programmy/1c/) справочника, все серверы — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/). Свой удалённый сервер можно проверить на соответствие ревизии 2026-07-28 [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/). --- # MCP в 1С:EDT: EDT MCP Server Установка, подключение клиентов, группы инструментов и защита от опасных операций > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/1c/edt/). Тип: Руководство. Сверено с README репозитория DitriXNew/EDT-MCP (изменён 07.10.2026). Ревизия спецификации 2026-07-28, сверено 13.10.2026. EDT MCP Server — открытое дополнение к 1C:EDT от разработчика DitriXNew. Оно запускает MCP-сервер внутри EDT, и ИИ-ассистент видит проект: метаданные, модули BSL, ошибки проверки, формы, может проверять запросы, запускать отладку и тесты. Это проект сообщества, а не фирмы «1С». _EDT MCP Server работает внутри 1C:EDT и слушает http://localhost:8765/mcp; клиенты подключаются напрямую или через мост mcp-remote._ ## Требования - 1C:EDT 2026.1 или 2026.2 (одна сборка для обеих версий), Java 17. - MCP-клиент: Cursor, Claude Code, Claude Desktop, VS Code с Copilot и другие. - Протокол сервера на дату проверки — ревизия 2025-11-25 с транспортом Streamable HTTP: её поддерживают все распространённые клиенты. ## Установка 1. В EDT: **Help → Install New Software…** 2. Добавьте сайт обновлений: `https://ditrixnew.github.io/EDT-MCP/` 3. Выберите **EDT MCP Server Feature** и перезапустите EDT. Настройки — **Window → Preferences → MCP Server**. Вкладка General: порт (по умолчанию 8765), автозапуск, режим простого текста для Cursor, кнопки копирования адреса и готовой конфигурации. Вкладка Tools: какие группы инструментов открыть клиентам. ## Подключение клиентов _Cursor — .cursor/mcp.json_ ```json { "mcpServers": { "EDT MCP Server": { "url": "http://localhost:8765/mcp" } } } ``` _Claude Code — раздел mcpServers в .claude.json_ ```json "mcpServers": { "EDT MCP Server": { "type": "http", "url": "http://localhost:8765/mcp" } } ``` _Claude Desktop — через мост mcp-remote_ ```json { "mcpServers": { "EDT MCP Server": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:8765/mcp"] } } } ``` Для VS Code автор приводит файл `.vscode/mcp.json` с ключом `servers` и адресом `http://localhost:8765/mcp`. Cursor не показывает модели встроенные ресурсы, поэтому для него включите в настройках **Plain text mode (Cursor compatibility)**. ## Что умеет **Группы инструментов (всего 97 на дату проверки)** | Группа | Примеры | |---|---| | Core | список проектов и модулей, чтение исходного кода, поиск по коду, список метаданных | | Metadata | создание, изменение, переименование и удаление объектов метаданных с каскадными правками | | Code | чтение и запись методов, поиск ссылок, переход к определению, иерархия вызовов, проверка текста запроса | | Debug | запуск отладки, точки останова, шаги, вычисление выражений | | Testing, Profiling | запуск тестов YAxUnit, замеры производительности | | Forms | снимки форм и описание их структуры | | Project, Git, Comparison | обновление базы, работа с Git, сравнение конфигураций | Чтобы не перегружать модель, инструменты можно включать группами и пресетами («только анализ», «ревью кода», «разработка»). ## Безопасность - **Только локальный доступ.** Сервер слушает `127.0.0.1`. Доступ из сети включается отдельно и требует токена; без токена такой сервер не работает. - **Подтверждение опасных операций.** По умолчанию EDT спрашивает человека перед удалением и переименованием метаданных, обновлением базы, завершением сеансов, выполнением кода в отладке и записью в Git. Диалог ждёт 120 секунд, затем операция отклоняется. - **Обход только для автоматизации.** Переменная `EDT_MCP_DESTRUCTIVE_CONSENT=allow` отключает подтверждение для запуска без интерфейса; каждое такое действие пишется в журнал. На рабочих базах её не используйте. - **Ответы инструментов — данные.** Код модулей и синонимы метаданных могут содержать текст, который выглядит как команда для модели. Модель не должна ему подчиняться. > Лицензия AGPL-3.0: пользоваться дополнением можно свободно, но если вы измените его и дадите доступ к изменённой версии другим, в том числе по сети, исходный код изменений нужно открыть. Карточка сервера в каталоге справочника: [EDT MCP Server](https://mcpprotocol.ru/katalog/edt-mcp/). > Готовые серверы для 1С с датой проверки — в [подборке каталога](https://mcpprotocol.ru/katalog/programmy/1c/) справочника, все серверы — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/). Свой удалённый сервер можно проверить на соответствие ревизии 2026-07-28 [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/). --- # Как написать MCP-сервер для базы 1С Сервер на Python поверх стандартного интерфейса OData: только чтение, белый список, проверка входных данных > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/1c/napisat-server/). Тип: Руководство. Код проверен: Python 3.13, пакет mcp 2.3.0 — против имитации интерфейса OData 1С. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Самый короткий путь дать ассистенту данные базы — небольшой сервер на Python поверх стандартного интерфейса OData, который есть в платформе 1С:Предприятие 8.3. Сервер ничего не пишет в базу, отдаёт только разрешённые объекты и поля и сам собирает запросы — модель не может прислать свой. _MCP-сервер стоит между ИИ-клиентом и базой: принимает вызовы инструментов, сам собирает запрос OData с белым списком полей и обращается к публикации базы от отдельного пользователя._ ## Варианты архитектуры **Три способа** | Способ | Как работает | Когда выбрать | |---|---|---| | Сервер на Python поверх OData | Отдельная программа обращается к `…/odata/standard.odata` | Чтение справочников и документов без доработки конфигурации — этот способ ниже | | Расширение с HTTP-сервисом | MCP-сервер реализован внутри базы на встроенном языке | Нужна логика на стороне 1С; готовая основа — проект [1c_mcp](https://github.com/vladimir-kharin/1c_mcp) | | Свой HTTP-сервис + MCP-прокси | Сервис отдаёт подготовленные данные, прокси переводит их в MCP | Сложные выборки, которые проще написать запросом 1С | ## Шаг 1. Публикация OData 1. Опубликуйте базу на веб-сервере и в окне публикации отметьте **«Публиковать стандартный интерфейс OData»**. 2. Включите в состав интерфейса только нужные объекты. Состав задаётся методом `УстановитьСоставСтандартногоИнтерфейсаOData()`; в типовых конфигурациях на БСП для этого обычно есть обработка настройки стандартного интерфейса OData. 3. Проверьте, что интерфейс отвечает: `http://сервер/база/odata/standard.odata/$metadata` — описание опубликованных объектов. Из него берите точные имена вида `Catalog_Номенклатура` и реквизитов. ## Шаг 2. Пользователь 1С Создайте отдельного пользователя, например `mcp_reader`, с правом только на чтение объектов, которые будет отдавать сервер, и правом доступа к стандартному интерфейсу OData. Пароль храните в переменных окружения сервера, а не в коде. ## Шаг 3. Код сервера _Установка_ ```bash pip install "mcp[cli]" ``` _onec_odata_server.py_ ```python """MCP-сервер для базы 1С через стандартный интерфейс OData. Только чтение.""" import os import re from typing import Any from urllib.parse import quote import httpx2 from mcp.server import MCPServer from mcp.server.mcpserver.exceptions import ToolError # Адрес публикации, например http://srv/trade/odata/standard.odata ODATA_URL = os.environ["ONEC_ODATA_URL"].rstrip("/") # Отдельный пользователь 1С с правом только на чтение нужных объектов AUTH = (os.environ["ONEC_USER"], os.environ["ONEC_PASSWORD"]) # Белый список: какие объекты читать и какие поля отдавать модели. # Имена зависят от конфигурации — сверьте их с $metadata своей базы. ENTITIES = { "Catalog_Номенклатура": ["Ref_Key", "Code", "Description", "Артикул"], "Catalog_Контрагенты": ["Ref_Key", "Code", "Description", "ИНН"], } MAX_ROWS = 50 GUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$") mcp = MCPServer("1С: справочники", version="1.0.0", instructions="Чтение справочников 1С. Изменять данные сервер не умеет.") async def odata_get(path: str, params: dict[str, str]) -> dict: async with httpx2.AsyncClient(auth=AUTH, timeout=20) as http: r = await http.get(ODATA_URL + path, params={"$format": "json", **params}) if r.status_code == 401: raise ToolError("1С отклонила логин или пароль сервера MCP") if r.status_code == 404: raise ToolError("Объект не найден или не включён в состав OData") if r.status_code >= 400: raise ToolError(f"1С вернула ошибку HTTP {r.status_code}") return r.json() def check_entity(entity: str) -> list[str]: if entity not in ENTITIES: raise ToolError(f"Нет доступа к {entity}. Доступны: {', '.join(ENTITIES)}") return ENTITIES[entity] @mcp.tool() def list_sources() -> dict[str, list[str]]: """Какие справочники 1С можно читать и какие поля в них есть.""" return ENTITIES @mcp.tool() async def search(entity: str, text: str, limit: int = 10) -> list[dict[str, Any]]: """Найти элементы справочника по части наименования (без помеченных на удаление).""" fields = check_entity(entity) text = text.replace("'", "''") # экранирование кавычки в строке OData data = await odata_get(f"/{quote(entity)}", { "$filter": f"substringof('{text}', Description) and DeletionMark eq false", "$select": ",".join(fields), "$top": str(max(1, min(limit, MAX_ROWS))), }) return data.get("value", []) @mcp.tool() async def get_item(entity: str, ref_key: str) -> dict[str, Any]: """Получить элемент справочника по Ref_Key (GUID из результата search).""" fields = check_entity(entity) if not GUID.match(ref_key): raise ToolError("ref_key должен быть GUID вида 00000000-0000-0000-0000-000000000000") data = await odata_get(f"/{quote(entity)}(guid'{ref_key}')", {"$select": ",".join(fields)}) return {k: data.get(k) for k in fields} if __name__ == "__main__": mcp.run() ``` - `ENTITIES` — белый список: только эти объекты и только эти поля попадут к модели. Закупочные цены, телефоны и другие лишние реквизиты отсекаются через `$select`. - Фильтр `$filter` собирает сервер. Строка от модели экранируется (кавычка удваивается), `ref_key` проверяется регулярным выражением. - `MAX_ROWS` ограничивает выборку, `DeletionMark eq false` скрывает помеченные на удаление. - Ошибки 1С превращаются в понятный модели текст через `ToolError`. > Функцию `substringof` в `$filter` поддерживает стандартный интерфейс OData платформы. Если ваша версия платформы ответит ошибкой на этот фильтр, замените его точным совпадением: `Description eq '…'`. ## Шаг 4. Подключение к клиенту _Claude Desktop или Cursor_ ```json { "mcpServers": { "1c-catalogs": { "command": "python", "args": ["/абсолютный/путь/onec_odata_server.py"], "env": { "ONEC_ODATA_URL": "http://srv/trade/odata/standard.odata", "ONEC_USER": "mcp_reader", "ONEC_PASSWORD": "пароль" } } } } ``` ## Что получилось Результаты вызовов из нашей проверки: _Вызовы инструментов_ ```text list_sources() → {"Catalog_Номенклатура": [...], "Catalog_Контрагенты": [...]} search("Catalog_Номенклатура", "стол") → [{"Ref_Key": "0b8e2a4c-…-000000000001", "Code": "00-001", "Description": "Стол обеденный", "Артикул": "A-100"}] search("Catalog_Номенклатура", "O'Neil") → [{"Description": "Стул O'Neil", …}] (кавычка экранирована) get_item("Catalog_Номенклатура", "") → {"Ref_Key": …, "Code": "00-001", "Description": "Стол обеденный", "Артикул": "A-100"} search("Document_Заказ", "x") → ошибка: Нет доступа к Document_Заказ. Доступны: … get_item("Catalog_Номенклатура", "1' or 1=1") → ошибка: ref_key должен быть GUID … неверный пароль → ошибка: 1С отклонила логин или пароль сервера MCP ``` Элемент «Стол письменный», помеченный на удаление, в выдачу не попал, а реквизит «Цена закупки» отсечён белым списком полей. ## Как расширить - **Документы за период:** `Document_ЗаказКлиента` с фильтром `Date ge datetime'2026-10-01T00:00:00'` и `$orderby=Date desc`. Дату собирайте из параметра типа `date`, а не из строки модели. - **Остатки:** виртуальные таблицы регистров накопления доступны через OData, но имена регистров и измерений зависят от конфигурации — сверяйтесь с `$metadata`. - **Удалённый режим:** запустите сервер по HTTP (`mcp.run(transport="streamable-http")`) и закройте его [авторизацией](https://mcpdocs.ru/svoy-server/avtorizatsiya/). ## Безопасность данных базы > MCP-сервер даёт модели доступ к данным от имени своего пользователя 1С. Всё, что этот пользователь может прочитать, может оказаться в контексте модели, а значит — у поставщика модели. - **Отдельный пользователь 1С** только для MCP-сервера, с правами на чтение нужных объектов. Не используйте учётную запись администратора или сотрудника. - **Только нужные объекты и поля.** Белый список справочников и реквизитов в коде сервера; персональные данные (паспорта, телефоны, зарплаты) не отдавайте без правового основания. - **Никакого произвольного запроса от модели.** Фильтры собирает сервер, строковые значения экранируются, идентификаторы проверяются по формату. - **Лимит строк** в каждом запросе. - **Только чтение.** Запись в базу — отдельный сервер, отдельные права и подтверждение человека. - **HTTPS** между MCP-сервером и публикацией базы, если они на разных машинах. - **Журнал вызовов**: кто, когда и что запрашивал. - **Сначала копия базы.** Проверяйте сервер на копии, а не на рабочей базе. > Готовые серверы для 1С с датой проверки — в [подборке каталога](https://mcpprotocol.ru/katalog/programmy/1c/) справочника, все серверы — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/). Свой удалённый сервер можно проверить на соответствие ревизии 2026-07-28 [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/). --- # MCP для 1С: примеры и разборы Открытые проекты: серверы для EDT, метаданных, справки платформы и данных базы > Страница сайта MCP Docs — руководство (https://mcpdocs.ru/1c/primery/). Тип: Руководство. Репозитории проверены 13.10.2026. Ревизия спецификации 2026-07-28, сверено 13.10.2026. Ниже — открытые проекты сообщества, которые мы проверили по репозиториям: что делает каждый, лицензия, транспорт и на что обратить внимание. В конце — где искать остальные. _Открытые проекты MCP для 1С по задачам: код в EDT, метаданные, MCP-сервер внутри базы, справка платформы._ ## Проверенные проекты **Открытые проекты (проверено 13.10.2026)** | Проект | Что делает | Транспорт | Стек | Лицензия | Изменён | |---|---|---|---|---|---| | [EDT MCP Server](https://github.com/DitriXNew/EDT-MCP) | Дополнение к 1C:EDT: метаданные, код BSL, ошибки, отладка, тесты | HTTP | Java | AGPL-3.0 | 07.10.2026 | | [mcp-1c](https://github.com/feenlace/mcp-1c) | Метаданные конфигурации для генерации кода; работа с локальными моделями | stdio | Go | MIT (открытая редакция) | 02.10.2026 | | [1c_mcp](https://github.com/vladimir-kharin/1c_mcp) | Расширение: MCP-сервер внутри базы, инструменты на встроенном языке | HTTP, stdio через прокси | BSL, Python | не указана | 05.10.2026 | | [mcp-bsl-platform-context](https://github.com/alkoleft/mcp-bsl-platform-context) | Справка по синтаксису и объектной модели платформы | stdio, SSE | Kotlin | MIT | 11.03.2026 | ## Разбор ### EDT MCP Server Самый полный набор для разработки: 97 инструментов, от чтения модулей до обновления базы и отладки. Опасные операции по умолчанию требуют подтверждения в EDT. Подробно — [MCP в 1С:EDT](https://mcpdocs.ru/1c/edt/). ### mcp-1c Локальный сервер на Go: модель видит метаданные вашей конфигурации и пишет код с правильными именами. Установщик добавляет в базу расширение (`mcp-1c --install "путь к базе"`), поэтому запускайте его на копии. У автора есть платные редакции; в разборе — открытая. ### 1c_mcp Основа для своего MCP-сервера внутри базы: протокол берёт на себя расширение, а инструменты, ресурсы и шаблоны пишутся на встроенном языке. Прямое подключение требует публикации HTTP-сервиса без аутентификации 1С — для рабочих баз используйте Python-прокси из проекта. Файла лицензии в репозитории нет: условия уточняйте у автора. ### mcp-bsl-platform-context Справка по платформе из установленной у вас версии 1С: поиск по функциям, методам, свойствам и типам. Безопасен для начала — не трогает ни код, ни данные. Сетевой режим использует устаревший транспорт HTTP+SSE, локально берите stdio. ## Свои примеры - [MCP-сервер для базы 1С на Python через OData](https://mcpdocs.ru/1c/napisat-server/) — только чтение, белый список, проверка входных данных. - [Память и состояние](https://mcpdocs.ru/svoy-server/pamyat/) — если серверу нужно помнить контекст между вызовами. ## Где искать остальные Самый полный перечень — каталог [Awesome 1C MCP Servers](https://github.com/Untru/1c-mcp): серверы для EDT и VS Code, метаданных и анализа кода, справки, тестов, UI-тестирования и данных учёта, а также обёртки над 1С:Напарником (нужна подписка ИТС). Мы не проверяли каждый проект из этого списка: перед подключением смотрите лицензию, дату последнего изменения и права, которые получает сервер. Карточки проверенных серверов — в [подборке «MCP-серверы для 1С»](https://mcpprotocol.ru/katalog/programmy/1c/) каталога справочника. > Готовые серверы для 1С с датой проверки — в [подборке каталога](https://mcpprotocol.ru/katalog/programmy/1c/) справочника, все серверы — в [каталоге MCP-серверов](https://mcpprotocol.ru/katalog/). Свой удалённый сервер можно проверить на соответствие ревизии 2026-07-28 [бесплатной проверкой](https://mcpprotocol.ru/mcp-check/).