Partilhar via

O que é o SQL MCP Server?

Importante

O SQL Model Context Protocol (MCP) Server está em pré-visualização, e esta documentação e a implementação do motor podem mudar. Embora a versão 1.7 do Data API builder esteja em pré-visualização, deve usar explicitamente a versão pré-lançamento (por exemplo, 1.7.83-rc) porque as funcionalidades MCP ainda não estão incluídas na :latest etiqueta.

O SQL MCP Server oferece aos programadores uma forma simples, previsível e segura de integrar agentes de IA nos seus fluxos de trabalho de dados. O SQL MCP Server cumpre este objetivo sem expor a base de dados ou depender de uma análise sintáctica de linguagem natural frágil. Ao basear-se na abstração de entidades, RBAC, cache e telemetria do Data API Builder, o servidor oferece uma superfície pronta para produção que funciona da mesma forma em REST, GraphQL e MCP. Configura-se uma vez, e o motor trata do resto.

Diagrama que mostra como o SQL MCP Server liga agentes de IA a bases de dados SQL através da camada de abstração Data API builder.

Protocolo de contexto de modelo (MCP)

O Protocolo de Contexto de Modelo (MCP) é uma norma que define como os agentes de IA descobrem e chamam ferramentas externas. Uma ferramenta é uma única operação, como criar um registo ou ler dados. Cada ferramenta descreve as suas entradas, saídas e comportamento. O MCP oferece uma forma previsível para os agentes descobrirem e utilizarem capacidades.

Servidor MCP para SQL

SQL MCP Server é o motor dinâmico e open source da Microsoft para aplicações agentes. Configura-se isto com um ficheiro JSON que define:

  • Como se ligar à sua base de dados
  • Quais tabelas, vistas ou procedimentos armazenados devem ser expostos
  • As permissões que se aplicam a cada objeto

O SQL MCP Server está incluído como parte do Data API builder (DAB) a partir da versão 1.7. Expõe as operações SQL como uma pequena família de ferramentas MCP para que os agentes possam interagir com entidades da base de dados através de um contrato controlado. O servidor é auto-hospedado mas, para os programadores, também pode correr localmente através da linha de comandos do DAB.

Sugestão

O Data API Builder é open source e gratuito de usar.

Detalhes do protocolo MCP

O SQL MCP Server implementa o protocolo MCP versão 2025-06-18 como padrão fixo. Suporta dois transportes: HTTP streamable para cenários de alojamento padrão e stdio para cenários locais ou CLI. Durante a inicialização, o servidor anuncia ferramentas e capacidades de registo, devolve metadados do servidor (nome e versão DAB) e devolve o instructions campo de runtime.mcp.description para que os clientes compreendam o propósito do servidor.

Transporte Stdio

O transporte stdio é útil para desenvolvimento local e fluxos de trabalho baseados na Interface de Linha de Comandos (CLI). Pode especificar um papel com role:<role-name>, que por defeito é anonymous quando é omitido. Neste modo, a autenticação utiliza o fornecedor do simulador e os pedidos recebidos são limitados a 1 MB.

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

Podes testar SQL MCP Server com o MCP Inspector.

Casos de uso

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

  • Permitir que copilots ou chatbots realizem operações CRUD seguras
  • Construir automações internas sem escrever SQL
  • Adicionar capacidades de agente sem expor diretamente a base de dados

Fixação do esquema

O Data API builder utiliza uma camada de abstração de entidades bem definida que lista todas as tabelas, vistas e procedimentos armazenados expostos através da API na configuração. Esta camada permite-lhe atribuir alias a nomes e colunas, descrever objetos e parâmetros, e limitar quais campos estão disponíveis para diferentes funções.

Importante

O Data API Builder (DAB) é consciente dos papéis e apenas expõe as entidades e operações para os quais o papel atual tem permissão para aceder.

