0.4.11
Поиск по документации… ⌘K
11 · Руководство пользователя

11. MCP-серверы

MCP (Model Context Protocol) — это способ дать AstraCode доступ к внешним системам: Linear, GitHub, Slack, базе данных, custom-сервисам. Каждое подключение — отдельный «MCP-сервер», который добавляет в распоряжение модели свои tools.

Зачем

Без MCP: - Чтобы прочитать тикет из Linear, вы копируете ID, вставляете описание в чат. - Чтобы оставить комментарий — открываете браузер, печатаете. - Чтобы запросить из БД — пишете SQL вручную.

С MCP:

text
You: посмотри тикет LIN-1234, поправь баг, опиши в комментарии что сделал.
AstraCode: (через linear-mcp читает тикет)
AstraCode: (видит описание бага, идёт в код, чинит)
AstraCode: (через linear-mcp оставляет комментарий)

Всё автоматизировано.

Транспорты

MCP-сервер подключается одним из двух транспортов:

  • stdio — MCP-сервер запускается как локальный процесс, AstraCode общается с ним по стандартным потокам ввода/вывода.
  • streamable-http — удалённый сервер, доступный по HTTP. Внутри этого транспорта для стриминга ответов используется SSE (Server-Sent Events), но как самостоятельный транспорт sse не выделяется.

Как добавить MCP-сервер

Через config.toml, не через UI. Откройте ~/.astracode/config.toml и добавьте секцию [mcp_servers.<name>].

Локальный (stdio)

Самый частый случай — MCP-сервер запускается как процесс:

toml
[mcp_servers.linear]
command = "npx"
args = ["-y", "@linear/mcp-server"]
env_vars = ["LINEAR_API_KEY"]
enabled = true
default_tools_approval_mode = "prompt"
  • command + args — что запустить (как в shell).
  • env_vars — какие переменные окружения пробросить (значения берутся из вашей среды).
  • default_tools_approval_mode — режим approval для tools этого сервера.

Удалённый (streamable-http)

Для серверов с публичным API:

toml
[mcp_servers.github_remote]
url = "https://mcp-server.github.com"
bearer_token_env_var = "GITHUB_TOKEN"
enabled = true

После добавления — перезапустите AstraCode (/exit или Ctrl-D, потом astracode). MCP-серверы загружаются при старте.

Проверка

В TUI:

text
/mcp

Вывод — это read-only chat-cell, где по каждому настроенному серверу показаны поля: Status, Auth, Command (для stdio) или URL (для streamable-http), Tools, Resources.

Статусы аутентификации (поле Auth):

  • Unsupported — сервер не требует/не поддерживает OAuth.
  • NotLoggedIn — OAuth поддерживается, но вход не выполнен.
  • BearerToken — аутентификация через bearer-токен (env var).
  • OAuth — выполнен OAuth-вход.

Подробнее:

text
/mcp verbose

Покажет имена всех tools от каждого сервера, OAuth-статус, последние ошибки.

Approval для MCP-tools

Каждый MCP-сервер имеет default_tools_approval_mode:

Режим Что значит
auto AstraCode решает сам по requires_approval флагу tool'а
prompt Каждый вызов спрашивает разрешение
approve Без вопросов (использовать осторожно)

Можно настроить per-tool:

toml
[mcp_servers.github_remote.tools.delete_repo]
approval_mode = "prompt"   # для опасного — всегда спрашивать
toml
[mcp_servers.github_remote.tools.search_code]
approval_mode = "approve"  # для безопасного — без вопросов

OAuth flow

Многие удалённые MCP (GitHub, Notion, Slack) требуют OAuth. OAuth-логин выполняется через CLI, не через slash-команду:

bash
astracode mcp login github

Откроется браузер с OAuth-flow. После подтверждения — токен сохранится:

  • В OS keyring (режим keyring) — самое безопасное.
  • Или в файл ASTRACODE_HOME/.credentials.json (режим file) — если keyring недоступен.
  • Режим auto (по умолчанию) — keyring, если доступен, иначе файл.

Управление режимом хранения:

toml
mcp_oauth_credentials_store = "auto"   # auto | keyring | file

Стереть токен (например, чтобы перелогиниться):

bash
astracode mcp logout github

Что есть из готовых MCP

Список растёт. Популярные:

