FabricIQ stdio MCP Server

Exposes a published Microsoft Fabric Data Agent as a native MCP tool (query_fabric_agent) over stdio, so an MCP client (VS Code, GitHub Copilot CLI, Microsoft Scout, etc.) can call it directly instead of shelling out to a script per question.

This is the sibling project to foundryiq-rfp-kb — same design pattern (stdio MCP server, fresh Azure CLI token per call, per-workspace config.json), but targets a Fabric Data Agent's OpenAI-compatible Assistants endpoint instead of an Azure AI Search knowledge base.

A fresh Azure AD access token (scoped to https://api.fabric.microsoft.com) is minted on every tool call via the Azure CLI (az account get-access-token) — nothing is hardcoded and the token never goes stale.

What it calls

The tool talks directly to the Fabric Data Agent's OpenAI-compatible Assistants API (this skips the Foundry "connected tool" hop, which can add 10-15 min of latency/timeouts when the agent is invoked indirectly):

https://api.fabric.microsoft.com/v1/workspaces/<ws>/dataagents/<id>/aiassistant/openai

Protocol per query (api-version=2024-05-01-preview):

1. assistants.create(model="not used") — model field is ignored by Fabric
2. threads.create()
3. threads.messages.create(role="user", content=question)
4. threads.runs.create(assistant_id=...)
5. poll runs.retrieve until status is terminal
6. threads.messages.list(order="desc") → latest assistant message
7. threads.delete — cleanup

Prerequisites

• Python 3.10+
• Azure CLI installed and logged in:

  az login
  

  Your account needs at least Viewer access on the Fabric workspace hosting the data agent (and read access to its underlying data sources). The server requests a token for the workspace's specific tenant, so it works even if that tenant differs from your CLI's active tenant/subscription.

Setup

1. Create and activate a virtual environment:

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Copy config.example.json to config.json and fill in your Fabric data agent details:

   Copy-Item config.example.json config.json
   

   {
     "endpoint": "https://api.fabric.microsoft.com/v1/workspaces/<ws>/dataagents/<id>/aiassistant/openai",
     "api_version": "2024-05-01-preview",
     "token_resource": "https://api.fabric.microsoft.com",
     "tenant_id": "<tenant-guid>",
     "subscription_id": "",
     "poll_timeout": 600,
     "poll_interval": 3
   }
   

   endpoint is the published URL from the data agent's Publish pane in Fabric (ends in /aiassistant/openai). tenant_id is the tenant where the Fabric workspace lives — set it whenever that differs from your CLI's default login context (prevents cross-tenant 401 errors); subscription_id is an optional fallback used only when tenant_id is empty (the two are mutually exclusive for az account get-access-token). config.json is gitignored — it holds your real values and should never be committed.

Running standalone (sanity check)

The server speaks MCP JSON-RPC over stdio, so running it directly will just block waiting for input on stdin — that's expected:

.\.venv\Scripts\python.exe fabriciq_mcp_server.py --config config.json

Press Ctrl+C to stop. This only confirms the process starts without import/config errors; normally an MCP client launches and drives it.

You can also run a one-shot CLI query without an MCP client, for a quick smoke test:

.\.venv\Scripts\python.exe fabriciq_query.py "What was the average LTIFR across completed manufacturing projects?"

Registering with an MCP client

VS Code (mcp.json)

A .vscode/mcp.json is already included in this repo:

{
  "servers": {
    "fabriciq": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/Scripts/python.exe",
      "args": [
        "${workspaceFolder}/fabriciq_mcp_server.py",
        "--config",
        "${workspaceFolder}/config.json"
      ]
    }
  }
}

GitHub Copilot CLI (and Microsoft Scout, which rides on it)

The Copilot CLI reads its MCP server registrations from ~/.copilot/mcp-config.json (i.e. C:\Users\<you>\.copilot\mcp-config.json on Windows). Add a fabriciq entry there alongside any existing servers (e.g. foundryiq):

{
  "mcpServers": {
    "fabriciq": {
      "type": "local",
      "command": "C:\\Users\\sansri\\stdio-mcpservers\\fabriciq-rfp-kpis-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\sansri\\stdio-mcpservers\\fabriciq-rfp-kpis-mcp\\fabriciq_mcp_server.py",
        "--config",
        "C:\\Users\\sansri\\stdio-mcpservers\\fabriciq-rfp-kpis-mcp\\config.json"
      ],
      "tools": ["query_fabric_agent"]
    }
  }
}

