Compartilhar via

Transporte stdio para SQL MCP Server

Importante

O SERVIDOR MCP (Protocolo de Contexto do Modelo SQL) está disponível no Construtor de API de Dados versão 1.7 e posterior.

O SQL MCP Server dá suporte a dois transportes: HTTP transmitivel para cenários hospedados e de nuvem e stdio para desenvolvimento local e integração de agente direto. Este artigo aborda o transporte de stdio.

No modo stdio, o Data API builder (DAB) se comunica com um cliente MCP completamente por meio de entrada/saída padrão (stdin/stdout). Nenhum servidor HTTP ou porta de rede é iniciado. O cliente MCP inicia o DAB como um processo filho e canaliza mensagens para frente e para trás usando o Modelo de Protocolo de Contexto (MCP).

Quando usar o transporte de stdio

Scenario Transporte recomendado
Desenvolvimento local em uma estação de trabalho para desenvolvedores Stdio
VS Code com GitHub Copilot (modo de agente) Stdio
Pipelines de CI/CD ou automação de agente com script Stdio
Hospedagem em nuvem (Aplicativos de Contêiner, Serviço de Aplicativo) HTTP
Agente do AI Foundry com ponto de extremidade MCP remoto HTTP
Equipes de agentes compartilhando o mesmo ponto de acesso HTTP

Escolha stdio quando quiser a configuração local mais simples possível sem portas abertas. Escolha HTTP quando o servidor MCP precisar ser acessível em uma rede.

Pré-requisitos

  • CLI do Construtor de API de Dados instalada (versão 1.7 ou posterior)
  • Um existente dab-config.json com MCP habilitado (consulte a configuração necessária)
  • Um cliente compatível com MCP (VS Code com GitHub Copilot, Claude Desktop ou um agente personalizado)

Configuração necessária

Antes de usar o transporte stdio, habilite o MCP em seu dab-config.json:

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

O path campo é usado somente para transporte HTTP e é ignorado no modo stdio. O dml-tools bloco controla quais operações de manipulação de dados estão disponíveis como ferramentas MCP.

Importante

Se "mcp": { "enabled": false } ou o bloco mcp estiver ausente, o DAB falhará em iniciar no modo stdio.

Iniciar no modo stdio

Use a --mcp-stdio flag em dab start:

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

Para executar em uma função de permissão específica:

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

O role:<name> argumento é posicional e deve seguir --mcp-stdioimediatamente. Se omitida, a função usará como padrão anonymous. O nome da função deve corresponder a uma função definida na seção permissions de pelo menos uma entidade em sua configuração.

Como funciona o modo stdio

Quando --mcp-stdio detectado, o DAB faz as seguintes alterações internamente:

Codificação UTF-8 (sem marca de ordem de byte)

A entrada e a saída do console são configuradas para UTF-8 sem uma marca de ordem de byte (BOM). Essa configuração UTF-8 é necessária para uma comunicação JSON-over-stdio limpa porque muitos clientes MCP rejeitam fluxos prefixados pelo BOM.

Autenticação do simulador

O provedor de autenticação é substituído ao modo Simulador , independentemente do que o arquivo de configuração especifica. Esse modo simulador permite que a função especificada seja aplicada diretamente sem um JWT (Token Web JSON) real ou um provedor de identidade. O provedor simulador foi projetado para cenários de desenvolvimento e não deve ser usado para proteger endpoints HTTP em ambiente de produção, mas é exatamente adequado para sessões locais de stdio.

Os seguintes valores são aplicados na memória e substituem suas configurações durante a sessão.

Chave Valor
MCP:StdioMode "true"
MCP:Role "<role-name>" ou "anonymous"
Runtime:Host:Authentication:Provider "Simulator"

Nenhum ouvinte HTTP

O host ASP.NET Core é iniciado e todos os serviços são registrados, mas o DAB chama stdio.RunAsync() em vez de host.Run(). Nenhuma porta TCP (Protocolo de Controle de Transmissão) está associada. Todas as mensagens de protocolo MCP fluem por stdin/stdout.

Ferramentas MCP disponíveis

As seguintes ferramentas estão disponíveis no modo stdio, sujeitas à configuração dml-tools e às permissões de entidade:

Tool Descrição
describe_entities Lista entidades disponíveis e seus campos e permissões
create_record Insere um novo registro (somente tabelas)
read_records Lê registros de uma entidade
update_record Atualiza um registro existente
delete_record Exclui um registro existente (tabelas e exibições)
execute_entity Executa uma entidade de procedimento armazenado

Ferramentas MCP personalizadas suportadas por procedimentos armazenados também são registradas quando você usa --mcp-stdio.

Configurar um cliente MCP para stdio

Clientes MCP que suportam o transporte stdio inicializam o DAB como um subprocesso e redirecionam seu stdin/stdout. A sintaxe de configuração do cliente varia de acordo com o cliente.

VS Code (mcp.json)

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

Salve esse arquivo como .vscode/mcp.json dentro da pasta do projeto. O VS Code detecta a configuração automaticamente e mostra o servidor no MCP: Listar servidores. Como o cliente gerencia o ciclo de vida do processo, você não precisa executá-lo dab start separadamente em um terminal.

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", "none"
      ]
    }
  }
}

Combinar com outras dab start opções

--mcp-stdio é compatível com todas as outras dab start opções:

Opção Comportamento com --mcp-stdio
--config Usa o arquivo de configuração especificado (mesmo que o modo HTTP)
--LogLevel Aplica o nível de log especificado (none: recomendado para stdio) 
dab start \
  --mcp-stdio role:api-reader \
  --config ./dab-config.json \
  --LogLevel None

Solucionar problemas do modo stdio

Failed to start the engine in MCP stdio mode.

O DAB não pôde começar. Verifique:

  • O arquivo de configuração é válido: executar dab validate --config <path>
  • Seu string de conexão do banco de dados está correto e acessível
  • O MCP está habilitado na configuração: "mcp": { "enabled": true }

Permissão negada em chamadas da ferramenta MCP

A função especificada por role:<name> não tem as permissões necessárias para a entidade e a operação. Verifique a seção permissions da entidade relevante em sua configuração.

Ferramentas MCP não listadas

Ou dml-tools é definido globalmente como false, ou a entidade tem "dml-tools": false em suas configurações de mcp. Verifique também se mcp.enabled é true.

Erros de análise de JSON ou saída embaralhada

Certifique-se de que nada no código de inicialização escreva texto não JSON no stdout antes de o servidor MCP iniciar. A saída do log deve ser direcionada para stderr ou um arquivo de log, e não para stdout. Use --LogLevel para suprimir mensagens de inicialização detalhadas, se necessário.

Conteúdo relacionado

  • Last updated on