Conectar agentes de IA à API do Fabric para GraphQL com um servidor MCP (Protocolo de Contexto de Modelo) local

Imagine perguntar ao GitHub Copilot "Mostrar todas as vendas do último trimestre" e fazer com que ele consulte automaticamente o data warehouse do Fabric, entenda o esquema e retorne os resultados, tudo sem escrever uma única linha do GraphQL. Este tutorial mostra como tornar isso possível.

Neste tutorial, você criará um servidor MCP do GraphQL local que atua como uma ponte entre agentes de IA e seus dados do Microsoft Fabric. No final, você tem um servidor de desenvolvimento de trabalho que permite que assistentes de IA como GitHub Copilot, Claude e outros agentes de IA consultem naturalmente seus dados do Fabric usando linguagem de conversa.

O que você vai realizar:

Configurar a autenticação para que o servidor MCP do GraphQL possa acessar o Fabric com segurança
Habilitar a introspecção de esquema para que os agentes de IA possam descobrir sua estrutura de dados automaticamente
Implantar um servidor MCP do GraphQL local que traduz a linguagem natural em consultas GraphQL
Conectar o GitHub Copilot ou outras ferramentas de IA para consultar seus dados conversacionalmente

O que é o Protocolo de Contexto de Modelo (MCP)?

O Protocolo de Contexto de Modelo (MCP) é um padrão para conectar assistentes de IA aos sistemas em que os dados residem, incluindo repositórios de conteúdo, ferramentas de negócios e ambientes de desenvolvimento. Seu objetivo é ajudar os modelos de fronteira a produzir respostas melhores e mais relevantes. Pense no MCP como uma porta USB-C para aplicativos 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 uma maneira padrão de integrar agentes de IA a sistemas externos. Isso torna o MCP uma opção ideal para conectar agentes de IA aos dados do Microsoft Fabric.

Por que o GraphQL é ideal para MCP

O GraphQL é adequado para integrações mcp porque:

Introspecção de esquema: os agentes de IA podem descobrir automaticamente estruturas e relações de dados disponíveis diretamente do esquema GraphQL
Consultas flexíveis: os agentes podem solicitar exatamente os dados necessários em uma única solicitação
Segurança de tipo: a tipagem forte ajuda os agentes de IA a entender os formatos e restrições de dados
Busca eficiente de dados: reduz a busca excessiva e a sub-busca de dados

A API do Microsoft Fabric para GraphQL facilita a exposição de lakehouses, data warehouses e bancos de dados do Fabric a agentes de IA por meio de uma interface do GraphQL padronizada. Embora a API para GraphQL já forneça recursos de consulta avançados, a configuração de uma conexão para agentes de IA pode não ser tão simples quanto poderia ser.

Com um servidor MCP do GraphQL local simples, os desenvolvedores podem usar agentes de IA para descobrir sua estrutura de dados do Fabric, entender o que está disponível e consultá-la usando linguagem natural, tudo por meio da interface MCP padronizada. Convenientemente, você não precisa definir uma ferramenta MCP separada no servidor para cada tipo, consulta ou mutação do GraphQL. O servidor MCP do GraphQL introspecta o esquema GraphQL capacitando os agentes de IA a entender todos os tipos e operações disponíveis desde o início.

Pré-requisitos

Antes de começar este tutorial, verifique se você tem:

Um workspace do Microsoft Fabric com permissões apropriadas. Um papel de administrador do espaço de trabalho é necessário para configurar service principals e habilitar a introspecção.
Um item de API para GraphQL criado e configurado. Consulte Criar e adicionar dados a uma API para GraphQL ou criar a API do GraphQL do banco de dados SQL no portal do Fabric.
Node.js instalado em seu computador de desenvolvimento (inclui npm)
Visual Studio Code instalado em seu computador de desenvolvimento

Observação

Não é administrador? Algumas etapas neste tutorial exigem permissões de administrador. Se você não for um administrador, ainda poderá concluir a maior parte do tutorial solicitando ao administrador que ajude com tarefas específicas. Cada etapa que requer permissões de administrador está claramente marcada.

Etapa 1: Configurar o acesso do principal do serviço

O que você está fazendo: Configurando credenciais de autenticação não interativas para que o servidor MCP do GraphQL possa acessar o Fabric sem exigir que um usuário entre sempre.

Por que isso importa: O servidor MCP do GraphQL é executado como um serviço em segundo plano que os agentes de IA chamam automaticamente. Ele precisa de sua própria identidade (um principal de serviço) com credenciais para se autenticar no Fabric em nome do seu aplicativo, não em nome de um usuário específico.

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

Criar um Registro de Aplicativo do Azure (qualquer usuário com permissões para criar registros de aplicativo no Microsoft Entra ID)
Adicionar um segredo do cliente em Certificados &segredos (qualquer usuário)
Habilitar principais de serviço em suas configurações de locatário (requer administrador de locatário do Fabric)
Conceder permissões à API e ao workspace do GraphQL (requer função de administrador ou colaborador do workspace)

