# ATI.SU MCP для AI-агентов ## Что умеет ATI.SU MCP ATI.SU MCP — официальный MCP-сервер для работы с публичным API ATI.SU. Вместо отдельных MCP-инструментов для каждого метода API сервер предоставляет небольшой набор универсальных инструментов. Агент сначала находит нужный метод, затем изучает его контракт и только после этого выполняет запрос. Благодаря этому контекст модели не перегружается описанием всего API, а агент получает только ту информацию, которая нужна в текущий момент. Без Bearer-токена доступны discovery-инструменты: - поиск методов API; - просмотр схем; - работа со справочниками. Bearer-токен требуется только для `call_method`, который выполняет реальные запросы к API ATI.SU. ## Быстрый старт ### 1. Подключите сервер #### Cursor Добавьте сервер в `~/.cursor/mcp.json` и переподключите MCP: ```json { "mcpServers": { "ati-su": { "type": "http", "url": "https://api.ati.su/gw/panda-mcp/public/v1/mcp", "headers": { "Authorization": "Bearer " } } } } ``` #### Claude Code ```bash claude mcp add --transport http \ --header "Authorization: Bearer " \ ati-su https://api.ati.su/gw/panda-mcp/public/v1/mcp ``` Если нужен только поиск методов и схемы, заголовок `Authorization` можно не передавать. #### VS Code и другие Если клиент не подключается к удалённому MCP напрямую, используйте `mcp-remote`: ```json { "servers": { "ati-su": { "type": "stdio", "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://api.ati.su/gw/panda-mcp/public/v1/mcp", "--header", "Authorization: Bearer " ] } } } ``` ### 2. Получите Bearer-токен Bearer-токен требуется только для выполнения `call_method`. Добавьте его в конфигурацию MCP: ```http Authorization: Bearer ``` Откройте [Мои токены](/developers/tokens/) — там перечислены ваши `access_token`. Если подходящего токена нет, нажмите «Создать временный токен»: будет создан токен приложения `api-panda-portal`, действующий 7 дней. Если у вас уже есть `client_id`, постоянный токен можно создать в [Моих токенах](/developers/tokens/) или вызвать: ```http POST https://ati.su/gw/auth/v1/tokens/{client_id} Cookie: ваша авторизованная сессия ATI.SU ``` Если `client_id` ещё нет, сначала пройдите [инструкцию по получению access_token](https://ati.su/developers/raw/auth/auth.md). ### 3. Выполните первый запрос Лучше начать не с выполнения метода, а с его поиска. ```text Через ATI.SU MCP найди метод API для публикации груза. Покажи operation_id, обязательные поля и пример JSON body. call_method пока не вызывай. ``` После этого агент найдёт подходящий метод, покажет его описание и только затем сможет выполнить запрос. ## SKILL.md для AI-агента `SKILL.md` — готовая инструкция для AI-агента. В файле уже описаны: - endpoint сервера; - порядок вызова MCP-инструментов; - правила работы с Bearer-токеном; - ограничения `call_method`; - готовые промпты. Скачайте файл и передайте его агенту либо откройте эту страницу в агенте и попросите следовать инструкции из `SKILL.md`. После этого можно просто написать: «Через ATI.SU MCP найди нужный метод API». Если потребуется выполнить реальный запрос, агент сначала попросит Bearer-токен, а затем запросит подтверждение перед вызовом API. [Скачать SKILL.md](/developers/atisu-mcp/SKILL.md) ## Полный SKILL.md для агента Ниже полный текст skill-файла. Его можно передать агенту как инструкцию или сохранить отдельным файлом `SKILL.md`. ````markdown --- 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 " \ 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 " } } } } ``` Если клиент не умеет подключаться к удалённому HTTP MCP напрямую, используй `mcp-remote`: ```bash npx -y mcp-remote@latest \ https://api.ati.su/gw/panda-mcp/public/v1/mcp \ --header "Authorization: Bearer " ``` Заголовок `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 ``` 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` на догадках. ```` ## Инструменты | Tool | Для чего нужен | | --- | --- | | `get_spec_info` | Показывает версию спеки, время обновления, счётчики методов и схем, доступные серверы и security schemes. | | `list_categories` | Возвращает категории API и примеры методов в каждой категории. | | `search_methods` | Ищет методы по русским и английским ключевым словам, категории и HTTP-методу. | | `get_method` | Полное описание метода: параметры, body, ответы, security и связанные схемы. | | `get_schema` | Показывает схему из `components.schemas` по имени. | | `list_dictionaries` | Находит справочные методы: города, страны, регионы, типы ТС и другие словари. | | `call_method` | Реальный запрос к API ATI.SU с Bearer-токеном пользователя. | ## Если агент не находит нужный метод Попросите агента выполнить поиск поэтапно: - вызвать `list_categories`; - выполнить `search_methods` несколькими способами: по сценарию на русском языке, по названию сущности на английском, по HTTP-методу. Например: `груз`, `cargo`, `published loads`, `POST`. ## Безопасность `call_method` выполняет реальные запросы к API ATI.SU. Для тестирования публикации грузов рекомендуется использовать безопасные сценарии и персональные площадки, чтобы не создавать реальные перевозки. Bearer-токен не хранится на MCP-сервере. Он передаётся только в заголовке `Authorization` и используется для обращения к API ATI.SU. Агент получает только те права, которые есть у вашего токена. Не отправляйте Bearer-токены в чат с агентом и не публикуйте их в репозиториях. Если вам нужны только поиск методов, просмотр схем и генерация кода, подключайте MCP без заголовка `Authorization`. --- ## llms.txt Индекс ключевых страниц документации для LLM и AI-агентов доступен в [основном llms.txt](https://ati.su/developers/llms.txt).