MCP-сервер МойСклад: документация пользователя

MCP (Model Context Protocol) — открытый протокол, через который AI-приложения подключают внешние сервисы как набор инструментов. MCP-сервер МойСклад дает агенту доступ к данным аккаунта: товарам, складам, документам, контрагентам и отчетам.

MCP не заменяет JSON API 1.2. Это другой способ работы с МоимСкладом. Он удобен в чате с AI-агентом, но набор доступных операций у него меньше, а результат зависит от модели агента и формулировки задачи. Интеграции с заранее заданной логикой, операции создания и изменения данных, вебхуки, асинхронные задачи и массовую обработку данных по-прежнему нужно реализовывать через API.

Возможности сервиса MCP

Сервис MCP находится в стадии активной разработки. В связи с этим перечень доступных инструментов и их параметры могут быть изменены без предварительного уведомления. Для получения информации о текущем функционале рекомендуется обращаться к агенту в режиме реального времени.

Чтобы узнать актуальный набор возможностей MCP, после подключения задайте вопрос AI-агенту. Например:

Какие инструменты MCP МойСклад сейчас доступны? 
Для каждого напиши, что он делает, какие параметры обязательны и что возвращает.

Рекомендуется повторно запрашивать список инструментов при переподключении к серверу, а также в случае, если ранее рабочий запрос перестал возвращать ожидаемую информацию.

Для первого запроса к данным лучше выбрать небольшой набор полей, явный фильтр и результат, который можно быстро проверить. Например:

Найди товары не в архиве. Верни только идентификатор, название и артикул.

Через MCP удобно работать, например, с такими запросами:

• «Покажи товары не в архиве: ID, название, артикул»
• «Найди заказы покупателей за эту неделю»
• «Какие позиции в заказе X?»
• «Какие товары скоро закончатся?»
• «Какие поля есть у заказа покупателя и что из них фильтруется?»
• «Покажи товары, которые закончатся в ближайшее время»
• «Сравни продажи за этот месяц с предыдущим»
• «Сегментируй клиентов по объему покупок за последние полгода»
• «Какие заказы или клиенты подходят под условие?»

Агент получает только те поля сущностей, которые доступны через MCP и которые он запросил.

Особенности работы MCP

Коротко опишем процесс работы с сервисом MCP.

Вы описываете задачу обычным языком. Далее агент выбирает инструмент, платформа вызывает MCP-сервер, сервер отправляет запрос в МойСклад и возвращает ответ. Агент формулирует результат.

Схема работы MCP МойСклад

• AI-платформа — место, где пользователь общается с агентом: Yandex AI Studio, Cursor, Codex, Claude Code и другие.
• AI-агент — выбранная модель агента на AI-платформе, с инструкциями и списком инструментов. Именно он решает, какой инструмент вызвать и с какими параметрами.
• MCP-сервер — отдает агенту инструменты.
• Аккаунт МойСклад — источник данных. Доступ открывается токеном из личного кабинета.

В MCP действия выполняются через специальные инструменты (tools). У каждого есть описание: что он делает, какие параметры нужны и что вернется.

Чем MCP отличается от JSON API 1.2

В своем аккаунте вы можете использовать оба инструмента, но важно понимать, какой из них подходит для ваших текущих целей и задач.

Для каких задач использовать MCP и JSON API 1.2

JSON API 1.2 следует использовать для следующих задач:

• Создание, обновление и удаление сущностей и позиций.
• Реализация сценариев, в которых требуется предсказуемая структура запросов и ответов.
• Реализация интеграций, результаты работы которых должны быть воспроизводимыми и не зависеть от интерпретации AI.
• Точное управление фильтрацией, сортировкой, пагинацией и составом возвращаемых данных.
• Обработка больших выборок с использованием limit/offset и expand.
• Получение и обработка событий с помощью вебхуков.
• Работа с аудитом, асинхронными задачами и массовыми операциями.
• Построение интеграционных сценариев с заранее заданной логикой.
• Организация обмена данными с интернет-магазинами, 1С, СУС, маркетплейсами и другими внешними системами без участия пользователя в чате.
• Реализация интеграций, выполняющих синхронизацию номенклатуры, документов и остатков по расписанию или по событиям.
• Работа в сценариях, где требуется полный и неизменный контракт API и обработка кодов ошибок.

MCP рекомендуется использовать для следующих задач:

