MCP: подключение БД и локальных API к ИИ-агенту

Зачем MCP важен для продвинутых пользователей

До MCP каждая IDE придумывала свой формат плагинов. Model Context Protocol от Anthropic стандартизирует, как AI-клиент обнаруживает возможности: список инструментов → вызов инструмента с JSON-аргументами → возврат структурированных результатов. Это значит, что один read-only Postgres-сервер может обслуживать Claude Desktop, Cursor и другие MCP-хосты без переписывания интеграций.

Опытным разработчикам это важно, потому что:

• Базы данных становятся запрашиваемым контекстом без вставки дампов схемы в каждый чат
• Внутренние API (биллинг, feature flags, статус деплоя) выступают как типизированные инструменты вместо хрупкого copy-paste
• IDE + agent stacks делят один и тот же toolchain, когда вы также запускаете альтернативы Claude Code или OpenClaw на удалённом Mac

Официальные материалы: спецификация Model Context Protocol и документация Anthropic по MCP.

Архитектура MCP за 60 секунд

┌─────────────┐     JSON-RPC      ┌──────────────────┐
│  MCP Host   │ ◄──────────────► │  MCP Server       │
│ (Claude /   │   tools/resources │ (your custom code)│
│  Cursor)    │                   │  → DB / API / CLI │
└─────────────┘                   └──────────────────┘

Правило глубины: один сервер на границу доверия. Не помещайте production write-доступ и экспериментальные shell-инструменты в один бинарник сервера — разделяйте процессы, чтобы можно было отозвать один блок конфига, не трогая другой.

Матрица выбора транспорта

Паттерн 1 — MCP-сервер для базы данных

Цель: позволить модели выполнять read-only SQL (или предопределённые запросы) к PostgreSQL, MySQL или SQLite.

Ограничения проектирования:

• Экспонируйте именованные инструменты (query_sales_summary, list_tables) вместо произвольного raw SQL, когда это возможно
• Обеспечьте лимиты строк (например, max 200 строк) и таймауты запросов (например, 5 с)
• Никогда не передавайте connection strings через модель — загружайте из DATABASE_URL в окружении сервера

Пример поверхности инструментов:

Используйте read-only роль БД: GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_reader;

Паттерн 2 — Шлюз локального REST API

Цель: обернуть существующие HTTP-эндпоинты как MCP-инструменты, чтобы Claude никогда не держал долгоживущие API-ключи в окне чата.

Паттерн шлюза:

Claude → MCP tool "deploy_status" → your server → GET https://internal/api/v1/deployments

Советы по реализации:

• Сопоставьте каждый инструмент с одним HTTP-методом + шаблоном пути
• Валидируйте входы схемой (Zod, Pydantic) перед вызовом fetch
• Возвращайте усечённый JSON (первые 8 КБ) плюс флаг truncated: true, когда ответы огромны
• Логируйте correlation ID на стороне сервера; не эхо секретов в результатах инструментов

Это хорошо сочетается с мульти-агентной оркестрацией, когда воркеры OpenClaw вызывают те же внутренние API через MCP вместо ad-hoc curl.

Паттерн 3 — Мост IDE и репозитория

Cursor и Claude Code уже поставляются с поддержкой MCP-клиента. Ваш кастомный сервер может экспонировать:

• Repo tools: git_diff_summary, run_linter (sandboxed)
• Doc resources: file:// или resources/read для AGENTS.md, OpenAPI-спеков
• ECC / plugin hooks: после установки ECC добавьте MCP-инструменты, оборачивающие ecc-скрипты вашей команды

Держите IDE-мосты stdio-local, если вся команда не делит один удалённый dev box.

Runbook из восьми шагов

Шаг 1 — Установите официальный SDK

Node (рекомендуется для большинства хостов):

mkdir mcp-company-gateway && cd mcp-company-gateway
npm init -y
npm install @modelcontextprotocol/sdk zod pg

Python-альтернатива: pip install mcp (см. MCP Python SDK).

Шаг 2 — Создайте минимальный сервер

Создайте src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "company-gateway", version: "1.0.0" });

server.tool("ping", {}, async () => ({
  content: [{ type: "text", text: "pong" }],
}));

const transport = new StdioServerTransport();
await server.connect(transport);

Запустите один раз: npx tsx src/index.ts — процесс должен блокироваться в ожидании stdio (отсутствие вывода — норма).

Шаг 3 — Добавьте read-only Postgres-инструмент

export DATABASE_URL="postgresql://mcp_reader:****@127.0.0.1:5432/app"

Зарегистрируйте postgres_query_readonly с Zod-валидированным SQL, который должен начинаться с SELECT (отклоняйте ; и DDL-ключевые слова на стороне сервера).

Шаг 4 — Зарегистрируйте в Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "company-gateway": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/mcp-company-gateway/src/index.ts"],
      "env": { "DATABASE_URL": "postgresql://mcp_reader@127.0.0.1:5432/app" }
    }
  }
}

Перезапустите Claude Desktop. В новом чате убедитесь, что иконка hammer/tools показывает ping и postgres_query_readonly.