Dica

Não é um administrador? Você pode concluir os dois primeiros itens por conta própria. Peça ao administrador do inquilino do Fabric para habilitar "Os principais de serviço podem usar APIs do Fabric" em Configurações do locatário>Configurações do desenvolvedor>Portal de administração. Para obter permissões de workspace, peça ao administrador do workspace para conceder acesso ao principal de serviço ao workspace ou a uma API GraphQL específica.

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

ID do locatário: encontrada em Microsoft Entra ID na seção Visão Geral>ID do Locatário
ID do cliente: Encontrado no seu Registro de Aplicativo emVisão geral>ID do Aplicativo (cliente)
Segredo do cliente: o valor secreto exibido quando você cria um novo segredo do cliente (copiar imediatamente — ele só é mostrado uma vez)

Etapa 2: Habilitar a introspecção do GraphQL (requer administrador do workspace)

O que você está fazendo: Habilitar a introspecção permite que o servidor MCP do GraphQL pergunte à API do GraphQL "Quais dados você tem?" e receba uma descrição completa de todos os tipos, campos e relações disponíveis.

Por que isso importa: Essa é a "mágica" que possibilita consultas de linguagem natural. Quando você pergunta ao Copilot "Mostrar-me clientes", o agente de IA usa primeiro a introspecção para descobrir que existe um customers tipo, quais campos ele tem e como consultá-lo. Sem introspecção, você precisaria documentar manualmente todo o esquema para a IA.

Importante

A introspecção deve ser habilitada para que o servidor MCP do GraphQL funcione. Isso é desabilitado por padrão no Fabric por motivos de segurança. Somente os administradores do workspace podem habilitar a introspecção. Se você não for um administrador, peça ao administrador do workspace para concluir esta etapa.

Siga o guia completo na API Microsoft Fabric para Introspecção e Exportação de Esquema do GraphQL para:

Habilitar a introspecção em suas configurações de API
Entender como funcionam as consultas de introspecção
Saiba mais sobre as opções de exportação de esquema

Depois que a introspecção estiver habilitada, o servidor MCP do GraphQL poderá consultar sua estrutura de esquema e disponibilizá-la aos agentes de IA.

Etapa 3: Configurar o servidor MCP do GraphQL

O que você está fazendo: Instalando e configurando um servidor de Node.js local que implementa o Protocolo de Contexto do Modelo. Esse servidor atua como um tradutor entre agentes de IA e sua API do GraphQL do Fabric.

Por que isso importa: O servidor MCP fornece uma interface padronizada que os agentes de IA entendem. Quando um agente de IA se conecta, ele pode descobrir quais ferramentas estão disponíveis (introspecção e consulta), chamar essas ferramentas e receber respostas, tudo sem que você grave código de integração personalizado para cada plataforma de IA.

Agora que você tem credenciais de autenticação (Etapa 1) e introspecção habilitadas (Etapa 2), você está pronto para configurar o servidor para usá-las.

Clone o repositório de amostra

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 espaço reservado por:

MICROSOFT_FABRIC_API_URL: o ponto de extremidade do GraphQL no portal do Fabric
MICROSOFT_FABRIC_TENANT_ID: sua ID do tenant do Azure
MICROSOFT_FABRIC_CLIENT_ID: ID do cliente de registro do aplicativo
MICROSOFT_FABRIC_CLIENT_SECRET: O segredo do cliente de registro de aplicativo

Iniciar o servidor MCP do GraphQL

node FabricGraphQL_MCP.js

O servidor é iniciado em http://localhost:3000 e, em seguida, 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 MCP do GraphQL fornece duas ferramentas principais:

`introspect-schema`

Finalidade: Recupera o esquema GraphQL completo
Parâmetros: Nenhum
Uso: deve ser chamado primeiro, antes de realizar 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

Noções básicas sobre o fluxo de trabalho

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

Descoberta de esquema: o agente de IA deve primeiro chamar a introspect-schema ferramenta para entender o esquema e os dados disponíveis
Planejamento de consultas: o Agente analisa sua solicitação de 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 resposta: o agente formata e apresenta os resultados

Etapa 4: Testar o servidor MCP do GraphQL

O que você está fazendo: Verificando se o servidor MCP pode se autenticar no Fabric, recuperar seu esquema e executar consultas antes de conectar agentes de IA.

Por que isso importa: O teste manual garante que tudo esteja configurado corretamente. Se esses testes forem aprovados, você saberá que os agentes de IA poderão se conectar com êxito na Etapa 5.

Verificar a integridade do servidor

Primeiro, confirme se o servidor está em execução e se pode autenticar no Fabric.

Usando 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"}

Introspecção do esquema de teste

