# Подключение к MCP-серверу Адрес сервера один для всех клиентов, транспорт — Streamable HTTP: ``` https://routerai.ru/api/v1/mcp ``` Подключить агента можно двумя способами: - **Через браузер** — рекомендуем. Агент сам откроет RouterAI, вы подтвердите доступ, и токен сохранится в агенте. Копировать ничего не нужно. - **Готовым токеном** — если агент не умеет входить через браузер, работает на удалённой машине или в CI. ## Через браузер Добавьте сервер и запустите вход — выполните команды для вашего агента. Cursor подключается иначе — через файл настроек, шаги в разделе [Cursor](#cursor). ```bash claude mcp add --transport http \ routerai https://routerai.ru/api/v1/mcp claude mcp login routerai ``` ```bash codex mcp add routerai \ --url https://routerai.ru/api/v1/mcp codex mcp login routerai ``` ```bash opencode mcp add routerai --global \ --url https://routerai.ru/api/v1/mcp opencode mcp auth routerai ``` Дальше: 1. Откроется браузер. Войдите в RouterAI, если ещё не вошли. 2. На экране «Подключение приложения» проверьте настройки токена: - **Аккаунт** — личный или команда, где вы администратор. Платные запросы тратят баланс выбранного аккаунта. - **Разрешения** — агенты запрашивают все разрешения сразу. Снимите те, что агенту не нужны, например «Платные запросы к моделям». - **Лимит расходов** — сколько агент может потратить на платные запросы за месяц. По умолчанию 500 ₽. - **Срок действия** — 7, 30 или 90 дней. 3. Нажмите «Разрешить доступ». Браузер вернёт вас к агенту — подключение готово. Особенности клиентов: - **Claude Code** добавляет сервер в текущий проект. Чтобы сервер был доступен во всех проектах, добавьте к `claude mcp add` флаг `--scope user`. Войти можно и из самого Claude Code: команда `/mcp`, сервер `routerai`, пункт авторизации. - **Codex CLI** сам открывает вход в браузере сразу после `codex mcp add`. Команда `codex mcp login routerai` нужна, если окно не открылось или вход надо повторить. Платные инструменты `send_message` и `generate_image` Codex запускает только после вашего подтверждения; в `codex exec` без подтверждений они не выполнятся. - **OpenCode** — команды для OpenCode 2. Флаг `--global` добавляет сервер во все проекты. ## Личный аккаунт и команда одновременно Одна запись сервера в агенте хранит один токен. Повторный вход в ту же запись заменяет его: `claude mcp login routerai` сначала отзывает текущий токен и только потом открывает браузер — даже если на экране согласия вы выберете другой аккаунт. Поэтому, если войти в запись `routerai` личным аккаунтом, а затем командой, личный токен будет отозван. Чтобы агент работал с обоими аккаунтами, добавьте сервер дважды под разными именами и войдите в каждую запись отдельно: ```bash claude mcp add --transport http --scope user \ routerai https://routerai.ru/api/v1/mcp claude mcp add --transport http --scope user \ routerai-team https://routerai.ru/api/v1/mcp claude mcp login routerai # выберите личный аккаунт claude mcp login routerai-team # выберите команду ``` У агента появятся два набора инструментов RouterAI — по одному на аккаунт, а в разделе [Ключи → MCP-токены](https://routerai.ru/settings/keys?tab=mcp) — токены «Claude Code (routerai)» и «Claude Code (routerai-team)». ## Cursor Cursor подключается через файл настроек, а вход запускается в самом Cursor. 1. Добавьте сервер в файл `~/.cursor/mcp.json` — для всех проектов — или в `.cursor/mcp.json` в корне проекта. Если файл уже есть, добавьте `routerai` внутрь существующего `mcpServers`: ```json { "mcpServers": { "routerai": { "url": "https://routerai.ru/api/v1/mcp" } } } ``` 2. Откройте **Cursor Settings → Tools & MCP** и у сервера `routerai` нажмите **Connect**. Откроется браузер с экраном «Подключение приложения»: проверьте настройки токена, как описано [выше](#через-браузер), и нажмите «Разрешить доступ». 3. Когда вход пройдёт, у сервера `routerai` загорится зелёный индикатор, а инструменты RouterAI станут доступны агенту. Cursor CLI читает тот же файл: вход — `agent mcp login routerai`, список серверов — `agent mcp list`. ## Готовым токеном Выпустите MCP-токен в разделе [Ключи → MCP-токены](https://routerai.ru/settings/keys?tab=mcp) — он показывается один раз, сразу скопируйте его. Затем передайте токен агенту, подставив его вместо `rmcp_…`: ```bash claude mcp add --transport http \ routerai https://routerai.ru/api/v1/mcp \ --header "Authorization: Bearer rmcp_…" ``` ```bash export ROUTERAI_MCP_TOKEN=rmcp_… codex mcp add routerai \ --url https://routerai.ru/api/v1/mcp \ --bearer-token-env-var ROUTERAI_MCP_TOKEN ``` ```bash opencode mcp add routerai --global \ --url https://routerai.ru/api/v1/mcp \ --header "Authorization=Bearer rmcp_…" ``` В **Cursor** добавьте токен в заголовок сервера в `~/.cursor/mcp.json` — тогда вход через браузер не нужен: ```json { "mcpServers": { "routerai": { "url": "https://routerai.ru/api/v1/mcp", "headers": { "Authorization": "Bearer rmcp_…" } } } } ``` - Команду для Claude Code с вашим токеном показывает окно выпуска токена в личном кабинете — её можно скопировать целиком. - Codex читает токен из переменной окружения при каждом запуске. Чтобы переменная не пропала после перезапуска терминала, добавьте строку `export` в `~/.bashrc` или `~/.zshrc`. - Храните токен для Cursor в `~/.cursor/mcp.json`, а не в `.cursor/mcp.json` проекта, — иначе он может попасть в репозиторий. Вместо самого токена Cursor умеет подставить переменную окружения: `"Authorization": "Bearer ${env:ROUTERAI_MCP_TOKEN}"`. - Не добавляйте в репозиторий файлы конфигурации с токеном. ## Другие клиенты Подойдёт любой клиент с поддержкой удалённых MCP-серверов по Streamable HTTP: - **Адрес:** `https://routerai.ru/api/v1/mcp` - **Заголовок:** `Authorization: Bearer ` Для входа через браузер клиент должен поддерживать OAuth 2.1. Сервер публикует метаданные по адресу `https://routerai.ru/.well-known/oauth-protected-resource/api/v1/mcp`, поддерживает динамическую регистрацию клиента и PKCE (S256). Клиенты с поддержкой OAuth находят всё это сами по адресу сервера. ## Проверка Статус подключения показывают команды `claude mcp list`, `codex mcp list` и `opencode mcp list`, в Cursor — **Cursor Settings → Tools & MCP**. Спросите агента: «Какой у меня баланс в RouterAI?» — он вызовет `get_balance` и покажет остаток на балансе и лимит токена. ## Повторный вход и отключение Когда срок действия токена истекает, агент получает ошибку авторизации. Повторите вход: `claude mcp login routerai`, `codex mcp login routerai` или `opencode mcp auth routerai`, в Cursor — в **Cursor Settings → Tools & MCP**. Если вы подключались готовым токеном, выпустите новый и замените его в настройках агента. Claude Code при повторном входе отзывает прежний токен сам. Codex CLI и OpenCode — нет: каждый вход выпускает новый токен, а прежний продолжает действовать до конца срока. После повторного входа в этих агентах отзовите старый токен в разделе [Ключи → MCP-токены](https://routerai.ru/settings/keys?tab=mcp) — у него более раннее время создания и то же название. Чтобы отключить агента, отзовите его токен в том же разделе. Claude Code отзывает свой токен сам по команде `claude mcp logout routerai`. Команды `codex mcp logout routerai` и `opencode mcp logout routerai` токен на сервере не отзывают: он остаётся действующим, его нужно отозвать в личном кабинете. ## Если что-то не работает | Что происходит | Причина и решение | | --- | --- | | Браузер не открылся при входе | Агент решил, что работает без графического окружения, например по SSH, и вывел ссылку. Откройте её в браузере на том же компьютере, где запущен агент. | | Агент работает на удалённой машине | В Claude Code войдите командой `claude mcp login routerai --no-browser`. Откройте ссылку из терминала в браузере на своём компьютере и нажмите «Разрешить доступ». Браузер не сможет открыть страницу `localhost` — скопируйте адрес из адресной строки и вставьте в терминал. В других агентах подключитесь готовым токеном. | | Ошибка `401` | Токен истёк, отозван или скопирован не полностью. Повторите вход или выпустите новый токен. | | Ошибка `429` и `rate limit exceeded` | Больше 120 запросов в минуту на один ключ. Повторите через минуту. | | Нет инструментов `send_message` и `generate_image` | У токена нет разрешения «Платные запросы к моделям» или агент подключён API-ключом. Выпустите MCP-токен с этим разрешением. | | Ошибка `API key monthly spending limit exceeded` | Исчерпан месячный лимит расходов токена. Выпустите токен с бо́льшим лимитом или дождитесь начала следующего месяца. | | Платный вызов отклонён из-за баланса | На балансе аккаунта не хватает средств. Пополните баланс — ссылку на форму пополнения агент получит через `get_top_up_link`. | | После входа командой пропал личный токен или наоборот | Повторный вход в ту же запись сервера отзывает её прежний токен. Подключите аккаунты разными записями — см. [Личный аккаунт и команда одновременно](#личный-аккаунт-и-команда-одновременно). | | Выписка или данные команды недоступны | Выписка доступна только MCP-токену, а данные команды — только токену, который выпустил на команду её администратор. |