MCP (Model Context Protocol) становится стандартом де-факто для подключения ИИ-агентов к внешним инструментам и данным. Один из самых востребованных сценариев — прямой доступ агента к реляционной базе данных. Без MCP разработчику пришлось бы вручную реализовывать SQL-генерацию, обработку ошибок и управление соединениями внутри промпта или через кастомный API. MCP-сервер берёт эти задачи на себя.
Разберём настройку MCP-сервера для PostgreSQL от установки до проверки tool calling. Материал основан на официальной документации протокола, исходном коде референсного сервера и практическом опыте интеграции с Claude Code.
Что такое MCP-сервер для базы данных и зачем он нужен
MCP-сервер для PostgreSQL — это прослойка, которая преобразует вызовы ИИ-агента в SQL-запросы и возвращает структурированные результаты. В отличие от прямого подключения через библиотеку вроде `psycopg2`, MCP-сервер:
- Предоставляет агенту описанные инструменты (tools), а не сырой SQL. Агент «видит» только те операции, которые разрешены в конфигурации.
- Обрабатывает ошибки соединения и таймауты без участия агента. Если база недоступна, сервер возвращает понятное сообщение, а не крашит агента.
- Управляет пулом соединений — не создаёт новое подключение на каждый запрос.
- Добавляет слой безопасности: можно ограничить доступ на уровне схем, таблиц или типов запросов (только SELECT, без DDL).
Для разработчика это означает: не нужно писать код для каждого SQL-запроса внутри промпта. Агент получает готовые инструменты и вызывает их естественным образом.
Установка и запуск MCP-сервера PostgreSQL
Официальный референсный сервер от Anthropic доступен в репозитории modelcontextprotocol/servers. Для PostgreSQL используется реализация на TypeScript.
Требования
— Node.js 18+
— Доступ к PostgreSQL (локальный или удалённый)
— Учётные данные с правами на чтение (для безопасной конфигурации)
Установка через npm:
npm install -g @modelcontextprotocol/server-postgres
Запуск выполняется с указанием строки подключения:
mcp-server-postgres postgresql://user:password@localhost:5432/dbname
Для продакшен-среды пароль лучше передавать через переменную окружения:
export DATABASE_URL=»postgresql://user:password@host:5432/dbname»
mcp-server-postgres $DATABASE_URL
Сервер запускается по протоколу stdio — это значит, что он общается с агентом через стандартные потоки ввода-вывода. Для HTTP-транспорта потребуется дополнительная обёртка (например, через `mcp-proxy`).
Конфигурация для Claude Code и других агентов
Claude Code поддерживает MCP-серверы через файл конфигурации `~/.claude/mcp.json`. Пример для PostgreSQL:
json
{
«mcpServers»: {
«postgres»: {
«command»: «mcp-server-postgres»,
«args»: [«postgresql://user:password@localhost:5432/dbname»],
«env»: {
«PGPASSWORD»: «password»
}
}
}
}
Если сервер установлен глобально, путь указывать не нужно. В противном случае пропишите полный путь к бинарнику:
json
{
«mcpServers»: {
«postgres»: {
«command»: «npx»,
«args»: [
«-y»,
«@modelcontextprotocol/server-postgres»,
«postgresql://user:password@localhost:5432/dbname»
]
}
}
}
После перезапуска Claude Code агент автоматически обнаружит доступные инструменты. Проверить подключение можно запросом: «Какие таблицы есть в базе данных?».
Доступные инструменты и их возможности
MCP-сервер PostgreSQL предоставляет агенту три основных инструмента:
1. `read_query` — выполнение SELECT-запросов. Агент может читать данные из любых таблиц и представлений, к которым у пользователя есть доступ. Результат возвращается в виде массива объектов JSON.
2. `write_query` — выполнение INSERT, UPDATE, DELETE. Этот инструмент по умолчанию отключён и требует явной активации в конфигурации. Anthropic рекомендует включать его только в изолированных тестовых средах.
3. `create_table` — создание новых таблиц. Аналогично, отключён по умолчанию.
Пример типичного взаимодействия:
Агент получает задачу: «Найди всех пользователей, зарегистрированных в последнюю неделю». Он вызывает `read_query` с SQL:
sql
SELECT id, email, created_at FROM users WHERE created_at > NOW() — INTERVAL ‘7 days’
Сервер выполняет запрос и возвращает результат. Агент форматирует ответ для пользователя.
Важное ограничение: сервер не поддерживает транзакции. Каждый вызов выполняется в отдельном соединении. Для сложных операций с несколькими таблицами это может привести к проблемам консистентности.
Безопасность: что нужно знать до подключения к продакшену
Подключение ИИ-агента к базе данных через MCP — удобно, но требует осмотрительности. Основные риски:
SQL-инъекция через агента. Если агент формирует запрос на основе пользовательского ввода, злоумышленник может попытаться внедрить вредоносный SQL. MCP-сервер не экранирует параметры — он передаёт запрос как есть. Защита: использовать отдельную учётную запись PostgreSQL с минимальными правами.
Чтение чувствительных данных. Агент может запросить все строки из таблицы `users`, включая хеши паролей или персональные данные. Решение: создать представление (view) с ограниченным набором колонок и дать агенту доступ только к нему.
Случайное изменение данных. Если включён `write_query`, агент может意外но удалить или изменить записи. Рекомендация: в продакшене использовать только `read_query`, а запись реализовать через отдельный MCP-сервер с явными проверками.
Пример безопасной конфигурации
sql
— Создаём ограниченного пользователя
CREATE USER mcp_agent WITH PASSWORD ‘secure_password’;
GRANT CONNECT ON DATABASE production_db TO mcp_agent;
GRANT USAGE ON SCHEMA public TO mcp_agent;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_agent;
— Запрещаем DDL
REVOKE CREATE ON SCHEMA public FROM mcp_agent;
Подключение через MCP:
json
{
«mcpServers»: {
«postgres»: {
«command»: «mcp-server-postgres»,
«args»: [«postgresql://mcp_agent:secure_password@localhost:5432/production_db»]
}
}
}
Практический пример: аналитический запрос через агента
Рассмотрим реальный сценарий: у нас есть база данных интернет-магазина с таблицами `orders`, `products`, `customers`. Агент получает задачу: «Покажи топ-5 товаров по выручке за последний месяц».
Без MCP пришлось бы писать SQL вручную, выполнять его через клиент, форматировать результат. С MCP агент делает это сам:
Агент вызывает `read_query` с запросом
sql
SELECT p.name, SUM(o.quantity * p.price) as revenue
FROM orders o
JOIN products p ON o.product_id = p.id
WHERE o.created_at > NOW() — INTERVAL ’30 days’
GROUP BY p.name
ORDER BY revenue DESC
LIMIT 5
Сервер возвращает JSON-массив.
Агент форматирует ответ в читаемый вид с таблицей.
Время выполнения: 2-3 секунды вместо 5-10 минут ручной работы.
Альтернативы и ограничения
MCP-сервер PostgreSQL — не единственный способ подключения базы данных к агенту. Альтернативы:
- Прямой вызов API базы данных через tool calling. Агент вызывает HTTP-эндпоинт, который выполняет SQL. Даёт больше контроля, но требует написания бэкенда.
- Text-to-SQL через промпт. Агент генерирует SQL на основе описания схемы в контексте. Работает для простых запросов, но ненадёжен для сложных JOIN и агрегаций.
- ORM-обёртка. Агент использует ORM-методы через tool calling. Удобно для CRUD, но добавляет накладные расходы.
Ограничения MCP-сервера PostgreSQL
— Нет поддержки prepared statements — каждый запрос парсится заново.
— Нет кэширования результатов — повторные одинаковые запросы выполняются каждый раз.
— Нет стриминга — большие результаты передаются целиком, что может превысить лимит контекста агента.
— Нет поддержки COPY и других bulk-операций.
Что проверить перед использованием
Перед тем как подключать MCP-сервер к реальной базе, выполните несколько проверок:
Проверьте права пользователя. Подключитесь к базе через psql под той же учётной записью и убедитесь, что SELECT работает, а DROP/ALTER — нет.
2. Протестируйте таймауты. Выполните через агента запрос, который выполняется дольше 30 секунд. Сервер должен корректно обработать таймаут и вернуть ошибку.
3. Проверьте экранирование. Попробуйте передать через агента запрос с кавычками и спецсимволами. Убедитесь, что сервер не крашится.
4. Оцените объём данных. Запросите таблицу с 10 000 строк. Проверьте, укладывается ли ответ в лимит контекста агента (обычно 100-200 тысяч токенов).
MCP-сервер для PostgreSQL — практичный инструмент, который сокращает время разработки интеграций между ИИ-агентами и реляционными базами данных. Но, как и любой инструмент с прямым доступом к данным, он требует вдумчивой настройки безопасности и учёта ограничений протокола. Начните с изолированной тестовой базы, протестируйте все сценарии — и только затем подключайте к реальным данным.