Connecting AI Agents to Microsoft Fabric with GraphQL and MCP
A local MCP server lets an agent learn a Fabric GraphQL schema and then query warehouses, lakehouses and databases.
Giving an AI agent access to data usually means writing a connector for every table or query. Fabric GraphQL MCP takes a different route. Microsoft documents a local server that connects an agent to a Fabric GraphQL API through the Model Context Protocol (MCP), lets it learn the schema on its own and then query data in natural language.
This guide explains why GraphQL suits agents, how the server works, what setup involves, how to harden it and where it should not be used. It is written for data engineers and architects who want to test agent access to Fabric data without overpromising to the business.
Why GraphQL Suits AI Agents
A GraphQL API describes itself. Through introspection, a client can ask the API which types, fields and operations exist, so an agent can learn the data model at runtime instead of relying on hand-written tool definitions. Microsoft lists four reasons GraphQL fits MCP: schema introspection, flexible queries, type safety and efficient fetching.
| Property | What it gives an agent |
|---|---|
| Schema introspection | Discovers types, fields and relationships without manual documentation |
| Flexible queries | Requests exactly the data it needs in a single call |
| Strong typing | Understands data formats and constraints before it queries |
| Efficient fetching | Less over-fetching and under-fetching than many REST designs |
If you are new to the API itself, our guide to the Microsoft Fabric API for GraphQL explains how to expose Fabric data through it. It can expose Fabric data warehouses, SQL databases in Fabric, lakehouses and mirrored databases through their SQL analytics endpoints, and Azure SQL Database, with support for tables, views and stored procedures in SQL databases and warehouses. Every exposed table or view needs a primary key. Here we focus on the agent layer on top.
"GraphQL gives an agent a map. MCP gives it a way to walk it."
How the Local Server Works
The server is a simple local Node.js application from the Microsoft Fabric samples repository, described in a Microsoft Learn tutorial and on the Microsoft Fabric Updates blog. It uses HTTP transport, listens on your machine at port 3000, and acts as a translator between the agent and your GraphQL API. It exposes two tools:
| Tool | Purpose | Notes |
|---|---|---|
| introspect-schema | Retrieves the complete GraphQL schema | No parameters; must be called first |
| query-graphql | Executes GraphQL queries against your Fabric data | Takes a query string and optional variables; used for data retrieval and manipulation |
Because the agent reads the schema through the server, you do not define a separate MCP tool for each GraphQL type, query or mutation. When someone asks to "show me customers", the agent first learns that a customers type exists and which fields it has, then writes the query. Microsoft's tutorial follows the same pattern: ask the agent to introspect the schema first, then ask a question about the data in natural language, such as retrieving a list of customers.
What Setup Involves
The setup is short but touches identity, so involve your security team. Microsoft's tutorial needs Node.js, VS Code, a workspace with an API for GraphQL item and the following steps:
Enabling introspection exposes schema information to everyone with access to the API endpoint. Review what the API exposes before you turn it on, and expose only the objects and columns an agent needs. Microsoft notes that exporting the schema as a file works even when introspection is off.
GraphQL MCP vs Other Fabric MCP Options
Microsoft now ships several MCP servers, and this one is for querying data through a GraphQL API you define. Choose by the job:
| Option | Best for | Data access | Maturity |
|---|---|---|---|
| GraphQL MCP sample | Agents querying a data API you control | Warehouses, lakehouses, databases via GraphQL | Tutorial and sample for development |
| Fabric IQ MCP | Agents asking governed BI questions | Power BI semantic models via DAX, read-only | Generally available |
| Core MCP | Managing workspaces, items and roles | No table data | Status not stated in overview |
| Local Fabric MCP | Building solutions, OneLake files, pipelines | OneLake files and item operations | Open source, development-focused |
See our guides to the Fabric IQ MCP server and the Fabric Core MCP server for the other two.
Security: From Demo to Production
Microsoft is explicit that this server is for development and learning. It authenticates with a service principal, so every question runs with that app's rights, not the asker's. That makes least privilege essential. Microsoft's production guidance lists six steps:
| Concern | Recommended action |
|---|---|
| Secrets | Store them in Azure Key Vault instead of environment files |
| Access | Implement authorization, network security and firewall rules |
| Auditing | Enable audit logging for all GraphQL queries |
| Hosting | Use a managed host such as Azure App Service or Container Instances |
| Abuse | Add rate limiting and authentication to the MCP endpoints |
| Rotation | Rotate client secrets and certificates regularly |
One detail deserves attention: the query tool is documented for data retrieval and manipulation, so an agent can run GraphQL mutations wherever the API exposes them. Sources exposed through a SQL analytics endpoint are read-only, but warehouses and SQL databases can accept writes. We would add two practices of our own: expose only the objects and mutations an agent genuinely needs, and scope the service principal to a workspace that holds only the data the agent should reach.
Troubleshooting Checklist
| Problem | First checks |
|---|---|
| Authentication errors | App registration permissions, service principals enabled in the tenant, client secret not expired |
| Schema introspection fails | Introspection enabled, correct endpoint URL, network access to the workspace |
| Agent does not see the tools | Restart the client, confirm the server address responds, check server logs |
| Query errors | Review logged queries, match the schema and confirm permissions on the requested data |
Where This Pattern Pays Off
The best fit is exploration and prototyping: a data engineer asks questions of a new GraphQL API, a developer checks which fields exist, or a team demonstrates conversational access to operational data before investing in a full application. For governed BI questions, a semantic model is usually the better foundation, because measures and security are already defined there.
A useful test is to run the same question two ways. Ask the agent directly through GraphQL, then ask through a semantic model. Differences in the answers usually reveal missing definitions, and that finding is often worth more than the demo itself.
- GraphQL introspection lets an agent learn a data model at runtime, so two generic tools can serve many questions.
- The local server exposes introspect-schema and query-graphql, and Microsoft describes it as for development and learning.
- Setup needs a service principal, a tenant admin to allow service principals, a workspace admin to enable introspection and local server configuration.
- Production use needs Key Vault secrets, network controls, audit logging, rate limiting and secret rotation.
- For governed BI questions, a Power BI semantic model with Fabric IQ MCP is usually the better fit.
Numlytics builds Fabric data platforms and the data engineering pipelines behind them. Speak with a certified consultant to scope an agent access pilot.