Skip to content

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. 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.

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 own BI Pixie semantic model. You write no DAX and export nothing.

Two ways to run it

You can run the BI Pixie MCP Server in two ways, and both keep your data inside your organization. The local install is the place to start, and the remote option, which your Azure team deploys, is how you run the server 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. It suits an individual analyst or admin. Path A below describes the local install.
  • Remote (run it in production). The server is 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, Microsoft Foundry, and your team can reach it with no local install. Your Azure team deploys it. Path B below describes the remote option.

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 semantic model, it has to guess which column and which value the user means. The BI Pixie MCP Server can answer that question from real usage before the data agent writes its query. With data_audit and group_by="column", BI Pixie ranks columns by how often people actually select and filter them. With data_audit and view="column_values", BI Pixie returns a column's most-selected values. The data agent then picks the column and the values real users rely on instead of guessing. Grounding in real usage matters most in a hosted, always-on deployment where data agents run on their own. Both answers count the data-selection events BI Pixie captures (slicer, filter, cross-filter, and drill selections) rather than raw clicks on individual visuals, and every result carries a freshness footer.

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 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 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 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 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).
  • One Power BI 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 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 semantic model (Viewer, Member, or whatever the semantic 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 semantic model, and the semantic model name (BI Pixie). You can use the workspace 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

First run walks you through it

When you run uvx bipixie-mcp in a terminal with no settings yet, BI Pixie starts a short guided setup. It signs you in (reusing az login when available), lists the workspaces you can access, flags your BI Pixie semantic models, lets you pick one from a numbered menu, runs a quick test query to confirm it works, and saves a .env you can reuse. You can run the guided setup again any time with uvx bipixie-mcp setup. To configure it by hand, skip ahead to Step 2. (When your AI assistant launches the server, the server never prompts. It reads the settings described in Step 2.)

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). 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 semantic 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. 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. After the server connects, you can ask your assistant to list your workspaces and BI Pixie semantic models and pick one, then switch between them at any time.

Sign in without the Azure CLI

To sign in without the Azure CLI, set BIPIXIE_MCP_AUTH_MODE=device_code. This sign-in mode needs a public-client Entra app registered in your own tenant, with its client ID in BIPIXIE_MCP_CLIENT_ID. The app needs only the delegated Power BI Service > Dataset.Read.All permission, and no client secret. 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 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. With either sign-in mode, 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

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.

Path B: Remote (hosted in your own tenant)

Your BI Pixie Azure Deployment already runs a serverless web service in your subscription, the send_event and activity_logs Function App. The MCP server can run beside it as another endpoint you host in your own managed resource group. It comes 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, Microsoft 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. Reading your data needs no app registration and no secret. 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.

Who may call the server: the sign-in application (client) ID

The install form asks for a Sign-in application (client) ID when you choose to deploy the MCP server. It is the ID of an app registration that you create in your own Microsoft Entra organization, and it works as the lock on the server's door. Every request must carry a Microsoft Entra token issued by your organization for that app registration. A request without one is refused before it reaches the server.

This ID decides only who may call the server. It does not sign anyone in to BI Pixie, and it does not give the server access to your data. By default the server reads your BI Pixie semantic model as its own managed identity, through that identity's Member role on your workspace, which you grant after the install. The app registration then needs no secret and no API permissions. If you choose to read usage data as each person, the same app registration also carries each person's exchange.

Create the app registration before you install

Create it in the same Microsoft Entra organization you install BI Pixie into. Tokens from any other organization are refused. In the Azure portal:

  1. Open Microsoft Entra ID > App registrations > New registration. Give it a name such as BI Pixie MCP, choose Accounts in this organizational directory only, and select Register. Leave the redirect URI empty.
  2. On the Overview page, copy the Application (client) ID. This is the value the install form asks for.
  3. Open Expose an API. Next to Application ID URI, select Add and accept the suggested value, api://<your client ID>. Save it.
  4. Open Manifest and set requestedAccessTokenVersion to 2. In the older manifest view the same setting is named accessTokenAcceptedVersion. The server accepts only version 2.0 tokens, so a token of the older version is refused even when everything else is right.
  5. If people will call the server with their own sign-in, for example through OAuth identity passthrough in Microsoft Foundry, also select Expose an API > Add a scope and add a scope such as access_as_user. An agent that calls as its own managed identity needs no scope.

With the Azure CLI, the same steps are:

CLIENT_ID=$(az ad app create --display-name "BI Pixie MCP" \
  --sign-in-audience AzureADMyOrg --query appId -o tsv)
