`Stdio` транспорт для SQL MCP Server

Это важно

Сервер протокола контекста модели SQL (MCP) доступен в Data API Builder версии 1.7 и выше.

SQL MCP Server поддерживает два транспорта: потоковую передачу HTTP для размещенных и облачных сценариев, а также stdio для локальной разработки и прямой интеграции агента. В этой статье рассматривается stdio транспорт.

В stdio режиме построитель данных (DAB) взаимодействует с клиентом MCP полностью через стандартный ввод/вывод (stdin/stdout). Http-сервер или сетевой порт не запущен. Клиент MCP запускает DAB как дочерний процесс и передает сообщения обратно и вперед с помощью протокола контекста модели (MCP).

Когда следует использовать `stdio` транспорт

Сценарий	Рекомендуемый транспорт
Локальная разработка на рабочей станции разработчика	`stdio`
VS Code с GitHub Copilot (режим агента)	`stdio`
Конвейеры CI/CD или автоматизация с использованием скриптов агентами	`stdio`
Облачное размещение (приложения-контейнеры, служба приложений)	HTTP
Агент AI Foundry с удаленной конечной точкой MCP	HTTP
Команды агентов, совместно использующие одну конечную точку	HTTP

Выберите stdio , когда требуется самая простая локальная настройка без открытых портов. Выберите HTTP, когда сервер MCP должен быть доступен в сети.

Необходимые условия

Интерфейс командной строки построителя данных (версия 1.7 или новее)
Существующий dab-config.json с включенной функцией MCP (см. Требуемая конфигурация)
Клиент, совместимый с MCP (VS Code с GitHub Copilot, Claude Desktop или настраиваемым агентом)

Требуемая конфигурация

Перед использованием stdio транспорта включите MCP в dab-config.json:

"runtime": {
  "mcp": {
    "enabled": true,
    "path": "/mcp",
    "dml-tools": {
      "describe-entities": true,
      "create-record": true,
      "read-records": true,
      "update-record": true,
      "delete-record": true,
      "execute-entity": true,
      "aggregate-records": true
    }
  }
}

Поле path используется только для транспорта HTTP и игнорируется в stdio режиме. Блок dml-tools определяет, какие операции обработки данных доступны в качестве средств MCP.

Это важно

Если "mcp": { "enabled": false } или mcp блок отсутствует, DAB не удается запустить в stdio режиме.

Запуск в режиме `stdio`

Используйте флаг на --mcp-stdiodab start:

dab start --mcp-stdio --config ./dab-config.json

Чтобы запуститься под определенной ролью разрешений, выполните следующие действия:

dab start --mcp-stdio role:authenticated --config ./dab-config.json

Аргумент role:<name> позиционный и должен немедленно следовать --mcp-stdio. Если его не указать, роль по умолчанию будет anonymous. Имя роли должно соответствовать роли, определенной в permissions разделе по крайней мере одной сущности в конфигурации.

Как работает режим `stdio`

Когда обнаруживается --mcp-stdio, DAB вносит во внутреннее состояние следующие изменения:

Кодировка UTF-8 (без метки порядка байтов)

Входные и выходные данные консоли вынуждены использовать UTF-8 без метки порядка байтов (BOM). Этот параметр UTF-8 необходим для чистого JSON-over-stdio взаимодействия, так как многие клиенты MCP отклоняют префиксированные потоки BOM.

Проверка подлинности симулятора

Аутентификатор принудительно устанавливается в режим симулятора, независимо от указаний в файле конфигурации. Этот режим моделирования позволяет применять указанную роль непосредственно без реального JSON-токена (JWT) или провайдера удостоверений. Поставщик симулятора предназначен для сценариев разработки и не должен использоваться для защиты рабочих конечных точек HTTP, но это правильно для локальных stdio сеансов.

Следующие значения применяются в памяти и переопределяют конфигурацию во время сеанса:

Ключ	Ценность
`MCP:StdioMode`	`"true"`
`MCP:Role`	`"<role-name>"` или `"anonymous"`
`Runtime:Host:Authentication:Provider`	`"Simulator"`

Нет прослушивателя HTTP

