Conecte agentes de IA à API de malha para GraphQL com um servidor MCP (Model Context Protocol) local

Imagine pedir ao GitHub Copilot "Mostre-me todas as vendas do último trimestre" e vê-lo consultar automaticamente o seu data warehouse Fabric, compreender o esquema e devolver resultados — tudo isto sem escrever uma única linha de GraphQL. Este tutorial mostra-te como tornar isso possível.

Neste tutorial, constróis um servidor local GraphQL MCP que funciona como uma ponte entre agentes de IA e os teus dados Microsoft Fabric. No final, tens um servidor de desenvolvimento funcional que permite a assistentes de IA como o GitHub Copilot, Claude e outros agentes de IA consultar naturalmente os teus dados do Fabric usando linguagem conversacional.

O que você realizará:

Configura autenticação para que o teu servidor GraphQL MCP possa aceder ao Fabric de forma segura
Ative a introspeção de esquemas para que os agentes de IA possam descobrir automaticamente a sua estrutura de dados
Implemente um servidor local GraphQL MCP que traduza linguagem natural em consultas GraphQL
Ligue o GitHub Copilot ou outras ferramentas de IA para consultar os seus dados de forma conversacional

O que é o Model Context Protocol (MCP)?

O Protocolo de Contexto do Modelo (MCP) é um padrão para ligar assistentes de IA aos sistemas onde residem dados, incluindo repositórios de conteúdo, ferramentas empresariais e ambientes de desenvolvimento. O seu objetivo é ajudar os modelos de fronteira a produzir respostas melhores e mais pertinentes. Pense no MCP como uma porta USB-C para aplicações de IA. Assim como USB-C fornece uma maneira padronizada de conectar seus dispositivos a vários periféricos e acessórios, o MCP fornece uma maneira padronizada de conectar modelos de IA a fontes de dados e ferramentas externas.

As principais plataformas de IA, incluindo OpenAI, Microsoft Copilot Studio e Microsoft Foundry, adotaram o MCP como forma padrão de integrar agentes de IA com sistemas externos. Isso torna o MCP uma escolha ideal para conectar agentes de IA aos seus dados do Microsoft Fabric.

Porque é que o GraphQL é ideal para MCP

O GraphQL é bem adequado para integrações MCP porque:

Introspeção de esquema: os agentes de IA podem descobrir automaticamente estruturas de dados e relacionamentos disponíveis diretamente do esquema GraphQL
Consultas flexíveis: os agentes podem solicitar exatamente os dados de que precisam em uma única solicitação
Segurança de tipo: a tipagem forte ajuda os agentes de IA a compreender formatos de dados e restrições
Busca eficiente de dados: reduz a busca excessiva e insuficiente de dados

A API do Microsoft Fabric para GraphQL facilita a exposição dos seus lakehouses, Data Warehouses e bases de dados Fabric a agentes de IA através de uma interface GraphQL padronizada. Embora a API para GraphQL já forneça recursos de consulta poderosos, configurar uma conexão para agentes de IA pode não ser tão simples quanto poderia ser.

Com um simples servidor local GraphQL MCP, os programadores podem usar agentes de IA para descobrir a sua estrutura de dados Fabric, compreender o que está disponível e consultá-lo usando linguagem natural – tudo através da interface MCP padronizada. Convenientemente, não precisa de definir uma ferramenta MCP separada no servidor para cada tipo, consulta ou mutação GraphQL. O servidor MCP GraphQL analisa o esquema GraphQL, permitindo aos agentes de IA compreender todos os tipos e operações disponíveis desde o início.

Pré-requisitos

Antes de começar este tutorial, certifique-se de que:

Um espaço de trabalho Microsoft Fabric com permissões apropriadas. É necessário um papel de administrador de espaço de trabalho para configurar os principais de serviço e permitir a introspeção.
Uma API para item GraphQL criada e configurada. Consulte Criar e adicionar dados a uma API para GraphQL ou Criar API GraphQL a partir da sua base de dados SQL no portal Fabric.
Node.js instalado na tua máquina de desenvolvimento (inclui o NPM)
Visual Studio Code instalado na sua máquina de desenvolvimento

Observação

Não és administrador? Alguns passos deste tutorial requerem permissões de administrador. Se não fores administrador, podes completar a maior parte do tutorial pedindo ajuda ao teu administrador com tarefas específicas. Cada passo que requer permissões de administrador está claramente assinalado.

Etapa 1: Configurar o acesso da entidade de serviço

