---
name: atisu-mcp
description: >-
  Работа с публичным API ATI.SU через ATI.SU MCP: поиск методов, просмотр схем
  и справочников, безопасное выполнение реальных API-запросов с Bearer-токеном
  пользователя.
---

# ATI.SU MCP

ATI.SU MCP — удалённый MCP-сервер публичного API ATI.SU. Используй его, когда
нужно найти метод API, понять контракт запроса/ответа, сгенерировать код
интеграции или выполнить запрос к API ATI.SU из агента.

Сервер не отдаёт отдельный tool на каждый метод API. Вместо этого он даёт
небольшой набор универсальных tools: найти метод, посмотреть схему, получить
справочники и выполнить запрос. Благодаря этому контекст модели не
перегружается описанием всего API. Всегда начинай с discovery, затем изучай
контракт метода, и только после этого вызывай API.

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

Удалённый MCP endpoint:

```text
https://api.ati.su/gw/panda-mcp/public/v1/mcp
```

Claude Code:

```bash
claude mcp add --transport http \
  --header "Authorization: Bearer <access_token>" \
  ati-su https://api.ati.su/gw/panda-mcp/public/v1/mcp
```

Cursor `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ati-su": {
      "type": "http",
      "url": "https://api.ati.su/gw/panda-mcp/public/v1/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}
```

Если клиент не умеет подключаться к удалённому HTTP MCP напрямую, используй
`mcp-remote`:

```bash
npx -y mcp-remote@latest \
  https://api.ati.su/gw/panda-mcp/public/v1/mcp \
  --header "Authorization: Bearer <access_token>"
```

Заголовок `Authorization` нужен только для `call_method`. Discovery tools
работают без токена.

## Tools

| Tool | Параметры | Для чего нужен |
| --- | --- | --- |
| `get_spec_info` | нет | Версия спеки, время обновления, счётчики методов и схем, доступные серверы и security schemes. |
| `list_categories` | нет | Категории API и примеры методов в каждой категории. |
| `search_methods` | `query`, опционально `category`, `http_method`, `limit` | Поиск методов по русским и английским ключевым словам, категории и HTTP-методу. |
| `get_method` | `operation_id` или `method` + `path`, `resolve_schemas`, `max_depth` | Полное описание метода: параметры, body, ответы, security и связанные схемы. |
| `get_schema` | `name`, `resolve_schemas`, `max_depth` | Схема из `components.schemas` по имени. |
| `list_dictionaries` | опционально `query`, `limit` | Справочные методы: города, страны, регионы, типы ТС и другие словари. |
| `call_method` | `operation_id` или `method` + `path`, опционально `path_params`, `query`, `body`, `token` | Реальный запрос к API ATI.SU с Bearer-токеном пользователя. |

## Рабочий маршрут

1. Начни с `list_categories` или `get_spec_info`.
2. Используй `search_methods`. Если метод не находится, пробуй несколько
   вариантов: сценарий на русском, сущность на английском, HTTP-метод.
3. Используй `get_method` для выбранного `operation_id`.
4. Используй `get_schema`, если в `get_method` есть `referenced_schemas` и
   нужны детали вложенных схем.
5. Используй `call_method` только после того, как показал пользователю метод,
   путь, query/body и получил явное подтверждение на реальный API-запрос.

Хорошие discovery-промпты:

```text
Через ATI.SU MCP найди метод API для публикации груза.
Покажи operation_id, обязательные поля и пример JSON body.
call_method пока не вызывай.
```

```text
Найди методы API для работы с заказами и сгруппируй их по сценарию.
```

```text
Покажи справочники городов и типов кузовов, нужные для создания груза.
```

## Bearer-токен

`call_method` нужен `access_token` ATI.SU. Передавай его так:

```http
Authorization: Bearer <access_token>
```

MCP-сервер не хранит токен. Он пробрасывает токен в `api.ati.su`, поэтому права
агента равны правам владельца токена.

Как пользователь получает токен:

1. Открывает `https://ati.su/developers/tokens/` — там перечислены его
   `access_token`.
2. Копирует нужный токен из списка.
3. Если подходящего токена нет, нажимает `Создать временный токен`: будет
   создан токен приложения `api-panda-portal`, действующий 7 дней.
4. Если у пользователя есть `client_id`, постоянный токен можно создать на той
   же странице.

Страница «Мои токены» использует такой HTTP-метод для создания токена по
`client_id`:

```http
POST https://ati.su/gw/auth/v1/tokens/{client_id}
Cookie: авторизованная браузерная сессия ATI.SU
```

Этот endpoint авторизуется cookie-сессией пользователя. Не пытайся вызывать его
из headless-агента напрямую, если пользователь явно не дал авторизованный
браузерный контекст.

## Правила безопасности

- Не проси пользователя вставлять реальный токен в чат.
- Не коммить конфиги с реальными токенами.
- Для поиска методов и генерации кода подключайся без `Authorization`.
- Считай `call_method` реальным production API-запросом, не моковым вызовом.
- Перед `POST`, `PUT`, `PATCH` или `DELETE` покажи пользователю operation, path,
  query и body, затем дождись явного подтверждения.
- Для тестов с грузами используй безопасные сценарии и персональные площадки,
  чтобы случайно не опубликовать данные в рабочем контуре ATI.SU.

## Если метод не находится

1. Вызови `list_categories`.
2. Повтори `search_methods` с несколькими вариантами: русский сценарий,
   английская сущность и HTTP-метод.
3. Примеры: `груз`, `cargo`, `published loads`, `POST`.
4. Если метод всё ещё неясен, спроси пользователя, какой UI-сценарий или
   бизнес-объект он имеет в виду. Не вызывай `call_method` на догадках.