The BI Pixie MCP Server lets AI assistants such as Claude, GitHub Copilot, Codex, Microsoft Fabric data agents, and Azure AI Foundry answer questions about how your Power BI reports are actually used, in plain language. Because BI Pixie is self-hosted, the server runs entirely inside your own organization. It reads only the BI Pixie telemetry in your own workspace, the numbers it returns match your BI Pixie Dashboard exactly, and it is strictly read-only. It can never change, delete, or refresh your data, and your engagement data never leaves your tenant.

What is 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 own BI Pixie semantic model. No DAX, no exports.

Two ways to run it

You can run the server two ways, and both keep your data inside your organization. Almost everyone starts with the local install, then asks their Azure team to deploy the remote option to run it in production for AI agents and teams.

  • Local (start here). Install it on your own machine and sign in as yourself. No service principal is involved, and the server can only reach data you can already see in Power BI. Best for an individual analyst or admin, and where everyone begins. See Path A below.
  • Remote (run it in production). Hosted in your own tenant as part of your BI Pixie Azure Deployment, so AI agents in production workflows can query usage data on their own, and so Microsoft Fabric data agents, Azure AI Foundry, and your team can reach it with no local install. Your Azure team deploys it. See Path B below.

Both paths use the same package and the same read-only tools. They differ only in where the server runs and how it signs in. The remote path is an Azure Deployment capability and is not available on the Power Platform (Starter) deployment.

Ground your data agent in real human usage

When a data agent turns a question into DAX against a mission-critical model, it has to guess which column and which value the user means. Point it at the BI Pixie MCP server first: audit_overview (with group_by="column") ranks columns by how often people actually select and filter them, and audit_column_values returns a column's most-selected values, so the agent picks the column and the values real users rely on instead of guessing. This is the kind of grounding you want in a hosted, always-on deployment where agents run on their own. These tools count BI Pixie's captured data-selection events (slicer, filter, cross-filter, and drill selections), not raw clicks on individual visuals, and every result carries a freshness footer.

What you can ask

Once connected, 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 is my stickiness (DAU over MAU)?"
  • "Which pages in the Executive Dashboard get the most clicks and time spent?"
  • "What is 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 agent groups by the right one?" (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?" (ranks the column's values by what people actually select)

Tip: ask your assistant to "suggest questions". The server ships a built-in menu of example questions grouped by topic, so you can explore what is available.

Path A: Local install

The local install runs the server on your own machine and signs you in with your own Microsoft account. It needs no service principal and no administrator setup beyond a single tenant setting.

Before you start

  • An active BI Pixie license and a deployed BI Pixie semantic model, the same model behind your BI Pixie Dashboard.
  • Python 3.12 or later on your machine.
  • The Azure CLI, for the simplest sign-in (az login).
  • One Power BI admin setting: "Dataset Execute Queries REST API" enabled (Power BI Admin portal > Tenant settings > Integration settings). This is the single most common setup blocker for the local path. If it is off, queries fail with a permission error. The local path needs no other admin toggle and no service principal.
  • Normal Power BI access to the workspace that holds the model (Viewer, Member, or whatever the model requires), granted the usual way under Manage access. This is per-user access, not a service-principal enrollment.
  • Three values that identify your data: your Microsoft Entra tenant, the workspace that holds the BI Pixie model, and the model name (BI Pixie). You can use the workspace display name instead of its GUID.

Step 1: Install

Install from PyPI. 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

Using VS Code? Register it in one click, 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). On the local path you point it at your own Entra tenant and your own workspace. The simplest setup reuses your existing Azure CLI sign-in, with no app registration and no secret. Create a .env file with these four values:

BIPIXIE_MCP_TENANT_ID=<your-entra-tenant-guid>
BIPIXIE_MCP_WORKSPACE_NAME=<workspace that holds the BI Pixie model>
BIPIXIE_MCP_DATASET_NAME=BI Pixie
BIPIXIE_MCP_AUTH_MODE=azure_cli

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. Prefer GUIDs? Set BIPIXIE_MCP_WORKSPACE_ID instead of the workspace name.

No need to hunt for IDs. The settings above use display names, so you do not have to copy GUIDs from the Power BI portal. After the server connects, you can ask your assistant to list your workspaces and BI Pixie models and pick one, then switch between them at any time.

Not using the Azure CLI?

Set BIPIXIE_MCP_AUTH_MODE=device_code instead. Because you are self-hosted, you register a public-client Entra app in your own tenant, add its client ID as BIPIXIE_MCP_CLIENT_ID, and the first time you use the server it prints a short sign-in code to paste into your browser. The app needs only the delegated Power BI Service > Dataset.Read.All permission. No client secret and no admin consent are required for this local flow. Either way, the server runs as you, so it can only reach data you already have access to in Power BI.

Step 3: Register with your assistant

Claude Code, Claude Desktop, or Cursor

Add the server to your project's .mcp.json:

{
  "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",
        "BIPIXIE_MCP_AUTH_MODE": "azure_cli"
      }
    }
  }
}

VS Code

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

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

Path B: Remote (hosted in your own tenant)

