Connect AI Assistants (MCP Server)

The BI Pixie MCP Server lets AI assistants such as Claude, GitHub Copilot, Codex, Microsoft Fabric data agents, and Microsoft Foundry answer questions about how your Power BI reports are actually used, in plain language. It connects to your BI Pixie semantic model and returns numbers that match your BI Pixie Dashboard exactly. Its usage tools are read-only, so they never change, delete, or refresh your data.

Since bipixie-mcp 0.6.0 the BI Pixie MCP Server can also act on BI Pixie for you through the BI Pixie API: assess a semantic model, show and apply an optimization, add Pixies, run a benchmark, and more. It acts as you, within your own plan, and it shows you what it will do and asks you before it spends or changes anything. These tools come with the local install, and with a hosted deployment whose deployer turned them on. See Manage BI Pixie from your assistant below.

About the Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to tools and data. The BI Pixie MCP Server is one such tool. Once you register it with your AI assistant, you can ask usage questions in chat and the assistant pulls the answers straight from your BI Pixie data, with no DAX and no exports.

Two ways to run it

You can run the BI Pixie MCP Server in two ways. The local install is the place to start, and the remote option is how you run the server in production for AI agents and teams.

• Local (start here). You install the server on your own machine and sign in as yourself, with no service principal and no admin setup beyond one tenant setting. The steps below cover the local install.
• Remote (run it in production). Your IT or Azure team hosts the server as a secure, always-on endpoint, so that AI agents in production workflows can query usage data on their own, and so that Microsoft Fabric data agents, Microsoft Foundry, and your team can reach it with no local install. The Hosted option section below describes it.

What you can ask

Once the server is connected, you can ask your assistant questions like:

