MCP Toolbox for Databases

MCP Toolbox for Databases — это MCP-сервер от Google. Он стоит между ИИ-агентом и базой данных и даёт агенту прямой доступ к данным. Написан на Go, распространяется под лицензией Apache 2.0.

Проект раньше назывался genai-toolbox. Имя поменяли, когда добавили поддержку MCP. Если у вас уже есть локальная копия, адрес репозитория обновляется одной командой:

git remote set-url origin https://github.com/googleapis/mcp-toolbox.git

Два режима работы

У проекта два разных сценария применения. Это важно, потому что в них работают разные инструменты и разные требования к безопасности.

Готовые инструменты из коробки. Вы запускаете сервер с флагом --prebuilt=postgres — и получаете набор универсальных инструментов: посмотреть список таблиц, выполнить SQL-запрос. Дальше Gemini CLI, Claude Code, Codex или любой другой MCP-клиент работают с вашей базой без единой строки вашего кода. Это сценарий, когда вы сами, разработчик, изучаете свою базу через агента.

Свой фреймворк для инструментов. Вы описываете инструменты вручную в файле tools.yaml. Это сценарий для продакшена, где агенту нужно дать узкие и безопасные операции, а не полный доступ к базе.

Подключение из коробки

Добавьте блок в конфигурационный файл вашего MCP-клиента — обычно это mcp.json или claude_desktop_config.json:

{
  "mcpServers": {
    "toolbox-postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@toolbox-sdk/server",
        "--prebuilt=postgres",
        "--stdio"
      ]
    }
  }
}

Дальше задайте переменные окружения для подключения. Полный список баз и их инструментов — в справочнике готовых конфигураций.

Через косую черту можно загрузить не весь набор, а только один набор инструментов. Например, --prebuilt=postgres/data загрузит только SQL-инструменты.

Поддерживаемые базы:

Файл конфигурации

Главный способ настроить Toolbox — файл tools.yaml. Внутри описаны несколько типов блоков.

Переменные окружения

Пароли, логины и ключи не нужно писать прямо в файл. Вместо этого используется подстановка:

user: ${USER_NAME}
password: ${PASSWORD}
port: ${DB_PORT:3306}

Значение после двоеточия — это значение по умолчанию, если переменная не задана.

Источники

Блок source описывает, к какой базе подключаться. Почти каждому инструменту нужен какой-то источник:

kind: source
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: ${USER_NAME}
password: ${PASSWORD}

Инструменты

Блок tool описывает действие, которое агент может выполнить. Обязательные поля — тип, источник, текст запроса и описание. Описание важно: именно его модель читает, чтобы понять, когда вызывать инструмент.

kind: tool
name: search-hotels-by-name
type: postgres-sql
source: my-pg-source
description: Search for hotels based on name.
parameters:
  - name: name
    type: string
    description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';

Наборы инструментов, группы и промпты

Блок toolset собирает несколько инструментов вместе, чтобы загружать их одним вызовом. Можно сделать отдельный набор для каждого агента. Блок group делает то же самое, но шире: в него попадают не только инструменты, но и промпты, ресурсы и шаблоны ресурсов.

kind: toolset
name: my_first_toolset
tools:
  - my_first_tool
  - my_second_tool

prompt хранит готовые текстовые заготовки для работы с моделью. resource и resourceTemplate отдают клиенту файлы и текст, которые агент может прочитать: схему базы, файлы логов по шаблону URI.

Параметры инструмента

Параметры задают, что агент должен передать при вызове. Базовые типы — string, integer, float, boolean, array и map.

У параметра есть ограничения, которые проверяются на стороне сервера: allowedValues и excludedValues (поддерживают регулярные выражения), а для чисел — minValue и maxValue. То есть можно заранее сказать «принимай только такие значения», и модель не сможет подсунуть своё.

Параметр обязательный по умолчанию. Сделать его необязательным можно двумя способами, и они работают по-разному. default: "AA" подставит значение, если аргумент не передан. А required: false означает, что значение просто не передастся — в SQL это станет NULL.

Отдельная тонкость: default: null в YAML превращается в пустое значение, которое сервер не отличит от отсутствия поля. Параметр останется обязательным. Чтобы он был необязательным без значения, пишите именно required: false.

Параметры-шаблоны и риск SQL-инъекций

Кроме обычных параметров есть templateParameters. Они подставляются прямо в текст запроса — без кавычек и до выполнения. Ими можно подставлять имена таблиц и колонок, но именно поэтому они опасны: агент может подсунуть вредоносный SQL.

Документация прямо предупреждает: такие параметры склонны к SQL-инъекциям, и обычные параметры предпочтительнее и по скорости, и по безопасности. Если шаблонные параметры всё же нужны, ограничивайте вход через allowedValues, а для чисел — через minValue и maxValue.

Секретные параметры

Отдельная механика — secure: true. Такой параметр ИИ-агент не должен видеть и не должен контролировать. Это может быть идентификатор клиента или токен сессии.

Как это работает:

