# MCP для ИИ-ассистентов

MCP (Model Context Protocol) — способ дать ИИ-ассистенту наши данные. Подключите сервер datool.ru, и ассистент сам найдёт канал, посмотрит его статистику и посты и ответит на вопрос вроде «как рос канал @rbc в октябре».

## Адрес и ключ

- Адрес сервера: `https://api.datool.ru/v1/mcp/` (MCP поверх HTTP, «Streamable HTTP»).
- Ключ — тот же, что для API: заголовок `Authorization: Bearer dtk_ваш_ключ`. Ключ создаётся на странице «API-ключи» в кабинете.

!!! note
    Ассистент тратит запросы так же, как ваш код: каждый вызов инструмента стоит столько же единиц, сколько метод API, и открыто ему то же, что вашему тарифу. Справочники и `/v1/me/` — бесплатно.

## Claude Code

```bash
# добавить сервер datool в Claude Code; ключ — со страницы «API-ключи» в кабинете
claude mcp add --transport http datool https://api.datool.ru/v1/mcp/ \
  --header "Authorization: Bearer dtk_ваш_ключ"
```

## Cursor и другие клиенты

Добавьте сервер в настройки MCP (в Cursor — файл `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "datool": {
      "url": "https://api.datool.ru/v1/mcp/",
      "headers": { "Authorization": "Bearer dtk_ваш_ключ" }
    }
  }
}
```

Claude Desktop и другим клиентам, которые умеют только запускать программу у себя, поможет переходник `mcp-remote` (нужен Node.js). В Claude Desktop настройка — файл `claude_desktop_config.json` (Settings → Developer → Edit Config). Ключ передаётся через переменную окружения: пробел внутри аргумента ломает настройку в Windows.

```json
{
  "mcpServers": {
    "datool": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.datool.ru/v1/mcp/",
               "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer dtk_ваш_ключ" }
    }
  }
}
```

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

Инструменты — это методы API, которые читают данные, с теми же именами и параметрами, что в [справочнике методов](/api/methods/):

| Инструмент | Что делает |
|---|---|
| `me_retrieve` | кто я, тариф и остаток запросов |
| `max_channels_resolve_retrieve` | найти канал по ссылке, @имени или ID MAX |
| `max_channels_list` | каталог каналов с фильтрами |
| `max_channels_retrieve` | карточка канала |
| `max_stats_daily_list` | статистика по дням |
| `max_channels_posts_retrieve` | посты канала |
| `max_posts_retrieve` | один пост |
| `max_categories_list`, `max_territories_list` | справочники рубрик и территорий |

Изменять что-либо через MCP нельзя — например, вебхуки управляются только через API ключом «чтение и запись».

## Как это устроено внутри

Свой клиент MCP можно написать и без готовых программ: сервер принимает JSON-RPC 2.0 запросом POST и отвечает JSON.

```bash
# список инструментов (бесплатно)
curl -X POST https://api.datool.ru/v1/mcp/ \
  -H "Authorization: Bearer dtk_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

# вызвать инструмент: карточка канала @citynews (стоит как метод API — 1 единица)
curl -X POST https://api.datool.ru/v1/mcp/ \
  -H "Authorization: Bearer dtk_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "max_channels_retrieve", "arguments": {"channel": "citynews"}}}'
```

Ответ на вызов инструмента — ответ метода API текстом (`content`) и объектом (`structuredContent`):

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{"type": "text", "text": "{\"id\": 4821, \"title\": \"Городские новости\", …}"}],
    "structuredContent": {"id": 4821, "title": "Городские новости", "subscribers": 128450},
    "isError": false
  }
}
```

| Метод протокола | Что делает |
|---|---|
| `initialize` | Знакомство: версия протокола, имя сервера, подсказка ассистенту |
| `tools/list` | Список инструментов с описаниями и входными схемами |
| `tools/call` | Вызвать инструмент: `name` и `arguments` (как параметры метода API) |
| `ping` | Проверка связи |

Сеансов и потока событий нет: каждый запрос самостоятельный, GET на адрес сервера — 405.

## Если ассистент пишет об ошибке

Ошибка метода приходит ассистенту текстом с кодом, например `403 tariff_required` — посты закрыты на «API.Max Тест», или `429 quota_exceeded` — запросы за период закончились. Коды — на странице [«Ошибки»](/api/errors/).

| Что случилось | Что приходит |
|---|---|
| Ошибка метода API (тариф, нет канала, лимит) | `result` с `isError: true` и текстом вида `403 tariff_required: …` |
| Неизвестный инструмент, лишний или пропущенный аргумент, значение, ломающее адрес (`/`, `?`, `#`) | ошибка JSON-RPC `-32602` |
| Неверный тип или значение аргумента (например, `kind=group`) | `result` с `isError: true` и ошибкой метода `400` — стоит как запрос |
| Неизвестный метод протокола | ошибка JSON-RPC `-32601` |
| Тело не JSON или не объект JSON-RPC 2.0 | ошибки JSON-RPC `-32700` и `-32600` |
| Нет ключа или ключ неверный | ответ HTTP 401 |