Metadata-Version: 2.4
Name: bipixie-mcp
Version: 0.9.0
Summary: MCP server that gives AI agents read-only access to BI Pixie usage and engagement data via the Power BI REST executeQueries endpoint, and management tools over the BI Pixie API as the signed-in person
Author-email: DataChant <support@bipixie.com>
Maintainer-email: DataChant <support@bipixie.com>
License: MIT
Project-URL: Homepage, https://bipixie.com
Project-URL: Documentation, https://bipixie.com/docs/cloud/mcp-server/
Project-URL: Support, https://bipixie.com/docs/cloud/contact-support
Keywords: mcp,power-bi,bi-pixie,analytics,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp<3,>=2.11
Requires-Dist: msal>=1.28
Requires-Dist: azure-identity>=1.17
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-settings>=2.3
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: respx>=0.21; extra == "test"
Requires-Dist: PyYAML>=6; extra == "test"
Provides-Extra: dev
Requires-Dist: bipixie-mcp[test]; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# BI Pixie MCP Server

Ask your AI assistant how your Power BI reports are really used, and let it work in BI Pixie for you.

The BI Pixie MCP Server connects AI assistants such as Claude, GitHub Copilot in VS Code, Cursor, Codex, Microsoft Fabric data agents and Azure AI Foundry to your BI Pixie data through the [Model Context Protocol](https://modelcontextprotocol.io/). It carries **84 tools** in three families:

- **23 usage tools** answer questions about adoption, engagement, satisfaction, data auditing and AI Readiness from your BI Pixie semantic model. They are read-only, and their numbers match your BI Pixie Dashboard exactly.
- **4 navigation tools** let you switch to another workspace or semantic model while you chat (local install only).
- **57 management tools** work in BI Pixie as you, through the [BI Pixie API](https://bipixie.com/docs/api): read your account and plan, assess semantic models and data agents, preview and apply optimizations, add Pixies, run benchmarks and A/B tests. Anything that spends or changes something shows you a preview and asks you first. They come with the local install, and with a hosted deployment whose deployer turned them on (see Hosted deployment).

Full setup guide: [bipixie.com/docs/cloud/mcp-server](https://bipixie.com/docs/cloud/mcp-server/).

> **Note:** Requires an active BI Pixie license and an installed BI Pixie Dashboard. "BI Pixie" is a trademark of DataChant. This package is a client and grants no rights to the BI Pixie service or data.

---

## What you need

- **A BI Pixie license and the BI Pixie Dashboard installed** in a Power BI or Fabric workspace. The server reads the semantic model behind that dashboard.
- **Python 3.12 or later**, and [uv](https://docs.astral.sh/uv/) for the `uvx` command.
- **The [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)**, for the simplest sign-in (`az login`).
- **One Power BI tenant setting:** "Dataset Execute Queries REST API" turned on (Power BI Admin portal > Tenant settings > Integration settings). If it is off, every query fails with a permission error (403). This is the most common setup blocker, and it needs a Power BI administrator.
- **Ordinary access to the workspace** that holds the BI Pixie Dashboard, the same access you use to open the dashboard.

The local install signs in as you. It needs no app registration, no service principal and no administrator consent.

---

## Set up

### 1. Run the guided setup

```bash
uvx bipixie-mcp
```

Run in a terminal with no settings yet, this starts a short guided setup. It signs you in (reusing `az login` when it can), lists the workspaces you can open, flags your BI Pixie semantic models, lets you pick one from a numbered menu, runs a one-row test query, offers the BI Pixie API application ID for the management tools and confirms it by reading your BI Pixie account once, and writes a `.env` file with a ready-to-paste registration block. Run `uvx bipixie-mcp setup` to go through it again at any time.

When your AI assistant starts the server it never prompts; it reads the settings below instead. `bipixie-mcp --version` prints the version you have installed.

### 2. The settings

Five settings identify you, your data and the BI Pixie API:

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

- **Tenant:** your own Microsoft Entra tenant, the one that holds your Power BI workspace. `az account show --query tenantId -o tsv` prints it after `az login`.
- **Workspace:** its display name, or its GUID in `BIPIXIE_MCP_WORKSPACE_ID`.
- **Semantic model:** BI Pixie names it `BI Pixie Dashboard` when it installs the dashboard. Leave the setting out and the server looks for `BI Pixie Dashboard` or `BI Pixie` on its own.
- **Sign-in:** `azure_cli` reuses your `az login`. With `device_code`, the server prints a short code to paste into your browser on first use instead.
- **BI Pixie API application ID:** turns on the management tools. Without it the server carries the usage and navigation tools alone.

### 3. Register the server with your assistant

**Claude Code, Claude Desktop or Cursor.** Add it to your project's `.mcp.json`:

```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 Dashboard",
        "BIPIXIE_MCP_AUTH_MODE": "azure_cli",
        "BIPIXIE_MCP_API_APP_ID": "114a7e20-3796-4ddd-ab99-568a78b7759b"
      }
    }
  }
}
```

**VS Code.** Register it in one click, then add the same `env` block to `.vscode/mcp.json`:

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_BI_Pixie_MCP-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=bipixie&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22bipixie-mcp%22%5D%7D)

BI Pixie customers can also install it from the **AI Assistants** page of the BI Pixie portal, with the workspace and semantic model already filled in.

**Codex.** Add it to `~/.codex/config.toml`:

```toml
[mcp_servers.bipixie]
command = "uvx"
args = ["bipixie-mcp"]

[mcp_servers.bipixie.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"
```

### 4. Check that it works

Restart your assistant, then ask two questions:

1. **"Describe the BI Pixie semantic model."** You should see its tables, its measures and the date your data runs through. This confirms the usage tools reach your semantic model.
2. **"What is my BI Pixie plan?"** You should see your account, your plan and what is left of your allowances today and this month (`get_account`). This confirms the management tools reach the BI Pixie API as you.

If the first answer works and the second does not, check `BIPIXIE_MCP_API_APP_ID` and that you signed in with `az login`.

---

## What you can ask

- "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 DAU/MAU?"
- "Which pages in the Executive Dashboard get the most clicks and time spent?"
- "What are my CSAT and NPS, and which reports pull satisfaction down?"
- "Which columns of my semantic model do people filter on most?"
- "Which of my semantic models are ready for AI?"
- "Assess the Sales semantic model, then show me what BI Pixie would change."
- "Run the benchmark on my data agent and tell me which AI answered."

Ask your assistant to **"suggest questions"** for a menu of examples grouped by topic.

---

## Usage tools (23)

Read-only. They query your BI Pixie semantic model and change nothing. Every answer carries a freshness footer (`data_through`, the last date with data, and `last_refresh_utc`, the semantic model's last refresh), and the tools default to the 30 days before `data_through`. Pass `days=0` for all of your history.

| Tool | What it answers |
|------|-----------------|
| `suggest_questions` | Example questions grouped by topic, each naming the tool that answers it. Runs no query. |
| `describe_model` | The tables, measures and filterable columns of your BI Pixie semantic model, and how fresh its data is. |
| `list_reports` | Your tracked reports with sessions, hours, users and last activity. |
| `top_reports_by_usage` | Reports ranked by sessions, hours, users, interactive sessions, average session length or clicks, most or least used. |
| `report_usage_breakdown` | Across all reports: how many have Pixies, and how many are opened, interactive, passive or unused, and the same for pages, optionally per workspace. |
| `report_health` | One report's card: sessions, hours, average session length, interactive and passive sessions, users, CSAT and NPS. |
| `user_adoption` | MAU, DAU, DAU/MAU, WAU, engaged, new and returning users, as a summary or a trend. |
| `user_attrition` | Passive (at-risk) and engaged users, MAU, DAU, user attrition and last-time users. |
| `page_engagement` | Per page: sessions, time spent, interactions, slicer clicks, visual interactions and tooltip opens. |
| `visual_engagement` | Per visual: clicks, ranked, with how many visuals are certified, uncertified or risky. |
| `design_metrics` | Reports ranked by how they are built: complexity, usability and passivity scores, visuals, slicers, tooltip and drillthrough pages. |
| `field_usage` | Which columns and measures of your semantic model the report visuals use, and how often people click them. |
| `unused_fields` | Columns and measures on report visuals that nobody clicked in the period. |
| `feedback_summary` | CSAT, NPS, the sentiment split and survey results (time savings, financial gains), as a total, a breakdown or a trend. |
| `feedback_distribution` | How feedback clicks split across the smiley icons, with the overall CSAT. |
| `audit_overview` | Data auditing: which tables, columns or values people view or click most. |
| `audit_column_values` | The values of one audited column, ranked by views or clicks. |
| `audit_value_lookup` | Who viewed or clicked a value, when, and in which report and page. |
| `audit_resolve_entity` | Audited tables and columns whose names contain a word such as "product". |
| `audit_user_activity` | One person's data selections by date, report and page. |
| `rls_audit` | Row-level security health: users hitting no role or several roles, over-blocking, and rows that may be over-exposed. |
| `ai_readiness_scores` | Each semantic model's latest AI Readiness score and band, its change over time, and open findings. |
| `run_dax` | Any read-only `EVALUATE` DAX query, for questions the other tools do not cover. Write commands are refused before they reach Power BI. |

**Data auditing returns your business data.** The `audit_*` tools return the values people selected in your reports, such as a customer name, a region or a price. `BIPIXIE_MCP_PII_COLUMNS_ALLOWED` covers user names and IP addresses only, never those values. A value with a distinct count of 1 is a click on that value; a larger distinct count is a view of a span of values, so whether one value inside it was seen is approximate.

**AI Readiness results.** When your BI Pixie Dashboard holds AI Readiness results, `describe_model` says so and `ai_readiness_scores` ranks them. With data residency on, those results live in your own Lakehouse and are read through your semantic model only. No table holds an AI's answer to a benchmark question, a correct value or a DAX query, so no tool can return one.

## Navigation tools (4)

Local install only. Point the server at another workspace or semantic model without editing settings. A switch lasts until the server restarts, and you only ever see what your own Power BI account can open. Set `BIPIXIE_MCP_ALLOW_TARGET_SWITCHING=false` to keep the server on the configured semantic model.

| Tool | What it does |
|------|--------------|
| `list_workspaces` | Lists the Power BI workspaces you can open. |
| `list_datasets` | Lists the semantic models in a workspace and flags the BI Pixie ones. |
| `set_active_dataset` | Points every tool at another workspace and semantic model for this session. |
| `get_active_dataset` | Shows which workspace and semantic model the tools are reading, and how fresh it is. |

## Management tools (57)

Local install only, and only when signed in as a person (`azure_cli`, `device_code` or `interactive`). They act through the [BI Pixie API](https://bipixie.com/docs/api) as you, with your own permissions and your own plan, within the same limits the portal applies. Every plan, Free included, can use them. Each tool is one API call, and no token of yours is stored by BI Pixie.

**Reads.** These spend nothing.

| Ask your agent | Tool |
|---|---|
| What is my account, my plan, what do I have left today and this month | `get_account` |
| Which permissions I have given BI Pixie, and where to grant a missing one | `list_permissions` |
| Which reports and semantic models count as tracked items | `list_tracked_items` |
| Which semantic models BI Pixie knows, their AI Readiness score, their assessments | `list_semantic_models`, `get_semantic_model_readiness`, `list_assessments`, `get_assessment` |
| Which data agents BI Pixie knows, their readiness, their assessments | `list_data_agents`, `get_data_agent_readiness`, `list_data_agent_assessments`, `get_data_agent_assessment` |
| The saved benchmark questions, the benchmark runs, one scored run | `get_benchmark_questions`, `list_benchmark_runs`, `get_benchmark_run` |
| The A/B tests, one test, one run, a run's comparison, the tests an item is on | `list_ab_tests`, `get_ab_test`, `get_ab_test_run`, `get_ab_test_result`, `list_ab_tests_of_semantic_model`, `list_ab_tests_of_data_agent` |
| The assessment schedules | `list_schedules`, `get_schedule` |
| The reports in a workspace, or the reports built on a semantic model, and which have Pixies | `list_workspace_reports` |
| Whether a report has Pixies | `get_report_pixies` |
| The AIs my account has saved and the credentials they use (an account admin's; never a key) | `list_saved_ais` |
| What BI Pixie is doing for me, one operation, its result, wait for it to end | `list_operations`, `get_operation`, `get_operation_result`, `wait_for_operation` |

**Writes.** Set `BIPIXIE_MCP_WRITE_TOOLS=false` for a server that only reads.

| Ask your agent | Tool |
|---|---|
| Assess a semantic model, several of them, or a data agent | `assess_semantic_model`, `assess_semantic_models`, `assess_data_agent` |
| Show me what BI Pixie would change on a semantic model, then write it, then undo it | `preview_optimization`, `apply_optimization`, `revert_optimization` |
| The same for every kind of optimization at once: preview them all, write the ones I keep, undo them | `preview_optimization_bundle`, `apply_optimization_bundle`, `revert_optimization_bundle` |
| The same for a data agent's AI instructions and grounding | `preview_data_agent_optimization`, `apply_data_agent_optimization`, `revert_data_agent_optimization` |
| Add Pixies to a report or to several; remove them | `add_pixies`, `remove_pixies` |
| Write benchmark questions and show them to me, save them, check they can all be scored | `generate_benchmark_questions`, `save_benchmark_questions`, `check_benchmark_coverage` |
| Run the benchmark | `run_benchmark` |
| Create an A/B test and run it, run it again, rename it, delete it or one run | `create_ab_test`, `run_ab_test_again`, `update_ab_test`, `delete_ab_test`, `delete_ab_test_run` |
| Schedule assessments; stop a schedule | `put_schedule`, `delete_schedule` |
| Make a saved AI the one BI Pixie writes optimizations with; remove a saved AI | `make_saved_ai_the_writer`, `remove_saved_ai` |
| Stop a run | `cancel_operation` |

**You are asked first.** Every write that spends an allowance, claims a tracked item, changes an item or deletes a result answers a preview on its first call and does nothing: what it will do, to which item, and what it would spend, in the numbers your portal shows. The question names each item as your portal does, for example *Assess the AI Readiness of the semantic model "Sales" in the workspace "Finance"*, and ends with the ids, which tell apart two items with the same name. Where a name cannot be read, the question says the id instead. Where your AI assistant can ask you a question on the server's behalf, BI Pixie puts the question straight to you there, and one call does both. Only you see that question, so the answer tells your assistant what was asked and what you said: `askedThePerson`, `personAnswered`, and the question itself in `askedQuestion`. Without them an assistant has no way to know you were asked, and may report that the write went ahead unasked. A write you declined carries the question back too. Otherwise, where your assistant cannot ask you, the preview carries an agreement that it brings back on a second call once you agree. An agreement is good once, for that one action, for ten minutes, and an invented one is refused. The three optimization previews and the coverage check spend nothing and change nothing, so they answer at once.

**How you are asked is yours to choose.** `BIPIXIE_MCP_CONFIRM` sets it, in your settings only. No tool takes it, so your AI assistant can never choose to ask you less.

| `BIPIXIE_MCP_CONFIRM` | What happens before a write |
|---|---|
| `ask` (default) | Your AI client asks you, where it can, as described above. |
| `chat` | Your client is never asked. The question comes back into the conversation, and the write acts once you agree there. Useful when your client's own question is hard to read or answer. |
| `off` | Nobody is asked. Each write acts on its first call, and its answer says what was done and what it used. |

**Running without anyone present.** An assistant run from a script (for example `claude -p`) has nobody to answer, so the question counts as unanswered, never as a refusal. The assistant gets the preview and its agreement, and acts on it only if the prompt you gave it already asked for exactly that change.

**Never offered to an agent:** proposing and writing an optimization in one unattended step, a raw call to any BI Pixie address, and adding a saved AI or replacing its key, which would put your AI provider key into the conversation. Those stay in the portal: an AI is added in AI setup, on the [AI Assistants page](https://app.bipixie.com/ai-assistants).

**A bundle of optimizations.** `preview_optimization_bundle` previews every kind at once and spends nothing. `apply_optimization_bundle` writes only a bundle preview you have read, one kind at a time, and each next kind starts only while your assistant follows the operation with `wait_for_operation`. `revert_optimization_bundle` puts back every kind the apply wrote.

**Your own wording.** `apply_optimization` takes `values`, your own text for an AI instruction, a description or a display folder in place of what BI Pixie proposed. The question put to you quotes each text in full, and the agreement covers that exact text.

**Operations.** A write answers at once with the operation it started. `wait_for_operation` follows it for up to `BIPIXIE_MCP_WAIT_SECONDS` and answers its state and, once it succeeded, its result.

**Sign-in.** One sign-in covers both families. With `azure_cli`, `az login` is enough: the Azure CLI is a pre-authorized client of the BI Pixie API, so nothing is registered and nothing is consented to. With `device_code` or `interactive`, you consent to the BI Pixie API yourself on first use. A permission a call needs and you have not granted is answered with the API's own consent link. Tenant administrator consent is never needed and never asked for.

---

## Privacy and security

- **Usage tools are read-only.** They run read queries only. Write, delete and refresh commands are refused before they reach Power BI.
- **Management tools ask first**, as described above, and act as you within your own plan.
- **It runs as you.** The local install uses your own Microsoft sign-in, so it reaches only what your Power BI account and your BI Pixie account can already reach.
- **Personal data follows your dashboard.** When your BI Pixie semantic model holds user names or IP addresses, the 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.
- **Your saved sign-in.** With `device_code` or `interactive`, the sign-in is saved under the name `bipixie-mcp` in `.IdentityService` in your user profile, so a restart is silent. It holds a refresh token, so treat it like a password. On Windows it is `%LOCALAPPDATA%\.IdentityService\bipixie-mcp.nocae`, encrypted for your Windows account. On macOS the secret is in your login Keychain. On Linux it is `~/.IdentityService/bipixie-mcp.nocae`, encrypted when a desktop keyring is available and saved as plain text when it is not (over SSH or in a container, for example), in which case `chmod 600` protects it. Delete it to sign out. With `azure_cli`, the Azure CLI keeps your sign-in and the server saves nothing.
- **Secrets stay out of logs.** All logs go to stderr, and a redacting filter masks GUIDs and long hex strings. A `.env` that holds a client secret belongs outside source control.

---

## Configuration reference

Settings are read from environment variables or from a `.env` file in the working directory.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `BIPIXIE_MCP_TENANT_ID` | Yes | | Your Microsoft Entra tenant GUID: the tenant that holds your Power BI workspace. |
| `BIPIXIE_MCP_AUTH_MODE` | No | `device_code` | How the server signs in: `azure_cli` (reuses `az login`), `device_code`, `interactive`, `service_principal` or `managed_identity`. The last two are for a hosted deployment. |
| `BIPIXIE_MCP_CLIENT_ID` | For `device_code`, `interactive`, `service_principal` | | The client ID of your own Entra app registration. Not needed for `azure_cli` or `managed_identity`. |
| `BIPIXIE_MCP_CLIENT_SECRET` | For `service_principal` | | The client secret for `service_principal`. In Azure, use a Key Vault reference. Never logged. |
| `BIPIXIE_MCP_WORKSPACE_ID` | This or the name | | The GUID of the workspace that holds the BI Pixie Dashboard. |
| `BIPIXIE_MCP_WORKSPACE_NAME` | This or the ID | | The workspace's display name. Ignored when `WORKSPACE_ID` is set. |
| `BIPIXIE_MCP_DATASET_ID` | No | | The GUID of the BI Pixie semantic model. Unset, the server finds it by name. |
| `BIPIXIE_MCP_DATASET_NAME` | No | either `BI Pixie Dashboard` or `BI Pixie` | The semantic model's name. Unset, the server accepts `BI Pixie Dashboard` (the name BI Pixie gives it when it installs the dashboard) or `BI Pixie` (self-hosted), and stops with a message if the workspace holds both or neither. |
| `BIPIXIE_MCP_POWERBI_API_BASE` | No | `https://api.powerbi.com/v1.0/myorg` | Power BI REST address. Change it only for a sovereign cloud. |
| `BIPIXIE_MCP_POWERBI_SCOPE` | No | `https://analysis.windows.net/powerbi/api/.default` | The OAuth scope for Power BI queries. Power BI refuses Fabric-audience tokens, so change it only for a sovereign cloud. |
| `BIPIXIE_MCP_FABRIC_IQ_URL` | No | `https://fabriciq.svc.cloud.microsoft/v1/mcp/fabriciq` | Microsoft's Fabric IQ endpoint. When Power BI refuses a person who can read a semantic model but lacks Build on it, `query_semantic_model` runs the query through Fabric IQ as them instead. Behind private links, use `https://api.fabric.microsoft.com/v1/mcp/fabriciq`. Leave it empty to turn this off, and that person is told Build is needed. |
| `BIPIXIE_MCP_TRANSPORT` | No | `stdio` | `stdio` for a local install, `streamable-http` for a hosted deployment. |
| `BIPIXIE_MCP_HTTP_HOST` | No | `0.0.0.0` | Bind host for `streamable-http`. |
| `BIPIXIE_MCP_HTTP_PORT` | No | `8000` | Bind port for `streamable-http`. Azure's `PORT` / `WEBSITES_PORT` is picked up automatically. |
| `BIPIXIE_MCP_DEFAULT_DAYS` | No | `30` | The period, in days, a tool uses when it is given none. |
| `BIPIXIE_MCP_DEFAULT_TOP_N` | No | `100` | How many rows a ranking or list tool returns when it is given no `top_n`. |
| `BIPIXIE_MCP_MAX_ROWS` | No | `1000` | The most rows any tool returns. |
| `BIPIXIE_MCP_PII_COLUMNS_ALLOWED` | No | `true` | `true` returns user names and IP addresses when your semantic model holds them. `false` strips them from every result. |
| `BIPIXIE_MCP_QUERY_RATE_LIMIT` | No | `60` | The most Power BI queries per minute, to stay under Power BI's limit of about 120. |
| `BIPIXIE_MCP_TOKEN_CACHE_PATH` | No | (ignored) | **Deprecated, no effect.** The saved sign-in lives in `.IdentityService` (see Privacy and security). Setting it logs a warning. |
| `BIPIXIE_MCP_LOG_LEVEL` | No | `INFO` | `DEBUG`, `INFO`, `WARNING` or `ERROR`. Logs go to stderr. |
| `BIPIXIE_MCP_ALLOW_TARGET_SWITCHING` | No | `true` | `false` removes the four navigation tools and keeps the server on the configured semantic model. |
| `BIPIXIE_MCP_DEPLOYMENT_MODE` | No | `self_hosted` | `cloud` or `self_hosted`. A label for logs only; it changes nothing the server does. |
| `BIPIXIE_MCP_DATA_LAKE_URL` | No | | Your data lake container address, shown in diagnostics only. The server never reads it. |
| `BIPIXIE_MCP_API_BASE` | No | `https://api.bipixie.com/v1` | The BI Pixie API address the management tools call. |
| `BIPIXIE_MCP_API_APP_ID` | For the management tools | | The BI Pixie API's application ID. Unset, the management tools are not offered. BI Pixie cloud (`api.bipixie.com`): `114a7e20-3796-4ddd-ab99-568a78b7759b`. BI Pixie development cloud (`api-dev.bipixie.com`): `2e8a58e5-12c0-4a8f-a754-576086c505af`. Self-hosted: your own BI Pixie API's application ID. |
| `BIPIXIE_MCP_SIGNIN_APP_ID` | For the management tools on a hosted deployment | | The application ID of the sign-in app registration your callers get a token for. With `BIPIXIE_MCP_API_APP_ID` set too, a hosted deployment offers the management reads, acting for the person who signed in. Not used by a local install. |
| `BIPIXIE_MCP_WRITE_TOOLS` | No | `true` | `false` offers the management reads without any write tool. A hosted deployment offers write tools only when this is set to `true` explicitly. |
| `BIPIXIE_MCP_AGREEMENT_KEY` | For write tools on a hosted deployment | | The secret, at least 32 characters, that every copy of a hosted deployment signs a write's agreement with. The deployment template generates one. Never logged. |
| `BIPIXIE_MCP_CONFIRM` | No | `ask` | How a write is confirmed with you: `ask` (your client asks), `chat` (the question comes back into the conversation) or `off` (nobody is asked, and each answer says what was done). A hosted deployment always uses `chat` and refuses to start with `off`. |
| `BIPIXIE_MCP_WAIT_SECONDS` | No | `60` | How long `wait_for_operation` follows an operation when given no time, in seconds. |

**Self-hosted BI Pixie** uses the same settings with your own values: your tenant, your workspace, your own BI Pixie API's application ID and address, and `BIPIXIE_MCP_DATASET_NAME` left unset or set to your semantic model's name.

---

## Hosted deployment

The same server can run as an always-on endpoint in your Azure environment, so Microsoft Fabric data agents, Azure AI Foundry and your team can reach it with no local install. A hosted deployment runs under a managed identity or a service principal, carries the 23 usage tools, and needs the Power BI tenant setting "Allow service principals to use Power BI APIs". When its deployer turns them on, it also carries the management reads, which act for the person who signed in to it, never as the deployment itself: each person allows that once, for themselves, the first time they use one. Its deployer can also turn on the management writes. Every write is then agreed by that person in the conversation, and nobody is ever asked less. It is an enterprise setup: see [Deploy the BI Pixie MCP Server](https://bipixie.com/docs/self-hosted/mcp-server) and [contact support](https://bipixie.com/docs/cloud/contact-support) to plan it. The container image is `ghcr.io/bi-pixie/bipixie-mcp`.

---

## Troubleshooting

- **Every query fails with a permission error (403):** the "Dataset Execute Queries REST API" tenant setting is off, or your account cannot open the workspace. Ask your Power BI administrator to turn the setting on and confirm your workspace access.
- **"No semantic model named ..." or "No dataset named ...":** check the workspace name, and set `BIPIXIE_MCP_DATASET_NAME` to your semantic model's name exactly as it appears in the workspace. BI Pixie names it `BI Pixie Dashboard` when it installs the dashboard.
- **Wrong data or no results:** confirm `BIPIXIE_MCP_TENANT_ID` is the tenant that holds your Power BI workspace.
- **The usage tools answer but "What is my BI Pixie plan?" does not:** set `BIPIXIE_MCP_API_APP_ID`, sign in as a person (`az login` with `azure_cli`), and use the local install. A hosted deployment has the management reads only when its deployer turned them on, and only for a caller signed in as a person.

---

## Support and license

Setup guide: [bipixie.com/docs/cloud/mcp-server](https://bipixie.com/docs/cloud/mcp-server/). Support: [bipixie.com/docs/cloud/contact-support](https://bipixie.com/docs/cloud/contact-support) or support@bipixie.com.

MIT. The full text is in the bundled `LICENSE` file.

> **NOTICE:** Requires an active BI Pixie license and an installed BI Pixie Dashboard. "BI Pixie" is a trademark of DataChant. This package is a client connector and grants no rights to the BI Pixie service or its data.