Em seguida, verifique se o servidor pode recuperar seu esquema GraphQL por meio de introspecção. Isso chama a ferramenta MCP.

Usando 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 do GraphQL.

Testar uma consulta GraphQL

Por fim, teste a execução de uma consulta GraphQL real por meio do servidor MCP. Este exemplo consulta todos os nomes de tipo em seu esquema usando a query-graphql ferramenta MCP.

Usando 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 } } }"
      }
    }
  }'

Isso retorna uma lista de todos os tipos em seu esquema GraphQL.

Etapa 5: Conectar agentes de IA

O que você está fazendo: Configurando ferramentas de IA para usar o servidor MCP local como uma fonte de dados.

Por que isso importa: É aqui que tudo se junta. Uma vez conectados, os agentes de IA podem descobrir o esquema do Fabric por meio da introspecção e gerar consultas GraphQL com base em solicitações de linguagem natural. A IA manipula a sintaxe da consulta, basta fazer perguntas em inglês sem formatação.

GitHub Copilot no Visual Studio Code

Instalar a extensão do GitHub Copilot no VS Code

Defina o servidor MCP do GraphQL nas configurações do Copilot:

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

No chat do Copilot, primeiro peça para introspectar o esquema e, em seguida, tente fazer uma pergunta pertinente relacionada aos dados introspectados em linguagem natural, por exemplo:

Cursor IDE

Abrir configuraçõ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 introspectar o esquema e, em seguida, tente fazer uma pergunta pertinente relacionada aos dados introspectados em linguagem natural.

O que você criou

Parabéns! Agora você tem um servidor MCP do GraphQL em funcionamento que:

Autentica-se no Fabric usando credenciais de principal de serviço
Expõe o esquema de dados do Fabric por meio da introspecção
Converte solicitações de agente de IA em consultas do GraphQL
Retorna dados em um formato que os agentes de IA podem entender e apresentar

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

Descubra automaticamente quais dados estão disponíveis no workspace do Fabric
Gerar consultas do GraphQL corretas com base em perguntas de linguagem natural
Recuperar e formatar resultados sem que você grave nenhum código de consulta

Este servidor local destina-se ao desenvolvimento e ao aprendizado. As seções a seguir abordam considerações importantes sobre implantações de produção e cenários comuns de solução de problemas.

Considerações de segurança

Embora o servidor MCP do GraphQL local deva ser implementado apenas para fins de desenvolvimento, conforme descrito neste tutorial, ele é implementado com o transporte HTTP, facilitando o uso dele como ponto de partida para integrações mais complexas do servidor cliente ou da Web. Se você estiver implantando servidores MCP do GraphQL em produção:

Usar o Azure Key Vault para armazenar segredos em vez de .env arquivos
Implementar 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 a limitação de taxa e a autenticação para os endpoints do MCP
Rotacionar regularmente os segredos e certificados do cliente

Resolução de problemas

Problemas comuns e soluções

Erros de autenticação

Verifique se o Registro de Aplicativo do Azure tem as permissões corretas
Verifique se as entidades de serviço estão habilitadas em seu locatário do Fabric
Verifique se o segredo do cliente não expirou

Falha na introspecção de esquema

Confirme se a introspecção está habilitada nas configurações da API do GraphQL
Verifique se a URL do ponto de extremidade do GraphQL está correta
Verificar a conectividade de rede com o espaço de trabalho do Fabric

O agente de IA não reconhece ferramentas

Reiniciar seu cliente de IA após alterações de configuração
Verifique se a URL do servidor MCP está acessível
Verificar os logs do servidor em busca de mensagens de erro

Erros de execução de consulta

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

Comentários

Esta página foi útil?

Last updated on 2026-01-21

Compartilhar via

Conectar agentes de IA à API do Fabric para GraphQL com um servidor MCP (Protocolo de Contexto de Modelo) local

O que é o Protocolo de Contexto de Modelo (MCP)?

Por que o GraphQL é ideal para MCP

Pré-requisitos

Etapa 1: Configurar o acesso do principal do serviço

Etapa 2: Habilitar a introspecção do GraphQL (requer administrador do workspace)

Etapa 3: Configurar o servidor MCP do GraphQL

Clone o repositório de amostra

Instalar dependências

Configurar variáveis de ambiente

Iniciar o servidor MCP do GraphQL

Ferramentas MCP disponíveis

introspect-schema

query-graphql

Noções básicas sobre o fluxo de trabalho

Etapa 4: Testar o servidor MCP do GraphQL

Verificar a integridade do servidor

Introspecção do esquema de teste

Testar uma consulta GraphQL

Etapa 5: Conectar agentes de IA

GitHub Copilot no Visual Studio Code

Cursor IDE

O que você criou

Considerações de segurança

Resolução de problemas

Problemas comuns e soluções

Conteúdo relacionado

Comentários

Recursos adicionais

`introspect-schema`

`query-graphql`