Note the schema differs from VS Code's mcp.json: Copilot CLI uses "mcpServers" (not "servers") and "type": "local" (not "stdio"), but the mechanism is identical — a local subprocess over stdin/stdout, no URL/port involved. Restart Scout / start a new Copilot CLI session after editing this file for the change to take effect.

Microsoft Scout "Add MCP Server" dialog (GUI alternative)

Scout also has a GUI front-end for the same mcp-config.json — if you'd rather not hand-edit the file, use its Add MCP Server dialog instead (check first whether fabriciq already shows up in Scout's server list from the file edit above; if so, skip this to avoid a duplicate registration):

• Name: fabriciq-rfp-kpis-mcp
• Remote/Local: Command
• Command (paste as one combined string):

  C:\Users\sansri\stdio-mcpservers\fabriciq-rfp-kpis-mcp\.venv\Scripts\python.exe C:\Users\sansri\stdio-mcpservers\fabriciq-rfp-kpis-mcp\fabriciq_mcp_server.py --config C:\Users\sansri\stdio-mcpservers\fabriciq-rfp-kpis-mcp\config.json
  

• Environment variables: leave blank (auth comes from your existing az login session, not env vars)
• Tool-call timeout: the Fabric Assistants API run can take noticeably longer than a search retrieval. Bump this above the default (~60s) — 120–180s is a reasonable starting point, or match poll_timeout from config.json (default 600s) if Scout allows it.

Microsoft Scout skill (SKILL.md)

This repo includes SKILL.md — a Scout skill that teaches the agent how to use the registered fabriciq-rfp-kpis-mcp-query_fabric_agent MCP tool correctly (call it directly instead of shelling out, when to use it vs. a document/search knowledge base, treat a "no exact match" reply as valid free text rather than an error, never fabricate numbers, etc.).

Registering the MCP server (steps above) is not enough on its own — Scout needs this skill imported separately so the agent knows these usage rules exist and when to invoke the tool. Two things have to both be true for Scout to use this correctly:

1. The fabriciq MCP server is registered in ~/.copilot/mcp-config.json (see the GitHub Copilot CLI section above) — this is what makes the fabriciq-rfp-kpis-mcp-query_fabric_agent tool exist at all.
2. SKILL.md is imported into Scout's Skills/Extensions. Add this skill via Scout's extensions/skills UI (import from this repo path) so the skill's name/description frontmatter is indexed and Scout knows to route Fabric/KPI questions through this tool with the correct calling convention.

After importing, restart Scout (or start a new session) so it re-discovers both the MCP tool and the skill.

Other MCP clients

Point the client's server registration at the same venv Python + script + --config path shown above. Use absolute paths so the server resolves correctly regardless of the client's working directory.

Config resolution order

--config flag → FABRICIQ_CONFIG env var → config.json in the process's current working directory. Individual FABRICIQ_* env vars (FABRICIQ_ENDPOINT, FABRICIQ_TENANT_ID, FABRICIQ_SUBSCRIPTION_ID, FABRICIQ_API_VERSION, FABRICIQ_TOKEN_RESOURCE, FABRICIQ_POLL_TIMEOUT, FABRICIQ_POLL_INTERVAL) override individual fields on top of whatever config file was loaded.

Exposed tool

• query_fabric_agent(question: str) -> str — runs the Fabric Data Agent's Assistants-API conversation and returns the raw text answer. Intended for quantified project intelligence: KPI outcomes (OEE, LTIFR, TRIR, defect rates), financial data (cost variance, gross margin, change orders), risk register entries, milestone schedule data, certifications, client satisfaction scores. Not intended for narrative case-study text — use a document/search knowledge base (like foundryiq-rfp-kb) for that. A "couldn't find matching data" reply is valid free text from the agent, not a structural error — the caller decides what it means.

Troubleshooting

• Failed to acquire Fabric access token. Run 'az login' first. — your CLI session expired or doesn't have access to the tenant/subscription in config.json. Re-run az login (and az login --tenant <tenant_id> if needed).
• 401 / authentication failed — check tenant_id and that your account has access to the Fabric workspace hosting the data agent.
• 403 / access denied — ensure your account has at least Viewer permission on the Fabric workspace and read access to the data agent's underlying data sources.
• Fabric run polling exceeded <n>s — the agent took longer than poll_timeout (default 600s) to finish. Increase poll_timeout in config.json if your queries are genuinely heavy.
• No config found — ensure config.json exists next to the script, or pass --config <path> / set FABRICIQ_CONFIG.
• Stray output breaking the client — all logging must go to stderr (this is already handled in fabriciq_mcp_server.py); don't add print() calls that write to stdout.