MCP сервер

Подключите Claude Desktop, Cursor или любой MCP-клиент к каталогу коннекторов samreshuuu и сэндбоксу для исполнения кода.

Что это

Сервер реализует Model Context Protocol поверх Streamable HTTP по адресу https://samreshuuu.ru/mcp/ (с завершающим слешем). Версию протокола сервер согласует с клиентом при подключении: принимаются 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25, а клиенту с незнакомой ревизией сервер отвечает 2025-11-25. Внешнему клиенту открыты каталог коннекторов организации и Python-песочница.

Сервер без состояния: каждый POST обрабатывается независимо, Mcp-Session-Id не выдаётся. Локального stdio-сервера и устаревшего транспорта HTTP+SSE нет; клиенту, который умеет только stdio, нужен мост mcp-remote (пример для Claude Desktop ниже).

Подключение клиента

Добавьте блок ниже в mcp.json в Cursor или эквивалентный конфиг вашего клиента. Готовые конфиги с вашим адресом есть в настройках, раздел «API-ключи».

{ "mcpServers": { "samreshuuu-coworker": { "url": "https://samreshuuu.ru/mcp/", "headers": { "Authorization": "Bearer sk-org-xxxxxxxxxxxx" } } } }

Создать API-ключ в настройках →

Claude Desktop

Конфиг Claude Desktop запускает только локальные серверы, поэтому к удалённому серверу с ключом он подключается через мост mcp-remote. Нужен Node.js 18 или новее. Откройте Settings → Developer → Edit Config и вставьте в claude_desktop_config.json:

