Практика: GitHub, базы данных и веб-API через MCP

В предыдущих статьях мы разобрали архитектуру MCP и научились строить собственные серверы. Теперь — конкретные интеграции, которые реально используются в работе: официальный GitHub MCP Server, PostgreSQL и паттерны для произвольных REST API. И вместе с ними — разбор подводных камней, которые в README обычно не попадают.

GitHub MCP Server: официальная интеграция

GitHub выпустил официальный MCP-сервер (github/github-mcp-server), который покрывает большую часть GitHub API: репозитории, ветки, коммиты, issues, pull requests, GitHub Actions, Dependabot-алерты, code search. Всего более 51 инструмента, организованных в 20+ функциональных категорий.

Два способа подключения — удалённый и локальный.

Удалённый сервер работает через streamable HTTP на инфраструктуре GitHub без локального процесса:

claude mcp add github \
  --transport http \
  --header "Authorization: Bearer ${GITHUB_TOKEN}" \
  https://api.githubcopilot.com/mcp/

GitHub-токен можно выпустить с минимальными скоупами — например, только repo:read для чтения. Рекомендуется именно такой: principle of least privilege работает и здесь.

Локальный запуск через Docker даёт больше контроля над сетевым доступом:

claude mcp add github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN="${GITHUB_TOKEN}" \
  -- docker run -i --rm \
     -e GITHUB_PERSONAL_ACCESS_TOKEN \
     ghcr.io/github/github-mcp-server

После подключения Claude видит инструменты вроде get_pull_request, create_issue, search_code, list_workflow_runs. Типичный сценарий: агент анализирует упавший CI-запуск — читает логи через get_workflow_run_logs, смотрит diff через get_pull_request_files, находит причину и оставляет ревью через create_pull_request_review.

Важный нюанс для тех, кто уже использует claude-code-action в GitHub Actions (обёртка над Agent SDK, разобранная в GitHub Actions и автоматический code review): GitHub MCP Server — это дополнение, а не замена. Actions-обёртка запускает агента в CI по триггеру @claude; MCP-сервер даёт этому агенту инструменты для работы с GitHub API внутри сессии.

Проверь себя

Представьте: вы хотите, чтобы агент в CI автоматически ревьюил PR при упоминании @claude. Какой из инструментов за это отвечает — GitHub MCP Server или claude-code-action? А зачем тогда нужен второй?

PostgreSQL: выбор сервера и безопасность

Оригинальный @modelcontextprotocol/server-postgres от Anthropic в 2025 году был депрекирован и заархивирован. Актуальная альтернатива — Postgres MCP Pro от Crystal DBA:

# Установка через pip
pip install postgres-mcp

# или изолированно через uv (предпочтительно)
uv tool install postgres-mcp

Подключение к Claude Code:

claude mcp add postgres \
  -e DATABASE_URI="postgresql://analyst:secret@localhost:5432/mydb" \
  -- uvx postgres-mcp --access-mode=restricted

Флаг --access-mode=restricted ограничивает Claude только SELECT-запросами — никаких INSERT, UPDATE, DELETE. Агентные ошибки (неверный WHERE, случайный DROP) в продакшн-базе исправить куда сложнее, чем в тестовой. Кроме обычных запросов, сервер умеет делать EXPLAIN-анализ планов выполнения, давать рекомендации по индексам и мониторить pg_stat_activity — удобно для задач из раздела Данные, SQL и аналитика.

Три правила безопасности, которые нарушают почти все:

1. Отдельная роль с минимальными правами. Никогда не давай Claude роль суперпользователя или владельца БД:

CREATE ROLE claude_analyst WITH LOGIN PASSWORD 'strong_password';
GRANT CONNECT ON DATABASE mydb TO claude_analyst;
GRANT USAGE ON SCHEMA public TO claude_analyst;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_analyst;

-- Для таблиц, которые появятся в будущем:
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO claude_analyst;

2. Credentials через переменные окружения, не в .mcp.json. Файл .mcp.json коммитится в git — строка подключения с паролем там равна утечке для всей команды:

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "${POSTGRES_URI}"
      }
    }
  }
}

${POSTGRES_URI} — переменная окружения, которую каждый разработчик выставляет локально: через .env, 1Password CLI, direnv или любой другой способ, принятый в команде. Конфиг коммитится безопасно, секрет остаётся у каждого своим.