Шаг 5 — Зарегистрируйте в Cursor

Проектный или глобальный .cursor/mcp.json:

{
  "mcpServers": {
    "company-gateway": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/mcp-company-gateway/src/index.ts"]
    }
  }
}

Перезагрузите окно Cursor. Протестируйте тот же инструмент ping из панели агента.

Шаг 6 — Экспонируйте SSE для удалённого хоста (опционально)

Когда MCP-сервер работает на удалённом Mac (team bastion или арендованный M4):

# Example: SDK HTTP/SSE transport on port 8787 — bind localhost only unless behind VPN
node dist/sse-server.js --port 8787 --host 127.0.0.1

Укажите в конфиге хоста url: "http://127.0.0.1:8787/sse" через SSH-туннель:

ssh -L 8787:127.0.0.1:8787 user@remote-mac

Никогда не экспонируйте неаутентифицированный MCP SSE-порт в публичный интернет.

Шаг 7 — Секреты и sandboxing

Шаг 8 — Проверьте через MCP Inspector

npx @modelcontextprotocol/inspector npx tsx src/index.ts

Вызовите tools/list и tools/call вручную, прежде чем доверять UI хоста. Логируйте каждый вызов инструмента с timestamp + OS user (не содержимое чата) для аудита.

Чеклист безопасности и sandbox

• Read-only роли БД для analytics-инструментов; используйте второй сервер с write-инструментами только на dev-машинах
• Валидация входов на каждом инструменте; отклоняйте вложенные объекты больше 32 КБ
• Network egress allowlist из процесса сервера (iptables или macOS firewall) при обёртке внутренних API
• OAuth для SaaS — реализуйте refresh токенов внутри сервера; экспонируйте модели только opaque tool_ok

Когда запускать MCP на выделенном Mac

Сон ноутбука убивает stdio-серверы. Команды, которым нужны общие MCP-каталоги (одни и те же Postgres-инструменты для 8 инженеров), часто запускают сервер на постоянно включённом Apple Silicon Mac — локальном на столе или небольшом удалённом узле — и достигают его через SSH-туннель или VPN.

Это инфраструктурный выбор, а не требование MCP. M4 с 16 ГБ комфортно держит 3–5 лёгких MCP-серверных процессов (~80–150 МБ каждый) плюс Node tooling; добавьте RAM, если на том же box также работают Docker-базы. Сравните варианты хостинга на странице цен или обратитесь за помощью через поддержку.

Troubleshooting

Ошибка: Connection closed сразу после spawn

Паттерн: лог Claude Desktop показывает exit code 1 сервера.
Исправление: запустите те же command + args в Terminal; исправьте отсутствующий tsx, неверный абсолютный путь или исключение при старте. MCP-хосты не показывают stderr в UI.

Ошибка: Tool not found / пустой список инструментов

Паттерн: опечатка в JSON конфига или хост не перезагрузился.
Исправление: валидируйте JSON через jq . claude_desktop_config.json; полностью выйдите и откройте приложение хоста заново (не просто закройте окно).

Ошибка: SSE 404 или CORS failures

Паттерн: неверный путь удалённого URL (/sse vs /mcp).
Исправление: совпадите путь с документацией HTTP-транспорта вашего SDK; туннелируйте через ssh -L и используйте 127.0.0.1 в конфиге.

Рекомендуемый путь

Если X → Y: если данные живут на другой машине, разместите MCP-сервер рядом с данными и туннелируйте к хосту — не давайте Claude сырой database port в публичный интернет.

FAQ

В чём разница между MCP и плагинами ChatGPT?

MCP — открытый, независимый от хоста JSON-RPC-протокол с SDK на нескольких языках. Плагины были привязаны к платформе. MCP-серверы работают как локальные или удалённые процессы под вашим контролем; хост только запускает или подключается к ним.

Можно ли подключить MySQL или SQLite так же, как PostgreSQL?

Да. Меняется реализация сервера (драйвер + SQL-диалект); MCP-интерфейс (list_tools, call_tool) остаётся идентичным. Используйте read-only подключения и диалект-специфичные ограничения (SELECT only).

Поддерживает ли Claude Code кастомные MCP-серверы?

По состоянию на 2026 год Claude Code и Cursor поддерживают конфигурацию MCP-клиента, аналогичную Claude Desktop. Пути различаются по продуктам — проверьте актуальную документацию Anthropic и Cursor для расположения mcpServers. Написанный вами серверный код переиспользуется между хостами.

Сколько инструментов должен экспонировать один сервер?

Держите менее ~20 инструментов на сервер для надёжной маршрутизации модели. При росте каталога разделяйте на billing-gateway, data-gateway, ops-gateway — каждый появится отдельным блоком в конфиге хоста.

Безопасно ли экспонировать write-инструменты (DELETE, deploy)?

Только на non-production серверах с явным подтверждением человеком. В общих конфигах предпочитайте read-инструменты; write-операции — за вторым MCP-сервером, который включают только senior-разработчики в личном конфиге.