az ad sp create --id $CLIENT_ID
az ad app update --id $CLIENT_ID --identifier-uris "api://$CLIENT_ID"
az rest --method PATCH \
  --uri "https://graph.microsoft.com/v1.0/applications(appId='$CLIENT_ID')" \
  --body '{"api":{"requestedAccessTokenVersion":2}}'
echo $CLIENT_ID

Limit who may call it (optional). By default, anyone in your organization who can get a token for this app registration can call the server. To allow only named people and identities, open the app registration's Enterprise application, set Assignment required to Yes, and assign them. A managed identity can be assigned only through an app role, so define an app role on the app registration first.

Deploying the remote server

First, deploy the server. The remote MCP server is part of your BI Pixie Azure Deployment, so you stand it up by following the deployment instructions in Deploy BI Pixie on Azure. Have the sign-in application (client) ID ready: the install form requires it, and the deployment stops without it. The deployment provisions the MCP container in your managed resource group, alongside your other BI Pixie resources and already configured to serve a single secure POST /mcp endpoint with keyless (managed identity) sign-in. If you'd like help wiring the remote MCP endpoint into an existing deployment, contact us and we'll walk you through it.

Then, connect it. When the install finishes, open the deployment's Outputs in the Azure portal. Three of them belong to the MCP server:

  • mcpUrl is the server's address. It ends in /mcp.
  • mcpTokenAudience is api://<your client ID>, the audience an AI agent requests its token for.
  • mcpIdentityName is the name of the managed identity the server reads your data as.
  • mcpPostDeployStep says what to do next for the choice you made under Read usage data as.

You then connect the server to your data and your assistants in three steps:

  1. Grant access to your workspace. In the Power BI workspace that holds your BI Pixie semantic model, open Manage access and add the managed identity named in mcpIdentityName as a Member. Member gives it the Read and Build rights the server needs on your BI Pixie semantic model. The sign-in application plays no part here.
  2. Enable the two tenant settings. A Power BI admin turns on both "Dataset Execute Queries REST API" and "Allow service principals to use Power BI APIs" (Power BI Admin portal > Tenant settings).
  3. Register the endpoint. Add the mcpUrl address to your AI assistants, Fabric data agents, or Microsoft Foundry as a remote MCP server, using Microsoft Entra authentication. Where the agent asks for an audience, as Microsoft Foundry does, enter the mcpTokenAudience value. Where it asks for a scope, enter api://<your client ID>/.default, or api://<your client ID>/access_as_user when people call with their own sign-in. The agent then sends that token with every request, and the server accepts 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.

Read usage data as each person

The install form asks whose identity the server reads usage data with. The server's own identity is the default: every person who may call the server sees the same usage data, the data the managed identity can read. Each person's own identity reads as the person who is asking instead. Each person then sees only what their own Power BI access and row-level security allow, and the Power BI activity log records their name rather than the server's.

Reading as each person suits an organization that limits who sees whose usage data. It needs a person behind every call, so an agent that calls as its own identity, such as an Azure AI Foundry agent without OAuth identity passthrough or a scheduled agent, is refused with a sentence saying why. The choice is made at installation, and changing it takes a new installation.

What reading as each person needs

  1. A delegated Power BI permission on the sign-in app registration. Open API permissions > Add a permission > Power BI Service > Delegated permissions and add Dataset.Read.All. The access_as_user scope from the steps above is needed as well, because people call with their own sign-in. Add SemanticModel.ReadWrite.All from the same list too, so that an agent can read a semantic model's AI instructions. Do not grant it for your organization: the agent asks for it only when it first reads AI instructions, and each person consents to it for themselves then. Only a person who may edit a semantic model can read its AI instructions.
  2. A federated credential on the same app registration. It lets the server's managed identity prove who it is to Microsoft Entra ID, so the app registration needs no client secret. Open Certificates & secrets > Federated credentials > Add credential, choose Other issuer, and enter the mcpFederatedCredentialIssuer and mcpFederatedCredentialSubject values from the installation's outputs, with the audience api://AzureADTokenExchange.
  3. Read and Build for each person on the BI Pixie semantic model, which a workspace role such as Viewer with Build, or a direct share, gives them. The managed identity needs no workspace role.

The first time a person asks, Microsoft Entra ID may ask them to allow BI Pixie to read Power BI data for them. The agent shows them a link where they allow it for themselves, and the next question is answered. If your organization does not let people allow apps for themselves, the agent says so, and an administrator in your organization decides whether to allow it.

Add the hosted server to Claude as a connector