• В манифесте MCP параметр попадает в secureInputSchema, а не в inputSchema. SDK автоматически убирают его из сигнатур инструментов. Модель его не видит и не придумывает.
• Приложение подставляет значение в коде. Оно уходит по сети отдельным полем secureArguments в запросе tools/call и не смешивается с обычными аргументами.
• Если агент попытается передать секретный параметр обычным способом, сервер вернёт ошибку. Значение от модели не примет.

Секретные параметры всегда обязательные. У них не может быть default, authServices или required: false. Нужна версия протокола 2026-07-28 и расширение com.google.cloud/toolbox.v1.

Аутентификация и авторизация

Параметр с полем authServices заполняется автоматически из ID-токена, который приходит в заголовках запроса. Указываете сервис проверки токена и название поля внутри токена:

parameters:
  - name: user_id
    type: string
    description: Auto-populated from Google login
    authServices:
      - name: my-google-auth
        field: sub

Агент не передаёт user_id вообще. Он подставляется сервером из токена.

На уровне инструмента доступ закрывается полем authRequired — это список сервисов проверки, все должны пройти. А на уровне MCP есть scopesRequired для точных прав по OAuth-скоупам.

Есть и подсказки для клиента — аннотации инструмента: readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Они ничего не запрещают, но помогают MCP-клиенту показать пользователю подтверждение. Значения по умолчанию Toolbox расставляет сам по типу операции.

Три слоя защиты от записи

Для режима с готовыми инструментами это важный момент: такие инструменты дают агенту сырой SQL, и аннотации здесь не защита. Документация рекомендует три уровня.

Первый — параметризованные запросы в своих инструментах вместо execute_sql. Знаки $1 для Postgres и ? для MySQL передают значения отдельно от текста запроса, поэтому структуру запроса изменить нельзя.

Второй — режим только для чтения. На уровне источника ставится readOnly: true. Это граница на уровне протокола базы: никакая конфигурация инструмента её не обойдёт.

Третий — права учётной записи. Лучший способ запретить запись — вообще не дать её учётке. Заведите отдельного пользователя, которому разрешено только SELECT на нужные схемы, и передайте пароль именно ему. Тогда даже неверно настроенный инструмент ничего не испортит.

Подробнее — в гайде по инструментам только для чтения.

Установка и запуск

Четыре способа поставить сервер.

Бинарный файл — скачивается со страницы релизов. Дальше просто ./toolbox --config tools.yaml.

Контейнер:

export VERSION=1.13.1
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION

Homebrew:

brew install mcp-toolbox

Из исходников — нужен Go:

go install github.com/googleapis/mcp-toolbox@v1.13.1

Самый быстрый способ для первого знакомства — npx @toolbox-sdk/server --config tools.yaml. Документация честно предупреждает: этот способ удобный, но не самый быстрый. Для продакшена ставьте бинарный файл или контейнер.

Дальше сервер слушает HTTP на порту 5000. Клиент подключается к адресу http://127.0.0.1:5000/mcp, а конкретный набор инструментов — к http://127.0.0.1:5000/mcp/{toolset_name}.

По умолчанию Toolbox перечитывает конфигурацию на лету. Отключается флагом --disable-reload.

SDK для своих приложений

Готовые инструменты нужны для изучения базы. А для агента, который работает в вашем приложении, инструменты подключают через SDK. Клиент загружает их и отдаёт фреймворку.

Есть SDK для Python, JavaScript/TypeScript и Go. У каждого есть базовый вариант и варианты под конкретные фреймворки: LangChain и LangGraph, LlamaIndex, Genkit, ADK, OpenAI Go, Gemini CLI.

from toolbox_core import ToolboxClient

# update the url to point to your server
async with ToolboxClient("http://127.0.0.1:5000") as client:
    # these tools can be passed to your application!
    tools = await client.load_toolset("toolset_name")

Интеграция занимает меньше десяти строк — это и есть главный аргумент в пользу Toolbox.

Дополнительно

Toolbox UI. Флаг --ui открывает интерфейс, где можно вручную проверить инструменты и наборы. Полезно при отладке конфигурации.

Телеметрия. Сервер отдаёт метрики и трассы в OpenTelemetry. Адрес любого OTLP-совместимого приёмника задаётся флагом --telemetry-otlp.

Генерация Agent Skill. Команда skills-generate превращает набор инструментов в Agent Skill по спецификации agentskills.io. Получается переносимый пакет, который можно ставить в Gemini CLI. В самом репозитории уже есть готовые скилы в каталоге skills/.

Версии. Проект следует SemVer. Публичный API — это сервер (CLI, манифесты конфигурации, готовые наборы) плюс клиентские SDK.

MCP Apps. Через расширение io.modelcontextprotocol/ui обычный ресурс с флагом ui: true начинает работать как веб-приложение, и инструмент можно привязать к такому интерфейсу.

Кому это нужно

Главный сценарий — команда, у которой есть и агенты, и настоящая база, и требования к безопасности. Toolbox решает обе задачи: даёт быстрый доступ из коробки для разработчика и узкие безопасные инструменты для продакшена. Родной Go, Apache 2.0, MCP насквозь.

Что стоит проверить перед боевым использованием: права учётной записи в базе и то, какие инструменты вы реально открываете агенту.

Документация — mcp-toolbox.dev. Разработка — CONTRIBUTING и DEVELOPER. Лицензия — Apache 2.0.