O que é o SQL MCP Server?

O SQL MCP Server fornece aos desenvolvedores uma maneira simples, previsível e segura de colocar agentes de IA em seus fluxos de trabalho de dados. O SQL MCP Server atinge essa meta sem expor o banco de dados ou depender da análise de linguagem natural frágil. O servidor se baseia na abstração de entidade, RBAC, cache e telemetria do Construtor de API de Dados para fornecer uma superfície pronta para produção que funciona da mesma forma em REST, GraphQL e MCP. Você configura uma vez e o mecanismo cuida de todo o resto.

Protocolo de Contexto de Modelo (MCP)

O PROTOCOLO MCP (Model Context Protocol) é um padrão que define como os agentes de IA descobrem e chamam ferramentas externas. Uma ferramenta é uma única operação, como criar um registro ou ler dados. Cada ferramenta descreve suas entradas, saídas e comportamento. O MCP fornece uma maneira previsível para os agentes descobrirem e usarem recursos.

Servidor MCP para SQL

O SQL MCP Server é o mecanismo dinâmico e open source da Microsoft para aplicativos agente. Configure-o com um arquivo JSON que define:

• Como se conectar ao banco de dados
• Quais tabelas, exibições ou procedimentos armazenados expor
• As permissões que se aplicam a cada objeto

O SQL MCP Server é incluído como parte do DAB (Construtor de API de Dados) a partir da versão 1.7. Ele expõe operações SQL como uma pequena família de ferramentas MCP para que os agentes possam interagir com entidades de banco de dados por meio de um contrato controlado. O servidor é auto-hospedado, mas, para desenvolvedores, ele também pode ser executado localmente por meio da linha de comando do DAB.

Detalhes do protocolo MCP

O SQL MCP Server implementa o protocolo MCP versão 2025-06-18 como um padrão fixo. Ele dá suporte a dois métodos de comunicação: HTTP com transmissão contínua para cenários de hospedagem padrão e stdio para cenários locais ou de interface de linha de comando (CLI). Durante a inicialização, o servidor anuncia ferramentas e capacidades de registro em log, retorna metadados do servidor, como nome e versão do DAB, e inclui o instructions campo de runtime.mcp.description para que os clientes compreendam a finalidade do servidor.

Inspetor MCP

Para endpoints MCP baseados em HTTP, por exemplo, quando o DAB estiver em execução http://localhost:5000/mcp, inicie o Inspetor MCP no modo proxy inserindo diretamente a URL do endpoint:

Primeiro, inicie o construtor de API de Dados:

dab start

Em seguida, em outro terminal, inicie o Inspetor MCP com a URL do endpoint.

npx -y @modelcontextprotocol/inspector http://localhost:5000/mcp

Isso roteia solicitações por meio do proxy Inspetor e ajuda a evitar problemas de CORS do navegador e de cabeçalhos de sessão, que podem ocorrer no modo direto, como Mcp-Session-Id.

Transporte stdio

O transporte stdio é útil para desenvolvimento local e fluxos de trabalho de interface de linha de comando (CLI). Você pode especificar uma função com role:<role-name>, que usa como padrão anonymous quando omitida. Nesse modo, a autenticação usa o provedor de simulador e as solicitações de entrada são limitadas a 1 MB.

dab start --mcp-stdio

dab start --mcp-stdio role:<role-name>

Casos de uso

Aqui estão alguns casos de uso típicos para o SQL MCP Server:

• Permitir que copilots ou chatbots executem operações CRUD seguras
• Criar automações internas sem gravar SQL
• Adicionar recursos do agente sem expor o banco de dados diretamente

Protegendo o esquema

O Construtor de API de Dados usa uma camada de abstração de entidade bem definida que lista todas as tabelas, exibições e procedimentos armazenados expostos por meio da API na configuração. Essa camada permite que você alias nomes e colunas, descreva objetos e parâmetros e limite quais campos estão disponíveis para diferentes funções.

Como o SQL MCP Server é um recurso do Construtor de API de Dados, ele também usa essa camada de abstração. Essa abordagem impede que o esquema interno seja exposto a consumidores externos e permite que você defina famílias de objetos e relações complexas e até mesmo entre fontes de dados na camada de API.

Solução de NL2SQL

O SQL MCP Server adota uma abordagem diferente de muitos dos servidores MCP de banco de dados com visão curta disponíveis hoje. Um exemplo importante é que o SQL MCP Server intencionalmente não dá suporte ao NL2SQL.

Por que? Modelos não são determinísticos e consultas complexas são as mais propensas a produzir erros sutis. Essas consultas complexas geralmente são as que os usuários esperam que a IA possa gerar, mas também são as que exigem mais escrutínio quando produzidas de forma não determinística.