Como o SQL MCP Server é uma funcionalidade do Data API builder, também utiliza esta camada de abstração. Esta abordagem impede que o esquema interno seja exposto a consumidores externos e permite definir famílias complexas de objetos e relações, até mesmo envolvendo múltiplas fontes de dados, na camada da API.

Resolver o problema de NL2SQL

SQL MCP Server adota uma abordagem diferente em comparação com muitos servidores MCP de bases de dados limitados disponíveis atualmente. Um exemplo chave é que o SQL MCP Server intencionalmente não suporta NL2SQL.

Why? Os modelos não são determinísticos, e consultas complexas são as mais propensas a produzir erros subtis. Estas consultas complexas são frequentemente aquelas que os utilizadores esperam que a IA possa gerar, mas também são as que exigem maior escrutínio quando produzidas de forma não determinística.

Observação

Determinístico significa que a mesma entrada produz sempre a mesma saída. Não há aleatoriedade ou variação entre as chamadas, o que torna os resultados previsíveis, testáveis e seguros de automatizar.

Em vez disso, o SQL MCP Server suporta o que poderia ser chamado de modelo NL2DAB. Esta abordagem utiliza a camada de abstração de entidade do Secure Data API Builder e do DAB Query Builder integrado. Juntos, produzem Transact-SQL (T-SQL) precisos e bem formados de forma totalmente determinística. Esta abordagem elimina o risco, a sobrecarga e o incómodo associados ao NL2SQL, preservando a segurança e fiabilidade das consultas geradas por agentes.

Suporte para DDL

DDL (Data Definition Language) é a linguagem de bases de dados usada para criar e alterar objetos como tabelas e vistas. O SQL MCP Server é construído em torno da DML (Data Manipulation Language), a linguagem de base de dados usada para criar, ler, atualizar e eliminar dados em tabelas e vistas existentes. DML também cobre a execução de procedimentos armazenados. Como resultado, o SQL MCP Server foi concebido para trabalhar com dados, não com esquemas. Este design está alinhado com casos de uso MCP em produção, onde agentes de IA interagem com sistemas críticos para a missão ou sensíveis ao negócio.

Sugestão

Para modificar o esquema durante o desenvolvimento local, pode usar a extensão Microsoft SQL Server (MSSQL) no Visual Studio Code, que oferece suporte abrangente a DDL.

Apoio ao RBAC

SQL MCP Server beneficia do mesmo sistema comprovado de controlo de acesso baseado em funções (RBAC) utilizado em todo o Data API Builder. Cada entidade na sua configuração define quais os papéis que podem ler, criar, atualizar ou eliminar dados, e quais os campos incluídos ou excluídos para esses papéis. Estas regras aplicam-se automaticamente a todas as ferramentas MCP, garantindo que a segurança se mantém consistente entre REST, GraphQL e MCP sem necessidade de configuração adicional.

Importante

Restrições baseadas em funções aplicam-se em todas as etapas da interação com o agente.

Suporte para cache

O SQL MCP Server armazena automaticamente em cache os resultados da read_records ferramenta. O cache no Data API Builder está ativado globalmente, e pode configurá-lo por entidade. Tanto o cache de nível 1 como o de nível 2 ajudam a reduzir a carga da base de dados, evitam estampidas de pedidos e suportam cenários de arranque quente em ambientes de escala horizontal.

Suporte para monitorização

O SQL MCP Server emite logs e telemetria que permitem às empresas monitorizar e validar a atividade a partir de um único painel de vidro. Esta funcionalidade inclui Azure Log Analytics, Application Insights e registos locais de ficheiros dentro de um contentor.

Telemetria

SQL MCP Server está totalmente instrumentado com spans e atividades do OpenTelemetry (OTEL). Cada operação é rastreada para que os programadores possam correlacionar o comportamento entre sistemas distribuídos. Saiba mais sobre o suporte nativo de Open Telemetry do Data API Builder.

