# MCP сервер

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

## Что это

Сервер реализует протокол Model Context Protocol (версия 2025-06-18) поверх Streamable HTTP. Точка монтирования — /mcp/, имя сервера — samreshuuu-coworker. Через него тот же набор инструментов, которым пользуется ассистент в чате, доступен внешним клиентам: каталог из ~90 интеграций, REPL для Python и доступ к памяти и Диску пользователя.

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

Добавьте блок ниже в claude_desktop_config.json, mcp.json в Cursor или эквивалентный конфиг вашего клиента. URL и готовый JSON также доступны в настройках проекта.

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

[Создать API-ключ в настройках →](/settings/api-keys)

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

Каждый запрос требует заголовок Authorization: Bearer sk-org-… Ключ выдаётся в разделе «API-ключи» настроек организации, имеет скоупы (read:tools, write:tools, read:data, admin, chat) и срок действия. Контекст пользователя и организации привязан к ключу — отдельный X-Org-Id передавать не нужно.

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

GET /api/v1/mcp/info возвращает URL, имя сервера, версию протокола, список поддерживаемых скоупов и пример конфига. Эндпойнт не требует аутентификации — удобно для генерации сниппетов на стороне клиента.

```json
{
  "url": "https://api.samreshuuu.ru/mcp/",
  "server_name": "samreshuuu-coworker",
  "protocol_version": "2025-06-18",
  "supported_scopes": ["read:tools", "write:tools", "read:data", "admin", "chat"],
  "example_config": { "mcpServers": { "samreshuuu-coworker": { "url": "...", "headers": { "Authorization": "Bearer sk-org-<your-key>" } } } }
}
```

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

Те же инструменты, что использует чат-ассистент. user_id и org_id выводятся из bearer-ключа, поэтому каждый вызов работает в контексте владельца ключа.

| Инструмент | Назначение |
| --- | --- |
| `list_services` | Каталог коннекторов: имя + однострочное описание для каждого из ~90 сервисов. Hand­shake-размер (~2–5 КБ) — с него начинается любая сессия. |
| `describe_service` | Полный паспорт одного сервиса: модули, типовые рецепты, лимиты, подсказки по полям и пагинации, а также version/ttl для клиентского кэша. |
| `connector_execute` | Единая точка вызова любого коннектора. Для REST-сервисов — module + HTTP-метод + path + body/query; для RPC (bitrix24, onec и т. п.) — оставьте path пустым, передайте RPC-метод в method. |
| `repl_execute` | Исполнение Python-кода в песочнице пользователя. Учётные данные подключённых коннекторов автоматически прокидываются в env (WILDBERRIES_API_KEY и т. п.). Запрошенные навыки монтируются в `/mnt/skills/<id>/scripts/`. |
| `read_memory` | Чтение персонального хранилища памяти пользователя: read одного файла, list по префиксу с пагинацией, read_many для батча до 50 путей. |

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

```bash
→ 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"]
  )
```

## Skill-ресурсы

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

## Ошибки

Ошибки инструментов приходят как стандартный MCP ToolError, тело — JSON с полями code, message, retryable и опциональными hint и details. Базовый набор кодов:

```json
{
  "code": "UNKNOWN_SERVICE",
  "message": "Connector 'foo' not registered",
  "retryable": false,
  "hint": "Known services: wildberries, ozon, telegram, ..."
}
```

| Поле | Описание |
| --- | --- |
| `UNAUTHENTICATED` | Отсутствует или некорректный bearer-ключ. Проверьте префикс sk-org- и срок действия. |
| `UNKNOWN_SERVICE` | Указан несуществующий коннектор. В hint возвращается список зарегистрированных сервисов. |
| `INVALID_ARG` | Невалидный аргумент: неизвестный module/method, ошибка валидации Pydantic или нарушение контракта инструмента. В details приходят подробности. |
| `NOT_FOUND` | Ресурс не найден (например, файл памяти по указанному path). |
| `UPSTREAM_ERROR` | Внешний сервис вернул ошибку. Поле retryable показывает, имеет ли смысл повторить запрос. |

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

- [Настройки → API-ключи и MCP-сервер](/settings/api-keys)
- [Аутентификация — Bearer-токены и контекст организации](/docs/authentication)