3. Сетевой доступ по минимуму. Если база в облаке — Tailscale, VPN или SSH-туннель надёжнее открытого порта с IP-allowlist. Открытый порт — это постоянная поверхность атаки; туннель появляется только когда нужен.

Проверь себя

Почему строку подключения к базе (`postgresql://user:pass@host/db`) нельзя писать прямо в `.mcp.json` и коммитить в git?

Произвольные веб-API: три пути

Когда нет готового MCP-сервера, выбирай из трёх вариантов — от простого к мощному.

Путь 1: Bash-инструменты напрямую. Для публичных API без сложной авторизации Claude Code уже умеет делать curl-запросы через встроенный Bash-инструмент — никакого MCP не нужно:

curl -H "Authorization: Bearer $API_KEY" \
     "https://api.example.com/v1/data?limit=10"

Ограничение: Claude не знает схему API, нет типизации параметров, нет автодополнения в промпте. Подходит для разовых задач или быстрого прототипа.

Путь 2: Собственный MCP-сервер-обёртка. Если API используется регулярно — обернуть его в FastMCP, как мы разбирали в Создание собственного MCP-сервера. Сервер инкапсулирует авторизацию, трансформирует ответы, фильтрует чувствительные поля. Claude видит чистые инструменты с понятными именами и хорошими описаниями.

Путь 3: Puppeteer MCP. Для сервисов без API — корпоративных порталов, старых SPA, форм — MCP-сервер на базе Puppeteer даёт Claude управление браузером: клики, заполнение форм, скрейпинг. Серьёзный инструмент: требует sandbox и чёткой политики разрешений, чтобы агент не натворил лишнего.

flowchart LR
    CC["Claude Code"]

    CC -->|"Путь 1\nBash + curl"| P1["Публичный API\n(разовые задачи)"]
    CC -->|"Путь 2\nMCP-обёртка"| MCP["FastMCP-сервер"]
    CC -->|"Путь 3\nPuppeteer MCP"| BR["Браузер"]

    MCP -->|"auth, transform,\nфильтрация"| API["Корпоративный API\n/ внутренняя БД"]
    BR -->|"клики, формы,\nскрейпинг"| WEB["Веб-портал\nбез REST API"]

Три пути интеграции Claude Code с произвольными веб-сервисами — от простого к сложному

Типичные подводные камни

Большие результаты засоряют контекст. SELECT * FROM events на таблице с миллионом строк — это не запрос, это пожар в контекстном окне. Двойная защита: на уровне роли ограничить доступ к тяжёлым таблицам, а в CLAUDE.md явно прописать: «всегда добавляй LIMIT, используй агрегаты вместо сырых данных». Claude Code следует инструкциям из CLAUDE.md стабильно — это конфигурация, не пожелание.

Токены и пароли в конфиге. .mcp.json коммитится, settings.local.json — нет (он в .gitignore по умолчанию). Локальные секреты — в settings.local.json или переменных окружения. Командные — через Vault, AWS Secrets Manager или Doppler с инъекцией при старте процесса.

Слишком широкие инструменты. Один инструмент run_query(sql: str) без ограничений — антипаттерн. Claude не знает, что допустимо, а что нет. Явные, узкоспециализированные инструменты (search_orders, get_customer_by_id, update_order_status) дают модели предсказуемый контракт и снижают вероятность нежелательных побочных эффектов.

Смешивание скоупов. Сервер с широкими правами в project-скоупе (.mcp.json) автоматически становится доступен всем, кто склонирует репозиторий. Привилегированные серверы — в user-скоуп (~/.claude/), не в проект. Разграничение скоупов подробно разобрано в Подключение MCP-серверов в Claude Code.

Нет защиты от цикличных вызовов. Агент может вызывать API-endpoint в цикле — например, перебирать 500 пользователей по одному. Реализуйте rate limiting на уровне сервера или делайте инструменты с явным параметром limit и поддержкой пагинации.

Быстрое повторение

Какой выбор делаешь между curl в Bash, собственным MCP-сервером и Puppeteer MCP, если для API нет готового сервера?

Быстрое повторение

Почему при работе Claude с PostgreSQL нужна отдельная роль с минимальными правами вместо суперпользователя?

Быстрое повторение

Когда нужно выбрать локальный запуск GitHub MCP через Docker вместо удалённого сервера на инфраструктуре GitHub?