Controlos sanitários

O SQL MCP Server fornece verificações detalhadas de saúde e de entidades nos endpoints REST, GraphQL e MCP. O Data API Builder Health permite aos programadores definir expectativas de desempenho, definir limiares e verificar se cada endpoint está a funcionar como esperado.

Como configurar o SQL MCP Server

O MCP está configurado no teu ficheiro de configuração DAB. Se já tiver uma configuração funcional do Data API Builder, atualizar para a versão 1.7 ou posterior dá-lhe automaticamente um SQL MCP Server funcional sem necessidade de passos adicionais.

Configuração

Pode ativar o MCP globalmente ou ao nível da entidade. Esta funcionalidade permite-lhe escolher que entidades utilizam ferramentas MCP e quais permanecem inacessíveis aos agentes. O MCP segue as mesmas regras usadas para REST e GraphQL, pelo que a sua configuração continua a ser a única fonte de verdade para permissões, projeções e políticas.

Quando o MCP está ativado, o SQL MCP Server gera automaticamente a superfície da sua ferramenta com base na sua configuração. Não defines as ferramentas MCP manualmente. O sistema incorporado dml-tools descobre e expõe entidades proceduralmente, o que escala bem desde esquemas pequenos até bases de dados muito grandes.

Introdução

Começar significa criar o dab-config.json para controlar o motor. Pode fazer esta tarefa manualmente, ou pode usar a CLI do Data API builder (DAB). A CLI simplifica a tarefa, permitindo inicializar o ficheiro com um único comando. Os valores das propriedades de configuração podem usar strings 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

Pode especificar cada tabela, vista ou procedimento armazenado que quer que o SQL MCP Server exponha, adicionando-os à configuração. A CLI permite-te adicioná-los facilmente, atribuir aliases, configurar as permissões e mapear colunas se quiseres. Mais importante ainda, com a description propriedade, pode incluir detalhes semânticos para ajudar os modelos de linguagem a compreender melhor os 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)

Definições de tempo de execução

O SQL MCP Server está ativado por defeito na configuração do Data API builder. Na maioria dos casos, não precisas de adicionar definições. O servidor segue automaticamente as mesmas permissões e regras de segurança que a sua API e base de dados. Configure MCP apenas quando quiser estreitar 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
    }
  }
}

A CLI também permite definir cada propriedade individualmente ou programaticamente através 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

Porque é que desativar ferramentas individuais?

Os programadores podem querer restringir ações específicas mesmo quando as permissões de papéis ou entidades as permitam. Desativar uma ferramenta ao nível de execução garante que nunca aparece aos agentes. Por exemplo, desativar delete_record oculta completamente a capacidade de eliminar, independentemente da configuração em outro lugar. Este cenário é incomum, mas útil quando são exigidos limites operacionais rigorosos.

Configurações de entidade

Também não precisas de ativar o MCP em cada entidade. As entidades participam automaticamente, a menos que escolhas restringi-las. A dml-tools propriedade existe para que possa excluir uma entidade do MCP ou restringir as suas capacidades, mas não precisa de definir nada para uso normal. As configurações predefinidas tratam de tudo.

"entities": {
  "products": {
    "mcp": {
      "dml-tools": true
    }
  }
}

As ferramentas DML

O SQL MCP Server expõe seis ferramentas de Linguagem de Manipulação de Dados (DML) que permitem aos agentes de IA realizar operações de base de dados seguras e seguras para tipos: describe_entities, create_record, read_records, update_record, delete_record, e execute_entity. Estas ferramentas formam uma superfície CRUD previsível que reflete sempre a sua configuração, permissões e esquema.

Cada ferramenta respeita o controlo de acesso baseado em funções (RBAC), permissões de entidades e políticas. Os agentes nunca interagem diretamente com a tua base de dados – funcionam através da camada de abstração segura do Data API builder.

Conteúdo relacionado

  • Last updated on