Calling a Fabric Data Agent over MCP: Four Messages and One Real Decision
Every published Fabric Data Agent is now an MCP server. Calling it takes four JSON-RPC messages and a bearer token, from Python, Node, VS Code, or your own backend. The protocol is the easy part. The decision that matters is whose identity asks the question.
With the Assistants API gone, there is one supported way to call a Fabric Data Agent from code: its MCP endpoint. The good news is that it is smaller than what it replaced. No assistants, no threads, no runs, no polling. Four messages, one tool, one answer.
In the previous post I covered why this changed. This one is the practical half: what the endpoint expects, working clients in Python and Node, how to point VS Code or any MCP client at an agent, and the design decision hiding behind all of them. If you followed my earlier posts on service principals and embedding, this is the replacement for the client code in both.
- 4 JSON-RPC messages per question. initialize, initialized, list tools, call the tool. Skip the handshake and the endpoint will not talk to you.
- 1 tool, named after the agent. Described by the text you typed when you published. Discover it at runtime instead of hard-coding it.
- 10 to 60 s typical answer time. The agent plans, writes, and runs queries before it answers. Design every client around a pending state.
The Endpoint
Publish the agent, open its Settings, and go to the Model Context Protocol tab. You get the server URL, the tool name, the tool description, and a downloadable mcp.json. Or build the URL yourself from two IDs:
Three facts shape every client you will write against it:
- It is MCP over streamable HTTP, not REST. A plain POST with a question in the body fails. The client must do the MCP handshake first.
- Authentication is a Fabric bearer token for the scope
https://api.fabric.microsoft.com/.default, from a user or a service principal. The server does not support dynamic client registration, so clients that expect to register themselves automatically cannot connect. Your client gets its own token and attaches it. - It only exists once the agent is published. A correct URL for an unpublished agent still returns an error. If you see a 404, check that first.
The Four Messages
initialize
The client and server agree on a protocol version. The reply carries an Mcp-Session-Id header: send it on every request after this one.
notifications/initialized
A notification, with no id and no reply, telling the server the client is ready. Easy to forget, and the server will not go further without it.
tools/list
Returns exactly one tool: the agent, named after it and described by your publish description. Read the tool name and its string argument from the input schema instead of hard-coding them.
tools/call
Send the question as that argument. The agent plans, writes, and runs its queries, then answers in text and markdown tables. Expect 10 to 60 seconds.
Four messages, every time
That is the whole protocol, in every language. Two details trip up hand-written clients: send Accept: application/json, text/event-stream, and parse both plain JSON and server-sent events.
Python, with the MCP SDK
The official MCP Python SDK handles the handshake and the response format for you. With pip install mcp azure-identity and an az login, this is a complete client:
Note the long read timeout: the defaults in most HTTP stacks are shorter than a slow agent answer. To run unattended, swap AzureCliCredential for a service principal or managed identity credential from azure-identity. Nothing else changes.
Node, with No Dependencies
Writing the protocol by hand once is worth it, because it shows how little is there. This is the core of a Node 20+ client with nothing but fetch. It is also, almost line for line, what runs inside a server-side function in the next post.
For local testing, get the token with az account get-access-token --resource https://api.fabric.microsoft.com. In a server, it comes from a managed identity, a service principal, or a platform-provided identity. In a browser, it never comes from anywhere: more on that below.
VS Code and Other MCP Clients
Because the agent is a standard MCP server, you do not need to write a client at all to use it from a coding assistant. Drop the mcp.json from the agent's settings into .vscode/mcp.json, or add an HTTP server by URL. VS Code signs you in, and in agent mode the orchestrator calls your data agent whenever a question matches its tool description. That last part is why the publish description matters so much: it is the only thing the orchestrator reads before deciding to call.
Any other client that supports streamable HTTP with a custom Authorization header can use the same URL. If a client only supports automatic registration, it will not work against this server today.
The Real Decision: Whose Identity Asks
Once the protocol is out of the way, every integration comes down to one question. The agent queries your data with the permissions of whoever's token is on the request. That identity decides what data the answer can contain, who is accountable for the call, and what you have to secure. Here are the six ways to ask, and who is asking in each:
| Way | Who asks | Good for |
|---|---|---|
| Script (Python or Node) | You, via az login |
Testing an agent, batch questions, evaluation |
| Coding assistant (VS Code, any MCP client) | You, via interactive sign-in | Asking the data from where you already work |
| Copilot Studio | The signed-in user; source permissions carry through | Agents in Teams and Microsoft 365 |
| Fabric app function | The app's own identity | Apps built on Fabric, with no app registration or secret |
| Your own backend | A managed identity or service principal | Embedding in an existing product or site |
| Fabric portal | The signed-in user | People who already live in Fabric; nothing to build |
When the user asks
From the portal, Copilot Studio, or a coding assistant, the agent runs with the person's own token. Someone in the East gets company totals and East detail, because that is what the data platform lets them read.
A colleague asks the same question
Someone in the West gets totals and West detail. Same agent, same question, different answer, and that is correct. Permissions are enforced by the data, not by the agent.
When an application asks
Through a service principal, a managed identity, or a Fabric app's own identity, every question runs with the application's permissions. Every user now gets the same answer, built from everything that identity can read.
Scope the agent to what everyone may see
The clean fix lives in the agent, not the app: give it only the tables every user of the app is allowed to see. Or publish one agent per audience and decide on the server who may call which.
Neither case is a flaw. It is a design constraint, and there are two clean ways to live with it:
Scope the agent to shared data
Give the agent only tables that every user of the app is allowed to see. Aggregates, budgets, and published KPIs usually qualify. Row-level customer detail usually does not.
One agent per audience
When audiences need different data, publish different agents over different scopes, and let the app choose which agent a user may call. The routing rule becomes an authorization rule, so keep it on the server.
Rules That Hold for Every Client
- Never put the token in a browser. Ask from a server or function and send back only the answer. A Fabric token in client-side code is a token for everything that identity can reach, not just the agent.
- The asking identity needs two grants: access to the agent, and Read on each of the agent's data sources. A 403 almost always means one of the two is missing.
- Each call stands alone. The endpoint keeps no conversation between questions the way threads did. If a follow-up depends on the last answer, put the context in the question, or keep a short history yourself and send it along.
- Answers come back as text and markdown tables. No rendered charts. If you want a chart, ask for a predictable answer shape in the instructions and draw it yourself.
- Plan for slow answers. Set generous read timeouts and show a pending state. For very long questions, the endpoint supports the MCP tasks extension: the server hands back a task id, and the client polls
tasks/getinstead of holding the connection open. Clients that do not use tasks are unaffected. - Know where answers go. Microsoft notes that answers consumed through an MCP client may leave Fabric's compliance boundary and fall under that client's data handling terms. Check this with whoever owns compliance before you wire an agent into a third-party tool.
Migrating from the Assistants Pattern
If you have code from the earlier generation, the mapping is short:
| Assistants style | MCP |
|---|---|
.../aiassistant/openai base URL |
.../v1/mcp/workspaces/{ws}/dataagents/{id}/agent |
| Create assistant, create thread | initialize, notifications/initialized, tools/list |
| Add message, start run, poll run, list messages | One tools/call (or a task, for long questions) |
| Thread holds the conversation | Your app holds whatever context it needs |
| OpenAI client wrapping a Fabric token | The same Fabric token (https://api.fabric.microsoft.com/.default) as a plain bearer header |
The backend proxy pattern from the embedding post survives intact: browser to your backend, backend to the agent, secret on the server. Only the inside of the proxy changes, and it gets shorter.
When Something Fails
| Symptom | Usual cause |
|---|---|
| 401 | Token for the wrong scope or the wrong tenant. Sign in to the tenant that owns the workspace. |
| 403 | The identity can reach the workspace but not the agent, or lacks Read on a data source. |
| 404 | Wrong IDs, or the agent is not published. |
| Error on the first call, no answer | The client skipped the handshake, or did not send the session id it was given. |
| Timeout after 30 to 60 seconds | A default HTTP read timeout shorter than the agent's answer. Raise it, or use tasks. |
What's Next
Of the six ways to ask, one is new enough to deserve its own post: a Fabric app function that calls the agent as the app itself. No app registration, no client secret, no separate backend to host. That is next in the series.
Further Reading
- Data agent as Model Context Protocol server: Microsoft Learn, including the tasks extension and VS Code setup
- Model Context Protocol: the specification and SDKs
- What's New in Fabric Data Agents: the first post in this series