• "Which of my reports are used the most? Which are unused and could be retired?"
• "How many monthly and daily active users do I have, and what's my stickiness (DAU/MAU)?"
• "Which pages in the Executive Dashboard get the most clicks and time spent?"
• "What's my CSAT and NPS, and which reports are dragging satisfaction down?"
• "How has adoption trended over the last 90 days?"
• "How much time savings and financial benefit have users reported in surveys?"
• "Users keep asking about 'region'. Which audited column do people actually filter on most, so my data agent groups by the right one?" (BI Pixie resolves the name, then ranks columns by real selection activity.)
• "Before I write the DAX, what are the most-selected values of the Country column, the ones people deliberately click, so I can default my filter to them?" (BI Pixie ranks the column's values by what people actually select.)

Tip: when you ask your assistant to "suggest questions", BI Pixie returns a built-in menu of example questions grouped by topic, so you can explore what's available.

Before you start

The local install signs in as you and runs entirely under your own Power BI identity. You do not need a service principal, an admin-consented app registration, or the "Allow service principals to use Power BI APIs" tenant toggle for this local setup. There is exactly one piece of admin involvement, and it is the tenant setting called out below.

• An active BI Pixie license and a deployed BI Pixie semantic model. This is the same semantic model behind your BI Pixie Dashboard.
• Python 3.12 or later on your machine.
• The Azure CLI, for the simplest sign-in (az login).
• The one admin setting: "Dataset Execute Queries REST API" enabled (Power BI Admin portal > Tenant settings > Integration settings). This is the single tenant prerequisite for the local install. If it is off, every query fails with a permission error (403).
• Normal workspace access. Your signed-in account needs standard per-user access to the workspace (Viewer, Member, or whatever the semantic model requires), granted in the usual "Manage access" pane. This is ordinary Power BI access, not a service-principal enrollment.
• Three values that identify your data: your Microsoft Entra tenant, the workspace that holds the BI Pixie semantic model, and the semantic model name (BI Pixie Dashboard). You can use the workspace's display name instead of its GUID.

Step 1: Install

You install the server from PyPI, with no download or clone required.

# Zero-install runner (recommended), always fetches the latest version:
uvx bipixie-mcp

# Or install into your current Python environment:
pip install bipixie-mcp

In VS Code, you can register the server in one click and then add your settings in Step 2:

Install in VS Code

Step 2: Configure

The server reads its settings from environment variables (or from your AI assistant's MCP config). The simplest setup uses your existing Azure CLI sign-in, with no app registration and no secret. Create a .env file with these values. The last one, the BI Pixie API's application ID, turns on the tools that work with BI Pixie itself, described in Manage BI Pixie from your assistant. Leave it out for the read-only usage tools alone.

BIPIXIE_MCP_TENANT_ID=<your-entra-tenant-guid>
BIPIXIE_MCP_WORKSPACE_NAME=<workspace that holds the BI Pixie semantic model>
BIPIXIE_MCP_DATASET_NAME=BI Pixie Dashboard
BIPIXIE_MCP_AUTH_MODE=azure_cli
BIPIXIE_MCP_API_APP_ID=114a7e20-3796-4ddd-ab99-568a78b7759b

Then sign in once. The server reuses that session for every query:

az login

Tip: find your tenant GUID with az account show --query tenantId -o tsv. To use GUIDs, set BIPIXIE_MCP_WORKSPACE_ID instead of the workspace name.

You do not need to look up IDs. The settings above use display names, so you do not have to copy GUIDs from the Power BI portal. The guided setup can also write the .env for you when you run uvx bipixie-mcp setup and pick your workspace and semantic model from a menu. After the server connects, you can ask your assistant to list your workspaces and BI Pixie semantic models, pick one, and switch between them at any time.

Sign in without the Azure CLI

Set BIPIXIE_MCP_AUTH_MODE=device_code instead. This sign-in mode needs a public-client Entra app registered in your own tenant, with its client ID in BIPIXIE_MCP_CLIENT_ID. Microsoft counts an app your organization registers itself as coming from an unverified publisher, unless your organization has completed Microsoft's publisher verification for it. If your organization keeps Microsoft's recommended consent setting, Microsoft asks an administrator to approve such an app before anyone can sign in through it, and shows "Need admin approval" until then. The Azure CLI sign-in above needs no app and no approval. The first time you use the server, it prints a short sign-in code to paste into your browser. Either way, the server runs as you, so it can only reach data you already have access to in Power BI. The tools that act on BI Pixie, described in Manage BI Pixie from your assistant, sign in with the Azure CLI.

Step 3: Register with your assistant

Claude Code, Claude Desktop, or Cursor

In Claude Code and Cursor, add the server to your project's .mcp.json. Claude Desktop keeps its servers in its own configuration file instead: in Claude Desktop, open Settings, then Developer, and select Edit Config. The entry is the same in each:

{
  "mcpServers": {
    "bipixie": {
      "command": "uvx",
      "args": ["bipixie-mcp"],
      "env": {
        "BIPIXIE_MCP_TENANT_ID": "<your-entra-tenant-guid>",
        "BIPIXIE_MCP_WORKSPACE_NAME": "<your-workspace-name>",
        "BIPIXIE_MCP_DATASET_NAME": "BI Pixie Dashboard",
        "BIPIXIE_MCP_AUTH_MODE": "azure_cli",
        "BIPIXIE_MCP_API_APP_ID": "114a7e20-3796-4ddd-ab99-568a78b7759b"
      }
    }
  }
}

VS Code

Select Install in VS Code above, then add the same env block to .vscode/mcp.json so the server knows which workspace and semantic model to query.

Restart your assistant. Ask "describe the BI Pixie semantic model" to confirm the connection. You should see your tables, measures, and the data's freshness date.

Then ask "What is my BI Pixie plan?" to confirm that the BI Pixie tools work as you. You should see your account, your plan, and what is left of your allowances today and this month. If the first answer works and the second does not, check BIPIXIE_MCP_API_APP_ID and that you signed in with az login.

Switch workspaces while you chat

If you manage several BI Pixie semantic models, you don't need to reconfigure to move between them. On the local install, you can ask:

• "List my Power BI workspaces."
• "List the semantic models in <workspace>." (BI Pixie semantic models are flagged for you.)
• "Use the BI Pixie semantic model in <workspace>."

The switch lasts for the session and resets when you restart. You only ever see workspaces and semantic models your own Power BI account can already access. (This applies to the local install. A hosted deployment stays pinned to one semantic model.)

Manage BI Pixie from your assistant

Beside the usage tools, the server can carry a second set of tools that work with BI Pixie itself, through the BI Pixie API. They act as you, with your own permissions and your own plan, and within the same limits the portal applies. Every plan, Free included, can use them.

You can ask your assistant to read what BI Pixie knows:

• "What plan am I on, and how many assessments do I have left today?"
• "Which semantic models has BI Pixie assessed, and what is each one's AI Readiness score?"
• "Show me the last benchmark run on the Sales semantic model, and which AI answered it."
• "Which of my reports have Pixies?"

And to act for you:

• Assess a semantic model, several semantic models, or a data agent.
• Show what BI Pixie would change on a semantic model or a data agent, write it, and undo it. You can give your own wording for a description or for AI instructions in place of what BI Pixie proposed.
• Show every kind of optimization for a semantic model at once, write the whole bundle one kind at a time, and undo it.
• Choose which of your saved AIs BI Pixie writes optimizations with, or remove a saved AI. Adding an AI or replacing its key is done in AI setup, on the AI Assistants page of your portal, so your AI provider key never enters the conversation.
• Add Pixies to a report, or remove them.
• Write benchmark questions, save them, and run the benchmark.
• Create and run an A/B test, schedule assessments, and stop a run.

You are asked first

Anything that spends an allowance, claims a tracked item, changes an item, or deletes a result starts as a preview, and nothing is done yet. The preview names each item as your portal shows it, for example Assess the AI Readiness of the semantic model "Sales" in the workspace "Finance", says what it would use from your allowances in the numbers your portal shows, and ends with the item IDs so two items with the same name can be told apart. When your AI assistant can ask you a question on the server's behalf, BI Pixie puts the question straight to you there and acts on your answer in the same step. Only you see that question, so the answer tells your assistant that you were asked, what was asked, and what you answered, and a question you declined goes back to it too. Without that answer, an assistant has no way to know you were asked, and may tell you a change went ahead without your word. Where your assistant cannot put a question to you, it shows you the preview instead and acts only after you agree. That agreement is good once, for that one action, for ten minutes, and it exists only for assistants that cannot ask you. Showing what BI Pixie would change spends nothing and changes nothing, so it runs without asking.

What the question looks like

Every question names the item the way your portal does and ends with its ID, so two items with the same name can be told apart. These are the questions BI Pixie puts to you, with example names:

Each question also says what it would use from your allowances, in the numbers your portal shows, and what it would change. Showing what BI Pixie would change spends nothing and changes nothing, so it never asks.

How you are asked is your choice

Set BIPIXIE_MCP_CONFIRM in the same env block to choose how BI Pixie asks you:

• ask, the default: your AI assistant asks you when it can, as described above.
• chat: your AI assistant is never asked to put a question to you. The preview always comes back into the conversation, and BI Pixie acts once you agree there.
• off: nobody is asked. Each action happens at once, and its answer says what was done and what it used.

The choice is a setting in the local install only. No tool accepts it, so your AI assistant cannot choose to ask you less. A hosted deployment always uses chat, and cannot be set to off.

Turn them on

Sign in with the Azure CLI (az login) and add one setting, the BI Pixie API's application ID, to the env block from Step 2. The examples above already include it:

BIPIXIE_MCP_AUTH_MODE=azure_cli
BIPIXIE_MCP_API_APP_ID=114a7e20-3796-4ddd-ab99-568a78b7759b

One az login covers both sets of tools: nothing needs to be registered, and no administrator is asked to consent. Without the application ID, the server carries the read-only usage tools alone. To keep the BI Pixie tools that read but none that act, also set BIPIXIE_MCP_WRITE_TOOLS=false.

A hosted deployment carries these tools only when its deployer turns them on. It can offer the tools that read alone, or those and the tools that act. Either way they act for the person who signed in to it, never as the deployment itself. The first time a person uses one, they are asked once to allow it, for themselves only. After that, every action is agreed by that person in the conversation, each time, and a hosted deployment cannot be set to ask less. The settings its deployer needs are in the bipixie-mcp reference on PyPI.

Privacy and security

• Usage tools are read-only. They can only run read queries. They can never change, delete, or refresh your data, and write commands are rejected before they reach Power BI.
• BI Pixie tools ask first. A tool that acts on BI Pixie shows you a preview and acts only after you agree, once, for that one action. In the local install only you can change that, with BIPIXIE_MCP_CONFIRM. A hosted deployment always asks in the conversation.
• Runs as you. It uses your own Microsoft sign-in, so it can only reach data you're already permitted to see.
• Personal data follows your dashboard. BI Pixie collects viewer user names only when Capture user identity is on in Tracking Setup, and keeps each one as the email address, a masked ID or nothing, according to the choice on the Account page. Otherwise BI Pixie tells viewers apart by a masked IP address. When your BI Pixie semantic model holds user names or IP addresses, the local server returns them as your BI Pixie Dashboard shows them. Set BIPIXIE_MCP_PII_COLUMNS_ALLOWED=false to strip them from every result. A hosted deployment strips them by default.
• Claude never sees email addresses. When Claude runs a query through the BI Pixie connector, each value in the rows that looks like an email address reaches Claude as "(email address withheld)", with a note saying how many were withheld. The rest of each row reaches Claude as it is.
• Numbers you can trust. Answers come from the same validated measures as your BI Pixie Dashboard, so they match. Every answer is stamped with how fresh the data is (the most recent refresh date).

Hosted option (Fabric and Microsoft Foundry)

The same server can run hosted in your Azure environment as a secure, always-on endpoint, so AI agents in production workflows can query usage data on their own, and so Microsoft Fabric data agents, Microsoft Foundry, and your team can reach it without anyone installing anything locally. For step-by-step deployment, see Deploy the BI Pixie MCP Server, which walks your Azure team through standing up the remote endpoint as part of the BI Pixie managed app. The hosted option is an enterprise setup, and you can contact support to plan it. When its deployer turns them on, a hosted deployment also carries the tools that work with BI Pixie, acting for each person who signs in to it. Manage BI Pixie from your assistant says what each person is asked.

Unlike the local install, the hosted path runs under a shared identity rather than your personal sign-in, so it is the only path that involves a service principal or managed identity. The local install above needs none of the following. These requirements apply only to the hosted deployment:

• Admin tenant toggle. "Allow service principals to use Power BI APIs" (Power BI Admin portal > Tenant settings > Developer settings) must be on. This setting gates the service principal and managed identity modes only, never the local user-identity modes.
• Workspace role for the shared identity. The service principal or managed identity is added as a workspace Member or Admin so it can read and build the semantic model.
• Service principal mode. The service principal uses a confidential-client app registration with the Dataset.Read.All application permission, admin consent, and a client secret (stored as a Key Vault reference in Azure).
• Managed identity mode (preferred when hosted). A managed identity needs no app registration and no secret. The Azure-assigned identity is resolved automatically and needs the same workspace Member or Admin role as the service principal.

Troubleshooting

• Queries fail with a permission error (403): the "Dataset Execute Queries REST API" tenant setting is off, or your account isn't a Member of the workspace. Ask your Power BI admin to enable the setting and confirm your workspace access.
• An error that begins "No semantic model named": check the workspace name and confirm BIPIXIE_MCP_DATASET_NAME matches your semantic model's name. BI Pixie names it BI Pixie Dashboard when it installs the dashboard. If you renamed it, set the name you gave it.
• Wrong data or empty results: confirm BIPIXIE_MCP_TENANT_ID matches the tenant where your Power BI workspace lives.

Related

• BI Pixie Semantic Model: the tables and measures the assistant queries.
• BI Pixie Metrics: what each measure means.
• bipixie-mcp on PyPI: full technical reference covering every setting, all sign-in modes, the complete tool catalog, and hosted deployment.
• AI Readiness: where BI Pixie assesses whether your semantic models are ready for Copilot and data agents, and where you can benchmark Copilot, a Fabric data agent, or a generic AI agent against correct answers calculated from your own data.
• Contact Support: get help with setup.