{ "mcpServers": { "samreshuuu-coworker": { "command": "npx", "args": [ "-y", "mcp-remote", "https://samreshuuu.ru/mcp/", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer sk-org-xxxxxxxxxxxx" } } } }

Заголовок передаётся через переменную окружения: пробел внутри args ломает запуск на Windows. После сохранения перезапустите Claude Desktop.

Claude Code

claude mcp add --transport http samreshuuu-coworker https://samreshuuu.ru/mcp/ --header "Authorization: Bearer sk-org-xxxxxxxxxxxx"

Codex

В ~/.codex/config.toml ключ читается из переменной окружения (без префикса Bearer):

[mcp_servers.samreshuuu-coworker] url = "https://samreshuuu.ru/mcp/" bearer_token_env_var = "SAMRESHUUU_API_KEY"

VS Code

В .vscode/mcp.json:

{ "servers": { "samreshuuu-coworker": { "type": "http", "url": "https://samreshuuu.ru/mcp/", "headers": { "Authorization": "Bearer sk-org-xxxxxxxxxxxx" } } } }

Аутентификация

Каждый HTTP-запрос к /mcp/ несёт заголовок Authorization: Bearer sk-org-…. Пользователь и организация берутся из ключа, X-Org-Id не нужен. На запрос без годного ключа сервер отвечает ещё до разбора MCP-сообщения: HTTP 401, заголовок WWW-Authenticate: Bearer realm="samreshuuu" и тело detail нативного API (не объект ошибки /v1):

{ "detail": { "code": "AUTH_INVALID_CREDENTIALS", "message": "Ключ API не найден, отозван или истёк. Выпустите новый ключ в настройках организации.", "hint": null, "is_retryable": false, "message_en": "Invalid, revoked or expired API key. Create a new key in the organization settings." } }

HTTP	Код	Значение	Повтор
401	`AUTH_HEADER_MISSING`	Отсутствует заголовок авторизации.	нет
401	`AUTH_TOKEN_INVALID`	Недействительный токен авторизации.	нет
401	`AUTH_INVALID_CREDENTIALS`	Не удалось подтвердить вход. Попробуйте ещё раз.	нет

AUTH_HEADER_MISSING значит, что заголовка Authorization нет; AUTH_TOKEN_INVALID, что заголовок не вида Bearer sk-org-…; AUTH_INVALID_CREDENTIALS, что ключ неизвестен, отозван или истёк.

OAuth 2.1 (обнаружение сервера авторизации, динамическая регистрация клиента) сервер не поддерживает: только ключ в заголовке. Если клиент подключает удалённые серверы лишь через OAuth, используйте мост mcp-remote с заголовком, как для Claude Desktop.

Скоупы ключа: чтение (list_services, describe_service и читающие вызовы connector_execute) требует tools:read. Пишущие вызовы connector_execute и любой repl_execute требуют tools:write, он включает tools:read. Без нужного скоупа приходит AUTH_PERMISSION_DENIED. Пишущий ли вызов, решает классификатор коннектора, а не HTTP-метод: POST-запрос на чтение (например, отчёт маркетплейса) проходит и с ключом tools:read. Скоуп chat:write к MCP не относится, он открывает OpenAI-совместимый API.

Публичный info-эндпойнт

GET /api/v1/mcp/info возвращает URL, имя сервера для конфига клиента (samreshuuu-coworker), принимаемые ревизии протокола в protocol_versions (от старой к новой) и предпочтительную в preferred_protocol_version, поддерживаемые скоупы и пример конфига. Эндпойнт не требует аутентификации: удобно для генерации сниппетов на стороне клиента.

{ "url": "https://samreshuuu.ru/mcp/", "server_name": "samreshuuu-coworker", "protocol_versions": ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"], "preferred_protocol_version": "2025-11-25", "supported_scopes": ["tools:read", "tools:write", "chat:write", "sessions:read", "sessions:write"], "example_config": { "mcpServers": { "samreshuuu-coworker": { "url": "https://samreshuuu.ru/mcp/", "headers": { "Authorization": "Bearer sk-org-<your-key>" } } } } }

Доступные инструменты

Каждый вызов выполняется на общих подключениях организации и в песочнице ключа; личные кабинеты и память создателя ключа закрыты. Таблица взята из реестра инструментов сервера.

Инструмент	Scope ключа	Подсказки	Описание
`list_services`	`tools:read` (входит в `tools:write`)	только чтение	Каталог сервисов
`describe_service`	`tools:read` (входит в `tools:write`)	только чтение	Паспорт сервиса
`connector_execute`	`tools:write` для записи, `tools:read` для чтения	может менять данные, в лимите ключа	Вызов сервиса
`repl_execute`	`tools:write` на каждый вызов	может менять данные, в лимите ключа	Код и данные

Параметры:

list_services: без параметров. Показывает, какие сервисы есть, а не какие подключены у пользователя; внутренние сервисы в список не входят.
describe_service: service, module?. Без module возвращает оглавление сервиса: модули, шаблон вызова, заголовки рецептов. С module: рецепты с телами, лимиты, подсказки по полям и пагинации, а также version/ttl для клиентского кэша.
connector_execute: service, method, path?, module?, body?, query?. REST: HTTP-метод и path, module подставляется по рецептам. RPC (bitrix24, onec и т. п.): module (например, crm), RPC-метод в method (crm.deal.list), path пустой. Если подключено несколько кабинетов, назовите нужный: service="wildberries:<имя>"; отдельного аргумента для кабинета нет, а незаявленный аргумент (например, прежний instance_id) отказывается с TOOL_VALIDATION_FAILED.
repl_execute: code, skills?, timeout_seconds?. Python в песочнице, привязанной к этому ключу. Ответ: stdout, stderr, exit_code, error, files, truncated.

Секреты коннекторов (ключи API, токены, пароли) в окружение песочницы не попадают: код обращается к коннектору через хост, у которого и лежат креды. Через MCP repl_execute не получает и собственных переменных пользователя, а его вывод проверяется, найденные секреты маскируются.

Типичная последовательность вызовов:

→ list_services() → describe_service("wildberries") → connector_execute( service="wildberries", module="statistics", method="GET", path="/api/v1/supplier/orders", query={"dateFrom": "2026-04-15"} ) → repl_execute( code="from wb_analytics import abc_classify; ...", skills=["wb_analytics"] )

Лимиты и долгие вызовы

connector_execute и repl_execute считаются в лимит запросов ключа, который задаёт тариф организации; list_services и describe_service в него не входят. Пока идёт долгий connector_execute или repl_execute, сервер с коротким интервалом шлёт уведомления о прогрессе, если клиент передал progressToken: клиент, который сбрасывает таймаут по прогрессу, не оборвёт вызов. timeout_seconds у repl_execute выше потолка песочницы урезается до него. Ответы коннекторов и песочницы проходят проверку, найденные секреты маскируются.

Skill-ресурсы

Каждый включённый навык экспонируется как MCP-ресурс по схеме skill://{name}. Тело ресурса: системный промпт навыка плюс подсказка о том, как вызывать connector_execute с привязанным сервисом. На первом аутентифицированном запросе сервер однократно регистрирует ресурсы для всех включённых навыков, после чего resources/list их перечисляет.

Ошибки

Ошибка инструмента приходит результатом вызова с isError: true, текст результата несёт JSON-объект {code, message, retryable, hint?, details?}. MCP SDK может добавить перед текстом префикс Error executing tool …:; JSON идёт после него. details несёт данные об ошибке (кандидаты, подсказки), а не инструкции. Ошибка ключа приходит раньше, HTTP 401 (см. Аутентификация).

{ "code": "TOOL_VALIDATION_FAILED", "message": "…", "retryable": false, "details": { "suggestions": ["wildberries"], "connector_code": "UNKNOWN_SERVICE" } }

Каждый код это строка реестра ошибок сервера, того же, которым отвечает HTTP API. Собственные отказы MCP-сервера:

TOOL_VALIDATION_FAILED: коннектора нет в каталоге, module неизвестен или не выводится по рецептам, либо аргумент невалиден. Близкие имена в details.suggestions, модули в details.known_modules; исправьте вызов и отправьте снова.
UNKNOWN_INSTANCE: названный кабинет не подключён, или подключено несколько и нужный не назван. Список в details.candidates.
AUTH_PERMISSION_DENIED: у ключа нет скоупа, который требует инструмент (tools:read для чтения, tools:write для пишущего вызова или repl_execute). APPROVAL_NOT_ASKABLE: запись требует одобрения, а спросить через MCP некого; повтор не поможет, выполните действие в чате, где его можно одобрить. TOOL_AUTO_REVIEW_BLOCKED: автопроверка запретила запись (секрет уходит не тому сервису, который его выдал); одобрение этот запрет не снимает.
RATE_LIMIT_EXCEEDED: превышен лимит запросов ключа, подождите details.retry_after_s.

Упавший вызов коннектора передаёт код реестра своей ошибки (см. Ошибки и лимиты). Поле retryable результата это вердикт для этого вызова, и оно главнее колонки таблицы, которая описывает код в целом.

Если отказ поднят под собственным написанием коннектора или шлюза, это написание приходит в details.connector_code для диагностики. Ветвитесь по code: connector_code называет место отказа и пополняется вместе с коннекторами.

Полезные ссылки