Just as your BI Pixie Azure Deployment stands up a serverless web service (the send_event and activity_logs Function App) inside your subscription, the MCP server can run as another endpoint you host in your own managed resource group. It is delivered as a small container that exposes a single secure HTTP endpoint, deployed alongside the rest of your BI Pixie resources. AI assistants reach it remotely over HTTP, but it stays governed by your own identity and network controls, and it reads only your own workspace's BI Pixie telemetry. The data never leaves your organization.

Use the remote path when AI agents in production workflows need always-on access to usage data, or when Microsoft Fabric data agents, Azure AI Foundry, or a whole team should reach it without anyone installing anything locally. This is an Azure Deployment capability. It is not available on the Power Platform (Starter) deployment.

How the hosted server signs in

A hosted server has no interactive user to sign in, so instead of running as a person it runs as an application identity in your own tenant. You have two options:

  • Managed identity (recommended). The Azure-assigned identity of the hosted container authenticates automatically. There is no app registration to create and no secret to manage. You only need to grant the identity access to your workspace.
  • Service principal. A confidential-client Entra app registration in your tenant, with the Power BI Service > Dataset.Read.All application permission, admin consent, and a client secret stored as a Key Vault reference (BIPIXIE_MCP_CLIENT_SECRET). Use this if your governance requires an explicit app registration rather than a managed identity.

Important: the remote path is the only place service-principal infrastructure applies. For these two application identities, a Power BI admin must enable a second tenant setting, "Allow service principals to use Power BI APIs" (Power BI Admin portal > Tenant settings > Developer settings), in addition to the "Dataset Execute Queries REST API" setting from the local path. The local install never needs that toggle.

Deploying the remote server

The hosted MCP server deploys into your own subscription, the same way the rest of BI Pixie does. At a high level:

  1. Provision the MCP container in your managed resource group, alongside your existing BI Pixie resources. It is set to BIPIXIE_MCP_TRANSPORT=streamable-http so it serves a single POST /mcp endpoint, and to BIPIXIE_MCP_AUTH_MODE=managed_identity for keyless sign-in.
  2. Point it at the workspace and model that hold your BI Pixie data, using BIPIXIE_MCP_WORKSPACE_ID and BIPIXIE_MCP_DATASET_ID (or the matching name values). The tenant is your own tenant.
  3. Grant the deployment's managed identity (or service principal) the Member role on the workspace under Manage access. Member grants the Read and Build rights the server needs on the dataset.
  4. Have a Power BI admin enable both tenant settings noted above: "Dataset Execute Queries REST API" and "Allow service principals to use Power BI APIs".
  5. Retrieve the endpoint URL of the deployed container (it ends in /mcp) and register it with your AI assistants, Fabric data agents, or Azure AI Foundry as a remote MCP server, using Microsoft Entra authentication.

For the step-by-step deployment of your BI Pixie Azure resources, see Deploy BI Pixie on Azure. If you would like help wiring the remote MCP endpoint into an existing deployment, contact us and we will walk you through it.

Note: as with every BI Pixie Azure resource, we, as the publisher, have no access to your deployed application or its data. You own and host the infrastructure.

Switch workspaces while you chat

If you manage several BI Pixie models, you do not need to reconfigure to move between them on the local install. Just ask:

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

The switch lasts for the session and resets when you restart. You only ever see workspaces and models your own Power BI account can already access. This applies to the local install. A remote, hosted server stays pinned to the single workspace and model it was deployed for.

Privacy and security

  • Stays in your tenant. Whether you run it locally or host it in your Azure subscription, the server reads only your own workspace's BI Pixie telemetry, and your engagement data never leaves your organization.
  • Read-only. The server can only run read queries. It can never change, delete, or refresh your data, and write commands are rejected before they reach Power BI.
  • Scoped to one model. Every tool is scoped to the single configured workspace and dataset. Callers cannot target a different workspace or dataset.
  • Runs as a known identity. Locally it uses your own Microsoft sign-in. When hosted, it uses your own managed identity or app registration, so it can only reach data that identity is permitted to see.
  • No personal data by default. User names and IP addresses are stripped from every result unless an administrator explicitly enables them after a privacy review.
  • 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).

Troubleshooting

  • Queries fail with a permission error (403): the "Dataset Execute Queries REST API" tenant setting is off, or the identity running the server is not a Member of the workspace. Ask your Power BI admin to enable the setting and confirm workspace access.
  • The hosted server cannot sign in: the "Allow service principals to use Power BI APIs" tenant setting must be on for the managed-identity and service-principal modes, and the identity must be a workspace Member. The local install does not use this setting.
  • "Workspace or dataset not found": check the workspace name and confirm the model is named BI Pixie (or set BIPIXIE_MCP_DATASET_NAME to your model's actual name).
  • Wrong data or empty results: confirm BIPIXIE_MCP_TENANT_ID matches your own tenant, where your Power BI workspace lives.

What's Next

Explore the data the assistant queries: review the Metrics Reference to learn what each measure means, then walk through your dashboard to see the same numbers in context.

Related