11. MCP-серверы — AstraCode — Руководство пользователя

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-сервер

Через 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 этого сервера.

Удалённый (HTTP)

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

toml

[mcp_servers.github_remote]
url = "https://mcp-server.github.com"   # URL иллюстративный — подставьте реальный адрес вашего MCP-сервера
bearer_token_env_var = "GITHUB_TOKEN"
enabled = true

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

Проверка

В TUI команда /mcp принимает только один аргумент — verbose:

text

/mcp verbose

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

text

MCP servers
  ✓ linear        — connected · 8 tools
  ✓ github        — connected · 12 tools
  ✗ slack         — not authenticated (войдите: astracode mcp login slack)
  ✗ jira          — connection failed

OAuth-вход выполняется из командной строки (astracode mcp login <server>), а не из TUI — см. раздел OAuth flow ниже.

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. Вход выполняется из командной строки:

bash

astracode mcp login github

Откроется браузер с OAuth-flow. После подтверждения — токен сохранится: - В OS keyring (по умолчанию) — самое безопасное. - Или в файл (~/.astracode/mcp_oauth/) — если keyring недоступен.

Управление:

toml

mcp_oauth_credentials_store = "keyring"   # keyring | file | auto

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

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`	Браузер-автоматизация (альтернатива встроенному скиллу)

Полный реестр — официальный MCP servers repo.

Примеры использования

Linear

toml

[mcp_servers.linear]
command = "npx"
args = ["-y", "@linear/mcp-server"]
env_vars = ["LINEAR_API_KEY"]

В чате:

text

You: возьми тикет LIN-1234 из проекта Backend, посмотри что там, начни работу
AstraCode: (через MCP читает тикет)
AstraCode: Тикет «Fix race condition в auth/session.rs»...
AstraCode: ... я начинаю с анализа src/auth/session.rs

PostgreSQL

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';
Разрешить выполнение?
  Да, продолжить                                    (y)
  Да, и больше не спрашивать для таких команд       (p)
  Да, и разрешить на эту сессию                      (a)
  Нет, и сказать AstraCode, что сделать иначе       (esc)
You: y
AstraCode: 1247 пользователей.

GitHub

toml

[mcp_servers.github]
url = "https://api.github.com/mcp"   # URL иллюстративный — укажите реальный адрес 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 или HTTP). См. официальную документацию MCP.

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

В техдоке — MCP (dev-вики) — детали протокола.

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

Управление через CLI (вне TUI):

bash

astracode mcp list                   # все сервера
astracode mcp get linear             # показать конфигурацию одного сервера
astracode mcp add <name> ...         # добавить сервер в config.toml
astracode mcp remove linear          # удалить сервер из config.toml
astracode mcp login github           # OAuth-вход
astracode mcp logout github          # выход / стереть токен

Best practices

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

Зачем

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

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

Удалённый (HTTP)

Проверка

Approval для MCP-tools

OAuth flow

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

Примеры использования

Linear

PostgreSQL

GitHub

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

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

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

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

Per-server enabled = false

Per-server required = true

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

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

Best practices

Per-server `enabled = false`

Per-server `required = true`