• Выполнение запросов к данным аккаунта на естественном языке с возможностью уточнения запроса в ходе диалога.
• Исследование данных без предварительного знания структуры API и конкретных эндпоинтов.
• Быстрая проверка гипотез по данным без разработки отдельной интеграции или скрипта.
• Получение данных и их интерпретация в рамках одного диалога.
• Получение информации о доступных в аккаунте справочниках, документах и отчетах.
• Анализ возможностей использования данных аккаунта для построения статистики с помощью AI-агента.
• Формирование выборок для анализа, включая остатки, продажи, заказы, контрагентов и позиции документов.
• Последовательное уточнение аналитической выборки, например от определения проблемного периода к анализу конкретных товаров, заказов или контрагентов.
• Получение кратких сводок, сравнений и пояснений по данным аккаунта, например:
  • Определение дней с наибольшей частотой продаж или заказов с разбивкой по каналам продаж;
  • Анализ корреляции заказов и продаж по дням недели или месяцам;
  • Анализ частоты появления новых контрагентов;
  • Определение контрагентов, наиболее активно участвующих в продажах за выбранный период;
  • Выполнение других исследовательских и аналитических запросов к данным аккаунта.

Безопасность

Подключая MCP, вы даете платформе доступ к данным аккаунта от имени токена. К токену лучше относиться как к паролю.

• Держите токен в конфигурации платформы или в хранилище секретов, а не в Git и переписке.
• Не вставляйте токен в текст запроса — он должен находиться только в настройках MCP.
• Если есть вероятность утечки токена, отзовите его и выпустите новый.
• Не формулируйте запрос в формате «Выгрузи все»: это увеличивает контекст и повышает потребление токенов AI-агентом.
• Проверяйте результаты, полученные с помощью AI: возможны неточности и ошибочные интерпретации.

Подключение

Для подключения MCP понадобятся:

• Адрес MCP-сервера: https://mcp.moysklad.ru/tools/main.
• Токен из раздела МойСклад → Настройки → Токены, который передается в заголовке Authorization: Bearer <token>.

AI-агент также может помочь подключить MCP.

Yandex AI Studio

1. В МоемСкладе перейдите в раздел Настройки → Токены.
2. Создайте токен, скопируйте его и перейдите в Yandex AI Studio. При первой авторизации следуйте подсказкам сервиса.
3. Перейдите в меню Текстовые агенты и нажмите Создать агента.
4. В настройках агента перейдите в раздел Инструменты и добавьте MCP. Yandex AI Studio предложит создать MCP-сервер из шаблонов.
5. В шаблонах найдите МойСклад.
6. При подключении используйте токен, который вы получили в личном кабинете МоегоСклада.

Cursor

В Cursor MCP настраивается через файл mcp.json.

Подключение MCP через файл mcp.json

Пример заполнения файла mcp.json для добавления MCP-сервера:

{
  "mcpServers": {
    "moysklad-main": {
      "url": "https://mcp.moysklad.ru/tools/main",
      "headers": {
        "Authorization": "Bearer ВСТАВЬТЕ_ТОКЕН_СЮДА"
      }
    }
  }
}

После сохранения перезапустите Cursor.

Подключение MCP через интерфейс

Начиная с версии 3.9 все управление MCP-серверами находится на отдельной странице Customize. Чтобы подключить MCP-сервер:

1. Выполните Ctrl+Shift+P → Open Customize → MCPs или напрямую Ctrl+Shift+P → Open MCPs.
2. Добавьте MCP-сервер по кнопке + New MCP Server.
3. После сохранения перезапустите Cursor.

Codex

В Codex MCP настраивается через файл config.toml.

Подключение MCP через файл config.toml

Пример:

[mcp_servers.moysklad-main]
url = "https://mcp.moysklad.ru/tools/main"
 
[mcp_servers.moysklad-main.http_headers]
Authorization = "Bearer ВСТАВЬТЕ_ТОКЕН_СЮДА"

Синтаксис заголовков в разных версиях Codex может отличаться. Если сервер не запускается, сверьте ключ для заголовков с документацией вашей версии. Bearer-токен при этом остается тем же.

Чтобы проверить подключение, если установлен CLI, выполните команду:

codex mcp list

Плагин Codex в Cursor использует тот же файл ~/.codex/config.toml.

Подключение через десктопное приложение ChatGPT с Codex

1. Откройте десктопное приложение ChatGPT с Codex на Windows или macOS.
2. Перейдите в настройки (Settings).
3. Откройте вкладку Плагины.
4. Нажмите Добавить сервер.
5. Добавьте собственный MCP-сервер:
   • Name: moysklad-main;
   • URL: https://mcp.moysklad.ru/tools/main;
   • Токен: токен из МоегоСклада.
6. Сохраните данные. При необходимости перезапустите приложение.

Другие клиенты

MCP — открытый протокол, поэтому сервер можно подключать и к другим совместимым AI-клиентам и агентским платформам, например Claude Code. Для подключения к MCP-серверу в этих платформах используйте адрес https://mcp.moysklad.ru/tools/main и токен из личного кабинета МоегоСклада.