Em vez disso, o SQL MCP Server dá suporte ao que pode ser chamado de modelo NL2DAB. Essa abordagem usa a camada de abstração de entidade segura do construtor de API de Dados e o Construtor de Consultas DAB interno. Juntos, eles produzem Transact-SQL preciso e bem formado (T-SQL) de forma totalmente determinística. Essa abordagem remove o risco, a sobrecarga e o incômodo associados ao NL2SQL, preservando a segurança e a confiabilidade das consultas geradas pelo agente.

Suporte para DDL

DDL (Linguagem de Definição de Dados) é a linguagem de banco de dados usada para criar e alterar objetos, como tabelas e exibições. O SQL MCP Server é criado em torno de DML (Linguagem de Manipulação de Dados), a linguagem de banco de dados usada para criar, ler, atualizar e excluir dados em tabelas e exibições existentes. O DML também aborda a execução de procedimentos armazenados. Como resultado, o SQL MCP Server foi projetado para trabalhar com dados, não com esquema. Esse design se alinha aos casos de uso do MCP de produção em que os agentes de IA interagem com sistemas críticos ou sensíveis aos negócios.

Suporte para RBAC

O SQL MCP Server se beneficia do mesmo sistema RBAC (controle de acesso baseado em função) comprovado usado em todo o construtor de API de Dados. Cada entidade em sua configuração define quais funções podem ler, criar, atualizar ou excluir dados e quais campos são incluídos ou excluídos para essas funções. Essas regras se aplicam automaticamente a todas as ferramentas MCP, garantindo que a segurança permaneça consistente entre REST, GraphQL e MCP sem nenhuma configuração adicional necessária.

Suporte para cache

O SQL MCP Server armazena automaticamente em cache os resultados da read_records ferramenta. O cache no construtor de API de Dados está habilitado globalmente e você pode configurá-lo por entidade. Os caches de nível 1 e nível 2 ajudam a reduzir a carga do banco de dados, evitar enxurradas de solicitações e suportar cenários de início aquecido em ambientes escalados horizontalmente.

Suporte para monitoramento

O SQL MCP Server emite logs e telemetria que permitem que as empresas monitorem e validem a atividade de um único painel de vidro. Esse recurso inclui Azure Log Analytics, Application Insights e logs de arquivos locais dentro de um contêiner.

Telemetria

O SQL MCP Server é totalmente instrumentado com intervalos e atividades do OpenTelemetry (OTEL). Cada operação é rastreada para que os desenvolvedores possam correlacionar o comportamento entre sistemas distribuídos. Saiba mais sobre o suporte nativo de Telemetria Aberta do Construtor de API de Dados.

Exames de saúde

O SQL MCP Server fornece verificações detalhadas de integridade e de entidades nos endpoints REST, GraphQL e MCP. Saúde do Construtor de API de Dados permite que os desenvolvedores definam expectativas de desempenho, estabeleçam limites e verifiquem se cada endpoint está funcionando conforme o esperado.

Como configurar o SQL MCP Server

O MCP está configurado no arquivo de configuração do DAB. Se você já tiver uma configuração de construtor de API de Dados em funcionamento, a atualização para a versão 1.7 ou posterior fornecerá automaticamente um SQL MCP Server funcional sem nenhuma etapa adicional necessária.

Configuração

Você pode habilitar o MCP globalmente ou no nível da entidade. Essa funcionalidade permite que você escolha quais entidades exibem ferramentas MCP e que permanecem inacessíveis aos agentes. O MCP segue as mesmas regras usadas para REST e GraphQL, portanto, sua configuração continua sendo a única fonte de verdade para permissões, projeções e políticas.

Quando o MCP está habilitado, o SQL MCP Server gera sua superfície de ferramentas automaticamente com base em sua configuração. Você não define as ferramentas do MCP manualmente. O sistema embutido dml-tools descobre e expõe entidades proceduralmente, que se adapta bem de esquemas pequenos para bancos de dados muito grandes.

Introdução

Começar significa criar o dab-config.json para controlar o motor. Você pode fazer essa tarefa manualmente ou pode usar a CLI do DAB (Construtor de API de Dados). A CLI simplifica a tarefa, permitindo que você inicialize o arquivo com um único comando. Os valores da propriedade de configuração podem usar cadeias de caracteres literais, variáveis de ambiente ou segredos do Azure Key Vault.

dab init --database-type mssql --connection-string "<your-connection-string>" --config dab-config.json --host-mode development

Você pode especificar cada tabela, exibição ou procedimento armazenado que deseja que o SQL MCP Server exponha adicionando-os à configuração. A CLI permite adicioná-los facilmente, atribuir aliases, configurar suas permissões e mapear colunas, se desejar. Mais importante, com a description propriedade, você pode incluir detalhes semânticos para ajudar os modelos de linguagem a entender melhor seus dados.