Хост ASP.NET Core запускается, и все службы регистрируются, но DAB вызывает stdio.RunAsync() вместо host.Run(). Порт TCP не привязан. Все сообщения протокола MCP передаются через stdin/stdout.

Доступные средства MCP

Следующие инструменты доступны в stdio режиме, в зависимости от вашей dml-tools конфигурации и разрешений сущности:

инструмент	Описание
`describe_entities`	Список доступных сущностей и их полей и разрешений
`create_record`	Вставляет новую запись (только таблицы)
`read_records`	Считывает записи из сущности
`update_record`	Обновляет существующую запись
`delete_record`	Удаляет существующую запись (таблицы и представления)
`execute_entity`	Выполняет хранимую процедуру
`aggregate_records`	Выполняет агрегирование запросов к таблицам и представлениям

Пользовательские средства MCP, поддерживаемые хранимыми процедурами, также регистрируются при использовании --mcp-stdio.

Настройка клиента MCP для `stdio`

Клиенты MCP, которые поддерживают транспортировку stdio, запускают DAB как подпроцесс и передают данные по каналам stdin/stdout. Синтаксис конфигурации клиента зависит от клиента.

VS Code (`mcp.json`)

{
  "servers": {
    "sql-mcp-server": {
      "type": "stdio",
      "command": "dab",
      "args": [
        "start",
        "--mcp-stdio", "role:anonymous",
        "--config", "{path}/dab-config.json",
        "--LogLevel", "error"
      ]
    }
  }
}

Сохраните этот файл в .vscode/mcp.json папке проекта. VS Code автоматически обнаруживает конфигурацию и отображает сервер в MCP: список серверов. Так как клиент управляет жизненным циклом процесса, вам не нужно выполнять dab start отдельно в терминале.

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "sql-mcp-server": {
      "type": "stdio",
      "command": "dab",
      "args": [
        "start",
        "--mcp-stdio", "role:anonymous",
        "--config", "{path}/dab-config.json",
        "--LogLevel", "error"
      ]
    }
  }
}

Совмещение с другими `dab start` параметрами

--mcp-stdio совместим со всеми другими dab start параметрами:

Опция	Поведение с помощью `--mcp-stdio`
`--config`	Использует указанный файл конфигурации (аналогично режиму HTTP)
`--LogLevel`	Применяет указанный уровень журнала (`error`рекомендуется для `stdio`)

dab start \
  --mcp-stdio role:api-reader \
  --config ./dab-config.json \
  --LogLevel Error

Режим устранения неполадок `stdio`

`Failed to start the engine in MCP stdio mode`

DAB не удалось запустить. Проверьте следующие моменты:

Файл конфигурации действителен: выполните команду dab validate --config <path>
Строка подключения к вашей базе данных правильная и доступная.
MCP включен в конфигурации: "mcp": { "enabled": true }

Разрешение на вызовы средства MCP запрещено

Роль, указанная в role:<name>, не имеет необходимых разрешений для сущности и операции. permissions Проверьте раздел соответствующей сущности в конфигурации.

Средства MCP не перечислены

dml-tools Либо задано false глобально, либо сущность имеет "dml-tools": false свои mcp параметры. Кроме того, убедитесь, что mcp.enabled является true.

Ошибки искажённого вывода или разбора JSON

Убедитесь, что в коде запуска ничего не записывает в stdout текст, не являющийся JSON, перед запуском сервера MCP. Выходные данные журнала должны переходить к stderr или файлу журнала, а не stdout. При необходимости используйте --LogLevel для подавления подробных сообщений о запуске.

Кері байланыс

Бет пайдалы болды ма?

Last updated on 2026-03-14

Stdio транспорт для SQL MCP Server

Когда следует использовать stdio транспорт

Необходимые условия

Требуемая конфигурация

Запуск в режиме stdio

Как работает режим stdio

Кодировка UTF-8 (без метки порядка байтов)

Проверка подлинности симулятора

Нет прослушивателя HTTP

Доступные средства MCP

Настройка клиента MCP для stdio

VS Code (mcp.json)

Claude Desktop (claude_desktop_config.json)

Совмещение с другими dab start параметрами

Режим устранения неполадок stdio

Failed to start the engine in MCP stdio mode