O que estás a fazer: Configurar credenciais de autenticação não interativas para que o seu servidor GraphQL MCP possa aceder ao Fabric sem que o utilizador tenha de iniciar sessão cada vez.

Porque é que isto importa: O servidor MCP GraphQL funciona como um serviço em segundo plano que os agentes de IA chamam automaticamente. Precisa da sua própria identidade (um principal de serviço) com credenciais para autenticar no Fabric em nome da sua aplicação, não em nome de um utilizador específico.

Siga o guia completo em Usar Principais de Serviço com a API Fabric para GraphQL para:

Criar um Registo de Aplicações Azure (qualquer utilizador com permissões para criar registos de aplicações no Microsoft Entra ID)
Adicionar um segredo de cliente em Certificados & segredos (qualquer utilizador)
Ativa os principais de serviço nas definições do teu tenant (requer administrador do tenant Fabric)
Conceda permissões à sua API GraphQL e ao seu espaço de trabalho (requer um papel de administrador ou contribuidor)

Sugestão

Não és administrador? Podes completar os dois primeiros itens tu mesmo. Para a definição de arrendatário, peça ao administrador do arrendatário do Fabric para ativar "Os entidades de serviço podem usar APIs do Fabric" em Portal de Administração>Configurações do Arrendatário>Configurações do Desenvolvedor. Para permissões de espaço de trabalho, peça ao administrador do seu espaço de trabalho para conceder ao seu principal de serviço acesso ao espaço de trabalho ou à API específica do GraphQL.

Ao completar a configuração, capture estes três valores para a configuração do servidor GraphQL MCP:

ID de Inquilino: Encontrado no ID Microsoft Entra em Visão Geral>ID de Inquilino
ID do Cliente: Encontrado no registo da sua aplicação em Visão Geral>ID da Aplicação (cliente)
Segredo do Cliente: O valor do segredo mostrado quando cria um novo segredo do cliente (copiar imediatamente—só é mostrado uma vez)

Passo 2: Ativar o GraphQL Introspection (requer administração do espaço de trabalho)

O que estás a fazer: Ativar a introspeção permite ao servidor GraphQL MCP perguntar à sua API GraphQL "Que dados tem?" e receber uma descrição completa de todos os tipos, campos e relações disponíveis.

Porque é que isto importa: Esta é a "magia" que torna possíveis as consultas em linguagem natural. Quando perguntas ao Copilot "Mostra-me clientes", o agente de IA usa primeiro a introspeção para descobrir que existe um customers tipo, que campos tem e como o consultar. Sem introspeção, terias de documentar manualmente todo o esquema da IA.

Importante

A introspeção deve estar ativada para que o servidor MCP do GraphQL funcione. Isto está desativado por defeito no Fabric por razões de segurança. Só os administradores do espaço de trabalho podem ativar a introspeção. Se não és administrador, pede ao administrador do teu espaço de trabalho para completar este passo.

Siga o guia completo sobre a API do Microsoft Fabric para introspeção e exportação de esquemas em GraphQL:

Ativa a introspeção nas definições da tua API
Compreenda como funcionam as perguntas de introspeção
Aprenda sobre as opções de exportação de esquemas

Uma vez ativada a introspeção, o servidor GraphQL MCP pode consultar a estrutura do seu esquema e disponibilizá-la aos agentes de IA.

Passo 3: Configurar o servidor MCP do GraphQL

O que estás a fazer: Instalar e configurar um servidor local de Node.js que implemente o Protocolo de Contexto do Modelo. Este servidor funciona como tradutor entre agentes de IA e a sua API Fabric GraphQL.

Porque é que isto importa: O servidor MCP fornece uma interface padronizada que os agentes de IA compreendem. Quando um agente de IA se liga, pode descobrir que ferramentas estão disponíveis (introspeção e consultas), contactar essas ferramentas e receber respostas — tudo isto sem que escreva código de integração personalizado para cada plataforma de IA.

Agora que tens credenciais de autenticação (Passo 1) e introspeção ativadas (Passo 2), estás pronto para configurar o servidor para as usar.

Clone o repositório de exemplo

git clone https://github.com/microsoft/fabric-samples.git
cd fabric-samples/docs-samples/data-engineering/GraphQL/MCP

Instalar dependências

npm install

Configurar variáveis de ambiente

Crie um .env arquivo na raiz do projeto com sua configuração:

MICROSOFT_FABRIC_API_URL=https://your-fabric-endpoint/graphql
MICROSOFT_FABRIC_TENANT_ID=your_tenant_id_here
MICROSOFT_FABRIC_CLIENT_ID=your_client_id_here
MICROSOFT_FABRIC_CLIENT_SECRET=your_client_secret_here
SCOPE=https://api.fabric.microsoft.com/.default