dab add {entity-name} \                          # object alias (Employees)
  --source {table-or-view-name} \                # database object (dbo.Employees)
  --source.type {table|view|stored-procedure} \  # object type (table)
  --permissions "{role:actions}" \               # role and allowed actions (anonymous:*)
  --description "{text}"                         # semantic description (Company employee records)

Configurações de runtime

O SQL MCP Server é habilitado por padrão na configuração do construtor de API de Dados. Na maioria dos casos, você não precisa adicionar nenhuma configuração. O servidor segue automaticamente as mesmas permissões e regras de segurança que a API e o banco de dados. Configure o MCP somente quando você quiser limitar ou restringir o que os agentes podem fazer.

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

Defina dml-tools para true ou false para habilitar ou desabilitar todas as ferramentas, ou use um objeto com alternâncias por ferramenta. A ferramenta aggregate-records também pode aceitar um objeto com enabled e query-timeout (de 1 a 600 segundos, padrão 30) propriedades. Para obter a referência de configuração completa, consulte a configuração de runtime do MCP.

A CLI também permite que você defina cada propriedade individual ou programaticamente por meio de scripts.

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true

Por que desabilitar ferramentas individuais?

Os desenvolvedores podem querer restringir ações específicas mesmo quando as funções ou permissões de entidade permitem. Desabilitar uma ferramenta no nível de runtime garante que ela nunca apareça para os agentes. Por exemplo, desativar delete_record oculta completamente a funcionalidade de exclusão, independentemente da configuração em outro lugar. Esse cenário é incomum, mas útil quando limites operacionais estritos são necessários.

Configurações de entidade

Você também não precisa habilitar o MCP em cada entidade. As entidades participam automaticamente, a menos que você opte por restringi-las. A mcp propriedade existe para que você possa excluir uma entidade do MCP ou restringir seus recursos, mas você não precisa definir nada para uso normal. As configurações padrão lidam com tudo.

Use o formato de objeto para a configuração do MCP no nível da entidade:

"entities": {
  "Products": {
    "mcp": {
      "dml-tools": true
    }
  },
  "SensitiveData": {
    "mcp": {
      "dml-tools": false
    }
  }
}

Para entidades de procedimento armazenado, você também pode habilitar custom-tool para registrar o procedimento como uma ferramenta nomeada do MCP.

"entities": {
  "GetBookById": {
    "source": {
      "type": "stored-procedure",
      "object": "dbo.get_book_by_id"
    },
    "mcp": {
      "custom-tool": true
    }
  }
}

Quando custom-tool é true, o SQL MCP Server registra o procedimento armazenado como uma ferramenta nomeada por meio tools/list e tools/call, permitindo que os agentes o descubram e o invoquem diretamente pelo nome. A custom-tool propriedade só é válida para entidades de procedimento armazenado.

As ferramentas DML

O SQL MCP Server expõe sete ferramentas de DML (Linguagem de Manipulação de Dados) que permitem aos agentes de IA executar operações de banco de dados seguras e de tipo seguro: describe_entities, , create_record, read_records, update_record, delete_recorde execute_entityaggregate_records. Essas ferramentas formam uma superfície CRUD previsível que sempre reflete sua configuração, permissões e esquema.

Cada ferramenta respeita o RBAC (controle de acesso baseado em função), as permissões de entidade e as políticas. Os agentes nunca interagem diretamente com seu banco de dados – eles funcionam por meio da camada de abstração segura do construtor de API de Dados.

Ferramentas MCP personalizadas

Além das ferramentas DML internas, o SQL MCP Server dá suporte a ferramentas MCP personalizadas derivadas de procedimentos armazenados. Quando você define "custom-tool": true em uma entidade de procedimento armazenado, o DAB registra-a como uma ferramenta nomeada por meio do MCP tools/list e tools/call. Essa abordagem permite que os agentes descubram e invoquem procedimentos armazenados diretamente pelo nome, complementando a ferramenta DML genérica execute_entity .

Rastreamento OpenTelemetry do MCP

A execução da ferramenta MCP é totalmente instrumentada com intervalos OTEL (OpenTelemetry). Cada chamada de ferramenta MCP gera dados de rastreamento junto com operações REST e GraphQL, permitindo a observabilidade unificada em todas as superfícies de API. Saiba mais sobre o rastreamento OpenTelemetry.

Conteúdo relacionado

• Adicionando descrições semânticas ao SQL MCP Server
• Configurar a autenticação para o SQL MCP Server
• Ferramentas de manipulação de dados no SQL MCP Server
• Deploy SQL MCP Server para Azure Container Apps
• Comece com o SQL MCP Server no Visual Studio Code
• Comece com o SQL MCP Server em .NET Aspire
• Comece com o SQL MCP Server no Azure AI Foundry