---
type: how-to
title: Используй сервер MCP
summary: Подключи ИИ-агента к Caputchin через сервер MCP, аутентифицируй его токеном доступа и управляй API управления на естественном языке, с разобранным примером.
---

Сервер MCP Caputchin позволяет ИИ-агенту (Claude, Cursor или любому клиенту [Model Context Protocol](https://modelcontextprotocol.io)) управлять твоим аккаунтом, вызывая тот же [API управления](/docs/automation/management-api), что использует панель. Сервер это тонкая оболочка транспорта и аутентификации: он выставляет один инструмент MCP на каждую операцию управления и проксирует каждый вызов в API. Так что агент может делать всё, что можешь ты, кроме оплаты, на естественном языке.

## Выпусти токен доступа [#mint-an-access-token]

Сервер аутентифицируется токеном доступа из переменной окружения `CAPUTCHIN_TOKEN`. Любой вид работает (смотри [аутентификацию API](/docs/automation/management-api#mint-an-access-token)):

- [персональный токен доступа](/docs/account-management/personal-access-token) для контроля над всем аккаунтом, или
- [токен доступа команды](/docs/troops/tokens), чтобы ограничить агента определёнными командами с наименьшими привилегиями, что является более безопасным умолчанием при передаче доступа автономному агенту.

Скопируй токен при создании; он показывается один раз.

## Два способа подключиться

Есть два транспорта, и они выставляют **те же инструменты**, опирающиеся на тот же API управления. Выбирай по тому, как подключается твой клиент:

| | Локальный (stdio) | Размещённый (HTTP) |
|---|---|---|
| Что это | Пакет `@caputchin/mcp`, запущенный на твоей машине | Удалённый эндпоинт по адресу `api.caputchin.com/mcp` |
| Что нужно клиенту | Породить локальный процесс (stdio) | Подключиться к удалённому серверу MCP (HTTP) |
| Аутентификация | `CAPUTCHIN_TOKEN` в окружении процесса | Заголовок `Authorization: Bearer` на соединении |
| Лучше всего, когда | Локальная разработка, десктоп-клиент, нет входящей сети | Размещённый агент, нет локального процесса для порождения |

### Локальный: npx-сервер (stdio)

Сервер опубликован как `@caputchin/mcp` в npm. Обычно ты не запускаешь его вручную; ты прописываешь его в конфиг своего MCP-клиента, и он порождается через stdio, с токеном в своём окружении:

```json
{
  "mcpServers": {
    "caputchin": {
      "command": "npx",
      "args": ["-y", "@caputchin/mcp"],
      "env": { "CAPUTCHIN_TOKEN": "cpt_pat_..." }
    }
  }
}
```

Чтобы проверить, что он работает, запусти его напрямую; он говорит на MCP через stdio и выходит с ошибкой, если токен отсутствует:

```bash
CAPUTCHIN_TOKEN=cpt_pat_... npx -y @caputchin/mcp
```

### Размещённый: HTTP-эндпоинт

Для клиентов, которые подключаются к удалённому серверу MCP вместо порождения локального, Caputchin размещает тот же сервер по адресу:

```
https://api.caputchin.com/mcp
```

Он аутентифицируется твоим токеном как заголовком `Bearer` на соединении (те же учётные данные, просто переданные по HTTP, а не через окружение):

```json
{
  "mcpServers": {
    "caputchin": {
      "url": "https://api.caputchin.com/mcp",
      "headers": { "Authorization": "Bearer cpt_pat_..." }
    }
  }
}
```

Точная форма конфига зависит от твоего MCP-клиента; важны URL и заголовок `Authorization: Bearer`. Устанавливать нечего, и нет локального процесса; компромисс в том, что токен путешествует к размещённому эндпоинту на каждый запрос, а не остаётся в окружении локального процесса.

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

Каждый инструмент назван `caputchin_<verb>_<noun>` и отображается на одну операцию управления, например `caputchin_list_troops`, `caputchin_create_site`, `caputchin_rotate_site_secret`, `caputchin_add_troop_member`, `caputchin_site_stats`. Агент обнаруживает полный набор и параметры каждого инструмента автоматически через MCP, так что ты описываешь цель, а агент выбирает инструменты.

## Разобранный пример

С сервером, прописанным в твой клиент, ты можешь попросить агента простым языком:

> «Создай ключ сайта под именем shop-frontend в моей команде shop-team, затем включи для него игровые ворота.»

Агент разрешает это в последовательность вызовов инструментов: `caputchin_list_troops`, чтобы найти id команды, `caputchin_create_site` с этим `troop_id`, затем `caputchin_update_site_security`, чтобы потребовать игру. Каждый вызов бьёт в API управления под твоим токеном, и на Apex каждый приземляется в твоём [журнале аудита](/docs/audit-logs/overview), приписанный токену, так что действия агента так же отслеживаемы, как и человека.

Поскольку агент действует с полной досягаемостью твоего токена, предпочитай токен команды с охватом, когда можешь, и отзови его в тот же момент, как задача сделана.

## Полный справочник

Для полного списка инструментов, каждого с однострочным описанием и правом, которое должен держать его токен, смотри [справочник инструментов MCP](/docs/automation/mcp-tools). Инструменты зеркалят API управления один в один, так что [интерактивный справочник API](/docs/api-reference) это авторитетное описание параметров и ответа каждой операции: читай MCP-описание инструмента для сводки, обращённой к агенту, и справочник API для точной схемы.

## См. также

- [Справочник инструментов MCP](/docs/automation/mcp-tools): каждый инструмент, его описание и нужное ему право.
- [Управляй Caputchin через API](/docs/automation/management-api): HTTP API, который вызывает каждый инструмент.
- [Используй Terraform или OpenTofu](/docs/automation/terraform): поверхность infrastructure-as-code.
- [Персональный токен доступа](/docs/account-management/personal-access-token) и [токены команды](/docs/troops/tokens): учётные данные, которые использует сервер.