Substitua os valores de placeholders por:

MICROSOFT_FABRIC_API_URL: Seu ponto de extremidade GraphQL do portal Fabric
MICROSOFT_FABRIC_TENANT_ID: Sua ID de locatário do Azure
MICROSOFT_FABRIC_CLIENT_ID: ID do cliente de registro do aplicativo
MICROSOFT_FABRIC_CLIENT_SECRET: O segredo do cliente de registro do aplicativo

Iniciar o servidor MCP GraphQL

node FabricGraphQL_MCP.js

O servidor inicia http://localhost:3000 e exibe:

Microsoft Fabric GraphQL MCP server listening on port 3000
API URL: https://your-fabric-endpoint/graphql
Scope: https://api.fabric.microsoft.com/.default

Ferramentas MCP disponíveis

O servidor GraphQL MCP fornece duas ferramentas principais:

`introspect-schema`

Finalidade: Obter o esquema completo do GraphQL
Parâmetros: nenhum
Uso: Deve ser chamado primeiro antes de fazer consultas

`query-graphql`

Finalidade: Executa consultas GraphQL em relação aos dados do Fabric
Parâmetros:
- query (obrigatório): A cadeia de caracteres de consulta GraphQL
- variables (opcional): objeto de variáveis GraphQL
Uso: Para todas as operações de recuperação e manipulação de dados

Compreender o fluxo de trabalho

O fluxo de trabalho típico do GraphQL MCP segue este padrão:

Descoberta de Esquemas: O agente de IA deve primeiro ligar à introspect-schema ferramenta para compreender o esquema e os dados disponíveis
Planeamento de Consultas: O agente analisa o seu pedido em linguagem natural e o esquema GraphQL
Geração de consulta: o agente cria consultas GraphQL apropriadas
Execução: O agente chama a query-graphql ferramenta com as consultas geradas
Processamento de respostas: O agente formata e apresenta os resultados

Passo 4: Teste o servidor GraphQL MCP

O que estás a fazer: Verificar se o seu servidor MCP consegue autenticar-se no Fabric, recuperar o seu esquema e executar consultas — antes de ligar agentes de IA.

Porque é que isto importa: Testar manualmente garante que tudo está configurado corretamente. Se estes testes passarem, sabes que os agentes de IA conseguem conectar-se com sucesso no Passo 5.

Verificar a integridade do servidor

Primeiro, confirme que o servidor está a funcionar e pode autenticar-se no Fabric.

Com o PowerShell:

Invoke-RestMethod -Uri "http://localhost:3000/health" -Method Get

Usando cURL:

curl http://localhost:3000/health

Você deve receber uma resposta indicando que o servidor está em execução, semelhante a:

{"status":"healthy","server":"Microsoft Fabric GraphQL MCP Server","hasToken":true,"tokenExpiry":"2025-06-30T23:11:36.339Z"}

Introspeção do esquema de teste

De seguida, verifica se o servidor consegue recuperar o teu esquema GraphQL através da introspeção. Isto chama a introspect-schema ferramenta MCP.

Com o PowerShell:

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 1
    method = "tools/call"
    params = @{
        name = "introspect-schema"
        arguments = @{}
    }
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

Usando cURL:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "introspect-schema",
      "arguments": {}
    }
  }'

Isso deve retornar sua definição de esquema GraphQL.

Testar uma consulta GraphQL

Finalmente, teste a execução de uma consulta GraphQL real através do servidor MCP. Este exemplo consulta todos os nomes de tipos no seu esquema usando a query-graphql ferramenta MCP.

Com o PowerShell:

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 2
    method = "tools/call"
    params = @{
        name = "query-graphql"
        arguments = @{
            query = "query { __schema { types { name } } }"
        }
    }
} | ConvertTo-Json -Depth 4

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

Usando cURL:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query-graphql",
      "arguments": {
        "query": "query { __schema { types { name } } }"
      }
    }
  }'

Isto devolve uma lista de todos os tipos no seu esquema GraphQL.

Etapa 5: Conectar agentes de IA

O que estás a fazer: Configurar ferramentas de IA para usar o seu servidor MCP local como fonte de dados.

Porque é que isto importa: É aqui que tudo se encaixa. Uma vez ligados, os seus agentes de IA podem descobrir o seu esquema Fabric através de introspeção e gerar consultas GraphQL baseadas em pedidos em linguagem natural. A IA trata da sintaxe das consultas — basta fazer perguntas em inglês simples.