People in your organization can add the hosted MCP server to Claude as a connector, sign in with their own Microsoft account, and ask questions of the semantic models they can read. Every answer is read as the person who asked, so nobody sees data their own Power BI access does not already show them. The questions and answers pass between Claude and your own server. Nothing is sent to BI Pixie.

In Claude, this MCP server answers questions on semantic models and their usage in reports. The benchmark, assessments and account settings stay on BI Pixie's own connector.

When the install form offers it

The install form's AI Agent Access step offers Add this MCP server to Claude as a connector after Read usage data as. It is off by default, and with it off the install is exactly what it would otherwise be, including for Azure AI Foundry and Fabric data agent clients.

  • Read usage data as must be set to Each person's own identity. With the server's own identity, every person in Claude would read as one shared identity, so the form does not offer the connector.
  • It is offered with Public network access, with Restricted network access, and with an MCP server only install.
  • It is not offered with Private network access. Claude reaches the server from Anthropic's cloud, not from the person's computer, and a private network does not admit Anthropic's cloud, even when the person is on your VPN.

With Restricted network access, the MCP server also accepts requests from Anthropic's published outbound addresses, 160.79.104.0/21, beside your own allowed IP ranges, so that Claude can reach it. It still answers only people who sign in. The range is written into the template, so if Anthropic changes it, a new version of the managed app carries the change.

Prepare the sign-in application

Claude signs people in through the same sign-in application the install form asks for. Besides the steps in that section, the connector needs four more settings on it. You can make them before or after the install, but Claude cannot sign anyone in until they are in place.

  1. Add Claude's two callback addresses. Open Authentication > Add a platform > Web and add both https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback as redirect URIs. A sign-in application without them fails at the first sign-in in Claude.
  2. Add a scope named access. Open Expose an API > Add a scope, name it exactly access, and allow admins and users to consent. The server accepts a token from Claude only when it carries this scope.
  3. Add the federated credential. Open Certificates & secrets > Federated credentials > Add credential, choose Other issuer, and enter the mcpFederatedCredentialIssuer and mcpFederatedCredentialSubject values from the deployment's Outputs. The server then signs people in as the sign-in application through its own managed identity, so no client secret exists.
  4. Add the Power BI permissions. Open API permissions > Add a permission > Power BI Service > Delegated permissions and add Dataset.Read.All and SemanticModel.ReadWrite.All. Each person consents to Dataset.Read.All for themselves the first time they connect. Claude asks for SemanticModel.ReadWrite.All only when it first reads a semantic model's AI instructions, and each person consents to it for themselves then. Do not grant it for your organization. Only a person who may edit a semantic model can read its AI instructions.

Each person then needs Read and Build on the BI Pixie semantic model, as they would to open the BI Pixie Dashboard. The server's managed identity needs no workspace role in this mode.

Add the connector in Claude

  1. Copy the mcpUrl value from the deployment's Outputs. It ends in /mcp.
  2. In Claude, open Settings > Connectors and select Add custom connector. On a Team or Enterprise plan, an owner adds the connector for the organization first, and each person then connects to it.
  3. Enter a name such as BI Pixie usage and paste the mcpUrl value as the URL. Leave the OAuth client ID and secret empty: Claude registers itself with your server.
  4. Select Connect. Claude opens the Microsoft sign-in page of your own organization, where the person signs in and consents for themselves.

To confirm the connection, ask Claude "describe the BI Pixie semantic model". If Claude shows an error at sign-in instead, the redirect URIs or the access scope on the sign-in application are the usual cause.

Switch workspaces while you chat

If you manage several BI Pixie semantic models, you do not 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 remote, hosted server stays pinned to the single workspace and semantic 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 semantic model. Every tool is scoped to the single configured workspace and semantic model. Callers cannot target a different workspace or semantic model.
  • 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.
  • Personal data follows your dashboard. BI Pixie collects viewer user names only when include_user is true in bi_pixie_config.json, and it then keeps the email address, or a masked ID when MASK_USER_NAME is true on the function app. When include_user is false, it counts viewers 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.
  • 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 answers 401 Unauthorized: the caller's token was refused before the request reached the server. Check that the agent requests its token for mcpTokenAudience (or the scope api://<your client ID>/.default), that the token comes from the organization BI Pixie is installed in, and that the app registration's manifest sets requestedAccessTokenVersion to 2. See the sign-in application (client) ID.
  • 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.
  • An error that begins "No semantic model named": check the workspace name and confirm the semantic model is named BI Pixie, or set BIPIXIE_MCP_DATASET_NAME to your semantic 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

The Metrics Reference explains what each measure the assistant queries means, and the dashboard walkthrough shows the same numbers in context.

Related