> ## Documentation Index
> Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP-сервер
> Подключение AI-агента к аккаунту через Model Context Protocol: токен в профиле и настройка клиента
MCP (Model Context Protocol) — открытый стандарт, через который агент в вашем редакторе или чате обращается к инструментам платформы: баланс, ключи, организация, история генераций. Всё настраивается в веб-приложении.
**MCP — это не эндпоинт `/api/v1`.** REST API для управления MCP-серверами, токенами и разрешениями не существует. Всё, что связано с MCP, делается в интерфейсе на [speshu.ai/profile](https://speshu.ai/profile), раздел MCP. Из кода, из curl и из SDK этим не управляют.
## Что понадобится
* Аккаунт на [speshu.ai](https://speshu.ai) с пополненным балансом
* Клиент с поддержкой MCP и HTTP-транспорта (Streamable HTTP)
## Настройка
Откройте [speshu.ai/profile](https://speshu.ai/profile) и перейдите в **раздел MCP** в личном кабинете. Нажмите **Создать токен**.
Укажите понятное имя — по нему вы потом поймёте, где этот токен используется. Разрешения выбирайте минимальные: под каждый клиент отдельный токен, а не один на всё.
Токен показывается один раз. Сохраните его в менеджере секретов или переменной окружения, а не в файле проекта.
Укажите клиенту адрес сервера и заголовок авторизации с этим токеном. Конкретная команда зависит от клиента.
Токен даёт агенту доступ к вашему аккаунту в пределах выбранных разрешений. Обращайтесь с ним так же, как с API-ключом: храните в менеджере секретов, не коммитьте в репозиторий, заводите отдельный на каждый клиент и отзывайте при смене.
## Подключение к клиенту
Адрес сервера и способ авторизации вы увидите в том же разделе MCP в личном кабинете — вместе с готовым фрагментом конфигурации для вашего клиента. Не собирайте адрес и заголовки по памяти: раздел в профиле отдаёт актуальные значения.
```bash theme={null} theme={null}
# Claude Code — адрес и заголовок подставьте из раздела MCP в профиле
claude mcp add --transport http speshu-ai https://speshu.ai/api/mcp \
--header "Authorization: Bearer $SPESHU_MCP_TOKEN"
```
```json theme={null} theme={null}
{
"mcpServers": {
"speshu-ai": {
"type": "http",
"url": "https://speshu.ai/api/mcp",
"headers": {
"Authorization": "Bearer $SPESHU_MCP_TOKEN"
}
}
}
}
```
```typescript TypeScript theme={null} theme={null}
// переменная окружения, а не литерал в коде
const config = {
mcpServers: {
"speshu-ai": {
type: "http",
url: "https://speshu.ai/api/mcp",
headers: { Authorization: `Bearer ${process.env.SPESHU_MCP_TOKEN}` },
},
},
};
```
Файл конфигурации добавьте в `.gitignore`, если проект под контролем версий.
## Разрешения
Каждый токен имеет набор разрешений, и они определяют, какие инструменты видит агент. Управление ими — при создании и правке токена в разделе MCP профиля; через API они не задаются и не читаются.
Не давайте агенту права на удаление ключей, организаций и любые необратимые операции, если задача этого не требует. Агент вызывает инструменты по решению модели, а решение может быть ошибочным — ограничение прав здесь единственная реальная страховка.
## Безопасность
* **Относитесь к токену как к API-ключу.** Он даёт доступ к аккаунту и ограничен только лимитами и остатком кошелька.
* **Ограничивайте круг доступа.** Набор инструментов определяется разрешениями токена: для чтения данных хватит пресета с доступом только на чтение.
* **Не передавайте токен агенту, которому не доверяете.** Любой инструмент, доступный агенту, доступен и модели, которая решит его вызвать.
* **Заводите токен на клиента.** Два редактора — два токена. Отзыв одного не роняет остальные.
* **Отзывайте по сроку.** Если в разделе MCP доступна настройка срока действия, задавайте его для временных интеграций.
* **Проверяйте состояние токенов.** Список активных токенов с датами создания и последнего использования виден в разделе MCP профиля.
## Управление токенами
Всё делается в разделе MCP в личном кабинете на [speshu.ai/profile](https://speshu.ai/profile):
* просмотр активных токенов, даты создания и последнего использования;
* отзыв токена — действие необратимое, агент теряет доступ немедленно;
* настройка срока действия, если она доступна при создании.
## Разделение с API-ключами
MCP-токен и API-ключ — разные сущности, и путать их не надо:
| | API-ключ | MCP-токен |
| - | - | - |
| Где используется | Заголовок `Authorization` в запросах к `/api/v1` | Заголовок авторизации при подключении агента |
| Где создаётся | Раздел API-ключей в профиле | Раздел MCP в профиле |
| Что даёт | Выполнение запросов к моделям и медиа | Инструменты управления аккаунтом в рамках разрешений |
| Где описан | [Аутентификация](/docs/authentication) | Эта страница |
Подключение агента к MCP не даёт ему доступа к моделям. Если агенту нужны и генерации, и управление аккаунтом, у него должны быть оба: MCP-токен для инструментов и отдельный API-ключ для вызовов.
## Если не подключается
Проверьте, что токен скопирован целиком, без пробелов и переносов строк, и что он не отозван в разделе MCP профиля. Истёкший токен выглядит для сервера как несуществующий.
Проверьте разрешения токена: у него должен быть доступ к нужной группе инструментов. Если агент подключается, но ничего не видит — чаще всего дело именно в разрешениях, а не в подключении.
Нужен HTTP-транспорт (Streamable HTTP). Клиенты, умеющие только локальные процессы или SSE-транспорт в прежней версии, с этим сервером не заработают.
Раздел [Ошибки](/docs/errors) покрывает коды и форматы. Формат ошибок MCP-инструментов отдельно не документирован: ориентируйтесь на текст, который возвращает инструмент, и на раздел поддержки.
## Что дальше
API-ключи для вызовов к моделям
Подключение редакторов и агентов
Коды и форматы ответов API
Разбор проблем с интеграцией
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.