Сервер Что даёт
@linear/mcp-server Linear: тикеты, проекты, комментарии
@modelcontextprotocol/server-github GitHub: issues, PRs, releases
@modelcontextprotocol/server-filesystem Расширенный доступ к FS (вне sandbox)
@modelcontextprotocol/server-postgres PostgreSQL: запросы
@modelcontextprotocol/server-slack Slack: каналы, сообщения
@modelcontextprotocol/server-google-drive Google Drive
playwright-mcp Браузерная автоматизация

Примеры

База данных

toml
[mcp_servers.db]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
default_tools_approval_mode = "prompt"   # SQL — лучше с approval'ом

В чате:

text
You: сколько пользователей зарегистрировалось за последний месяц?
AstraCode: SELECT COUNT(*) FROM users WHERE created_at > NOW() - INTERVAL '30 days';
[approval] Allow this SQL query? [y/a/p/d/n]
You: y
AstraCode: 1247 пользователей.

GitHub

toml
[mcp_servers.github]
url = "https://api.github.com/mcp"
# токен через OAuth — astracode mcp login github
text
You: посмотри PR #234 в репо acme/backend — что в diff'е?
AstraCode: (через MCP читает PR)
You: оставь комментарий: "LGTM, но проверь edge case с пустым массивом"
AstraCode: (через MCP пишет коммент)

Когда MCP полезен

✓ Регулярная работа с одним сервисом (Linear / Jira / GitHub).
✓ Запросы к БД, которые нужны часто.
✓ Custom-инструменты вашей компании (свой MCP-сервер).
✓ Замена ручных копи-паст из браузера.

Когда MCP избыточен

✗ Разовая задача — проще руками.
✗ Простые скрипты — обычный shell через exec_command.
✗ Чтение/запись файлов — встроенные tools и так умеют.

Безопасность MCP

⚠️ MCP-сервер = отдельный процесс или удалённый сервис. Он: - Получает данные, которые вы передаёте (tickets, code snippets). - Может выполнять действия от вашего имени (создать комментарий, удалить тикет).

Защита: - approval_mode = "prompt" для опасных операций (delete, force, send). - Не подключайте MCP из недоверенных источников — это полный доступ к выполнению tools. - OAuth токены — в keyring (не в файлах). - bearer_token_env_var, а не plaintext в config.

Список tools от сервера

Каждый MCP объявляет свои функции. Например, linear может дать:

  • linear_list_issues
  • linear_get_issue
  • linear_create_issue
  • linear_update_issue
  • linear_add_comment
  • linear_list_projects

В /mcp verbose они все перечислены с описаниями. Модель сама выбирает, какую вызвать.

Per-server enabled = false

Если хотите временно выключить сервер:

toml
[mcp_servers.slack]
enabled = false

Tools от него не появятся в списке доступных модели. Удобно: не нужно стирать конфигурацию.

Per-server required = true

toml
[mcp_servers.linear]
required = true

Если этот сервер не отвечает при старте — AstraCode не запустится. Используйте, только если действительно критично.

Свой MCP-сервер

Если у вашей компании есть внутренний API, и вы хотите дать к нему доступ AstraCode — напишите свой MCP-сервер.

Это библиотека Python / TypeScript, реализующая MCP-протокол (stdio или streamable-http). См. официальную документацию MCP.

Шаги: 1. Написать сервер (обычно ~200 строк кода). 2. Указать его в ~/.astracode/config.toml. 3. Перезапустить AstraCode.

Командная строка

Управление через CLI (вне TUI), подкоманды astracode mcp:

bash
astracode mcp list                   # все сервера (есть --json)
astracode mcp get linear             # показать один сервер (есть --json)
astracode mcp add <name> ...         # добавить сервер в config.toml
astracode mcp remove linear          # удалить запись о сервере
astracode mcp login github           # OAuth-вход для сервера
astracode mcp logout github          # удалить OAuth-токен для сервера

Best practices

✓ Начинайте с одного — Linear или GitHub, поработайте, привыкните.
✓ prompt режим для опасного — delete, force, push.
✓ approve для безопасного — search, list, read.
✓ OAuth через keyring — не файл.
✗ Не подключайте всё подряд — каждый MCP-сервер добавляет tools, тратит токены на discovery.
✗ Не доверяйте сторонним MCP без проверки — они могут запросить что угодно.

ESC