Copiloto do GitHub no Visual Studio Code

Instale a extensão GitHub Copilot no VS Code

Configure o servidor MCP GraphQL nas definições do Copilot:

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

No bate-papo Copilot, primeiro peça para introspeccionar o esquema e, em seguida, tente fazer uma pergunta pertinente relacionada aos dados introspeccionados em linguagem natural, por exemplo:

Cursor IDE

Abrir as definições do Cursor

Adicione a configuração do servidor MCP:

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

No chat, primeiro peça para introspeccionar o esquema e, em seguida, tente fazer uma pergunta pertinente relacionada aos dados introspeccionados em linguagem natural.

O que construíste

Parabéns! Agora você tem um servidor MCP GraphQL funcional que:

Autentica-se ao Fabric usando credenciais de principal de serviço
Expõe o seu esquema de dados do Fabric através da introspeção
Traduz pedidos de agentes de IA em consultas GraphQL
Dados de retornos num formato que os agentes de IA conseguem compreender e apresentar

Os seus agentes de IA (como o GitHub Copilot) podem agora:

Descubra automaticamente que dados estão disponíveis no seu espaço de trabalho Fabric
Gerar consultas GraphQL corretas baseadas em perguntas de linguagem natural
Recuperar e formatar resultados sem que escrevas qualquer código de consulta

Este servidor local destina-se ao desenvolvimento e à aprendizagem. As secções seguintes abordam considerações importantes para implementações em produção e cenários comuns de resolução de problemas.

Considerações de segurança

Embora o servidor local GraphQL MCP deva ser implementado apenas para fins de desenvolvimento, conforme descrito neste tutorial, está implementado com transporte HTTP, tornando mais fácil usá-lo como ponto de partida para integrações cliente-servidor ou baseadas na web mais complexas. Se está a implementar servidores GraphQL MCP em produção:

Usar o Cofre da Chave do Azure para armazenar segredos em vez de .env arquivos
Implementar as regras adequadas de autorização, segurança de rede e firewall
Habilitar o log de auditoria para todas as consultas do GraphQL
Usar o Serviço de Aplicativo do Azure ou Instâncias de Contêiner para hospedagem
Implementar limitação de taxa e autenticação para os pontos de extremidade MCP
Alterne regularmente os segredos e certificados do cliente

Solução de problemas

Problemas e soluções comuns

Erros de autenticação

Verifique se o Registro do Aplicativo do Azure tem as permissões corretas
Verifique se os "service principals" estão habilitados no locatário do Fabric.
Assegure-se de que o segredo do seu cliente não está expirado

Falha na introspeção do esquema

Confirme se a introspeção está ativada nas configurações da API do GraphQL
Verifique se a URL do endpoint GraphQL está correta
Verificar a conectividade de rede com o seu Fabric workspace.

Agente de IA não reconhece ferramentas

Reinicie seu cliente de IA após alterações de configuração
Verifique se a URL do servidor MCP está acessível
Verifique se há mensagens de erro nos logs do servidor

Erros de execução de consulta

Revise o console do servidor para verificar se há consultas e erros registrados
Verifique se suas consultas correspondem ao esquema disponível
Verifique se você tem as permissões apropriadas para os dados solicitados

Feedback

Esta página foi útil?

Last updated on 2026-01-21

Partilhar via

Conecte agentes de IA à API de malha para GraphQL com um servidor MCP (Model Context Protocol) local

O que é o Model Context Protocol (MCP)?

Porque é que o GraphQL é ideal para MCP

Pré-requisitos

Etapa 1: Configurar o acesso da entidade de serviço

Passo 2: Ativar o GraphQL Introspection (requer administração do espaço de trabalho)

Passo 3: Configurar o servidor MCP do GraphQL

Clone o repositório de exemplo

Instalar dependências

Configurar variáveis de ambiente

Iniciar o servidor MCP GraphQL

Ferramentas MCP disponíveis

introspect-schema

query-graphql

Compreender o fluxo de trabalho

Passo 4: Teste o servidor GraphQL MCP

Verificar a integridade do servidor

Introspeção do esquema de teste

Testar uma consulta GraphQL

Etapa 5: Conectar agentes de IA

Copiloto do GitHub no Visual Studio Code

Cursor IDE

O que construíste

Considerações de segurança

Solução de problemas

Problemas e soluções comuns

Conteúdo relacionado

Feedback

Recursos adicionais

`introspect-schema`

`query-graphql`