# MCP-сервер

Сервер [Model Context Protocol](https://modelcontextprotocol.io) для Claude, Cursor и любого
клиента MCP: каталог, каналы, их сравнение и закрепление, чат и задачи — инструментами.

- Адрес — `https://api.souz.ai/mcp`, транспорт Streamable HTTP, версия протокола
  `2025-06-18` (понимает и `2025-03-26`, `2024-11-05`). Ответы — JSON на каждый `POST`, без
  сессий.
- Ключ — заголовок `Authorization: Bearer <ключ>` подключения. Инструмент вызывает метод API
  с этим заголовком: права, лимиты и цены — как у метода.

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

```bash tab="Claude Code"
claude mcp add --transport http souz https://api.souz.ai/mcp \
  --header "Authorization: Bearer $SOUZ_API_KEY"
```

```json tab="Cursor"
{
  "mcpServers": {
    "souz": {
      "url": "https://api.souz.ai/mcp",
      "headers": { "Authorization": "Bearer ${env:SOUZ_API_KEY}" }
    }
  }
}
```

```bash tab="cURL"
curl https://api.souz.ai/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

Cursor читает конфигурацию из `~/.cursor/mcp.json` или `.cursor/mcp.json` проекта.

## Какой ключ

| Инструменты | Ключ |
|---|---|
| `list_models`, `get_model`, `list_channels`, `compare_channels`, `preview_routing` | не нужен |
| `run_chat`, `get_job` | API-ключ (`sk_…`) |
| `get_routing_settings`, `pin_channel`, `unpin_channel` | ключ управления (`mk_…`); правка — с ролью разработчика или выше |

Агенту, которому нужно и то и другое, подключают два сервера с разными именами — `souz` с
API-ключом и `souz-account` с ключом управления. Не тот ключ — не ошибка протокола, а
результат инструмента с `isError: true`: код ошибки API и подсказка, какой ключ нужен.

## Инструменты

Каждый инструмент отвечает текстом (с таблицей Markdown) и теми же данными объектом
(`structuredContent`). Деньги в объекте — целые микроединицы `currency`, в тексте — рубли.

| Инструмент | Что делает | Метод API |
|---|---|---|
| `list_models` | модели каталога: цена «от», итоги 7 дней; фильтр `modality` | `GET /v1/models` |
| `get_model` | карточка: `input_schema`, `params`, `rules`, лимиты, цены пресетов | `GET /v1/models/{id}` |
| `list_channels` | каналы модели: цвет, доступность, ставки, пределы, задержка, скорость, доля успешных; таблица по `sort_by` | `GET /v1/models/{id}/channels` |
| `compare_channels` | рейтинг доступных каналов по `by` (`price`, `latency`, `throughput`, `stability`) и лучший по каждому критерию; с `params` или токенами — оценка каждого канала превью | `GET …/channels` и `POST …/routing/preview` |
| `preview_routing` | порядок попыток с ценой каждого канала и не вошедшие каналы с причинами | `POST /v1/models/{id}/routing/preview` |
| `get_routing_settings` | пресет, потолок цены и `routing_options` аккаунта; с `model` — какая настройка действует | `GET /v1/settings` |
| `pin_channel` | закрепить цвет за моделью: `mode: only` — только он, `prefer` — сначала он | `GET` и `PATCH /v1/settings` |
| `unpin_channel` | снять закрепление цветов модели | `GET` и `PATCH /v1/settings` |
| `run_chat` | ответ чат-модели без потока: текст, токены, `usage.cost`, фактический `channel` | `POST /v1/chat/completions` |
| `get_job` | задача по id: статус, канал, попытки, итог, файлы, ошибка | `GET /v1/jobs/{id}` |

Картинки, видео, музыка, транскрибация и речь пока запускаются через HTTP API; их итог
читает `get_job`.

## Рецепт: лучший канал и закрепление

1. `compare_channels {"model": "gpt-5-nano", "by": "stability"}` — рейтинг доступных цветов и
   лучший по цене, задержке, скорости и стабильности; для своего сценария — `input_tokens`
   и `output_tokens` (чат) или `params` (картинки, видео).
2. `preview_routing {"model": "gpt-5-nano", "routing_options": {"only": ["blue"]}}`:
   подходит ли цвет запросу.
3. Закрепить для аккаунта (ключ управления):
   `pin_channel {"model": "gpt-5-nano", "channel": "blue", "mode": "only"}`; проверка —
   `get_routing_settings {"model": "gpt-5-nano"}`, отмена — `unpin_channel`.
4. Только для одного запроса — `run_chat` с `"routing_options": {"only": ["blue"]}`.

`pin_channel` меняет только выбор цветов этой модели. Цены и скорость каналов меняются —
сравнивайте перед важной работой.

## Ошибки MCP

- Ошибка протокола — `error` JSON-RPC: `-32700` — тело не JSON, `-32600` — не запрос
  JSON-RPC (в том числе пакет), `-32601` — нет метода, `-32602` — неизвестный инструмент
  или неверные аргументы (`error.data.errors[]` — `path`, `reason`, `allowed`), `-32603` —
  сбой сервера.
- Отказ ручки API — результат инструмента с `isError: true`: код, сообщение и подсказка в
  тексте, `status` и `error` — в `structuredContent`.
- Транспорт: неизвестный `MCP-Protocol-Version` — `400`; `Origin` чужого сайта — `403`;
  больше 8 МиБ — `413`; без ключа или с незнакомым ключом больше 600 сообщений в минуту с
  одного адреса — `429` с `Retry-After`.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.