Building Semantic Models with an AI Agent: A Guide to the Power BI Authoring MCP Server

Let GitHub Copilot handle measures, relationships, translations and descriptions in your semantic model with the Power BI Authoring MCP Server. Setup, prompts that work, and guardrails.

Microsoft Fabric Oct 28, 2026 13 min read Atılay Berber

Author: @atilayberber

Renaming a hundred measures. Writing descriptions for an entire model. Translating every object into another language. Jobs like these used to eat a whole afternoon. Now you can hand them to an AI agent in a single sentence.

The piece that makes this possible is Microsoft’s Power BI Authoring MCP Server, published on GitHub and npm as powerbi-modeling-mcp. The local version is generally available, and the version hosted in Fabric is in preview.

This guide goes beyond “what does it do”. It covers the architecture, three ways to set it up, an end-to-end session that cleans up a messy model, prompt patterns that work, the transaction and trace tools, enterprise governance, and the problems you’re most likely to hit.

In this post

The building blocks of agentic Power BI development: MCP server, skills, plugin and Desktop Bridge
The Authoring MCP Server’s 21-tool toolbox
Hosted or local: a decision guide
Three setup paths: VS Code extension, hosted URL, the powerbi-authoring plugin
End-to-end example: cleaning up an inherited sales model in 7 steps
Six prompt patterns and a ready-to-use prompt library
Security, governance, limits and troubleshooting

What is MCP, and why should you care?

The Model Context Protocol (MCP) is an open protocol that gives AI assistants a standard way to connect to external tools and data. It has three roles:

Host: the app that runs the agent, such as VS Code.
Client: the part of the host that talks to MCP servers, such as GitHub Copilot.
Server: the program that exposes the tools. Here, that’s Power BI.

Here’s the difference. Classic Copilot suggests DAX, and you copy and paste it. An agent working through MCP connects to your model, makes the change itself, then runs a DAX query to test the result. You approve each step.

The four building blocks of agentic Power BI

Microsoft isn’t shipping this as a single tool but as a set of parts that work together. Telling them apart makes it easier to see which one you need and why:

Part	What it does	Think of it as
Authoring MCP Server	Connects to the model, reads and changes objects, runs DAX	The hands
Agent skills (`semantic-model-authoring` and others)	Teach the agent modeling best practices, workflows and checklists	The expertise
`powerbi-authoring` plugin	Installs the skills and the MCP server in one package	The toolkit
Power BI Desktop Bridge	Talks to a running Desktop instance, for example to reload the model or take screenshots	The bridge

In Microsoft’s words, skills tell the agent what to do, and tools let it do it. You can work with the MCP server alone. But with the skills added, the agent follows ready-made workflows, such as reporting model findings grouped by severity.

There’s also the consumption side. For end users asking questions of a model in natural language, Microsoft points to the Fabric IQ MCP server, which respects RLS and OLS. In short, Authoring MCP is for the person who builds the model; Fabric IQ is for everyone who asks it questions.

The toolbox: 21 tools, one modeling surface

The server groups its tools by object type. The agent decides which tool to call, but knowing what’s possible helps you write better prompts:

Area	Tools	Example operations
Connection and model	connection, database, model	Connect to Desktop or Fabric, import/export TMDL, deploy to Fabric, model stats
Core objects	table, column, measure, relationship	Create, update, delete, rename, move measures between tables, activate/deactivate relationships
Advanced modeling	calculation_group, function, calendar, user_hierarchy, perspective	Calculation groups, DAX user-defined functions (UDFs), calendars and time intelligence groups
Power Query	named_expression, query_group, partition	Parameters, query groups, partition-level refresh
Security and language	security_role, culture, object_translation	RLS roles, cultures and object translations
Testing and performance	dax_query, trace, transaction	Run/validate DAX, capture Analysis Services events, begin/commit/rollback

The server also ships built-in prompts: CreateDAXQuery, RunDAXQueryWithMetrics, AnalyzeDAXQuery, ConnectToPowerBIDesktop, ConnectToFabric and ConnectToPBIP. AnalyzeDAXQuery is especially handy: it runs a query on a cleared cache and reviews the performance metrics.

Hosted or local?

One server, two deployment options:

	Hosted (preview)	Local (GA)
Install	None, just add a URL	VS Code extension, npm package or .exe
Updates	Managed by Microsoft	Managed by you
Authentication	Entra ID (signed-in user)	Entra ID or service principal
Models in Fabric workspaces	Yes	Yes
Model open in Power BI Desktop	No	Yes
PBIP/TMDL files on disk	No	Yes
Transactions and traces	No	Yes
macOS	Yes	No

Decision guide:

You work in Desktop and PBIP, through Git: local.
You only work with models in Fabric and want nothing to install or maintain: hosted.
You’re on a Mac: hosted (the local server doesn’t support macOS).
You’ll run it in CI/CD or automation with a service principal: local.

Whichever you choose, don’t register both at once. Their tools overlap, the agent gets confused about which to call, and token cost goes up.

Setup: three paths

Path 1: VS Code extension (local, the easiest)

Install the GitHub Copilot Chat extension in VS Code and switch the chat to Agent mode.
Install the “Power BI Modeling MCP” extension (analysis-services.powerbi-modeling-mcp).
Check that powerbi-modeling-mcp appears in Copilot’s tool list. On enterprise accounts, an admin may need to enable “MCP servers in Copilot”.

If you’d rather use the npm package (requires Node.js), add this to your MCP configuration:

{
  "servers": {
    "powerbi-authoring-local": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@microsoft/powerbi-modeling-mcp@latest", "--start"]
    }
  }
}

Path 2: Hosted server (nothing to install)

Add the server below to your MCP settings. You sign in with Microsoft Entra on the first call, and the server acts with your permissions:

{
  "servers": {
    "powerbi-authoring-remote": {
      "type": "http",
      "url": "https://api.fabric.microsoft.com/v1/mcp/powerbi/authoring"
    }
  }
}

Note: some MCP clients rely on dynamic OAuth client registration, which Entra ID doesn’t support, so they can’t connect to the hosted server. In that case, use the local server or register your own Entra app.

Path 3: The powerbi-authoring plugin (skills + MCP together)

If you want the agent to have Microsoft’s modeling guidance and not just the tools, install the plugin. You’ll need GitHub Copilot CLI and Node.js 18+:

copilot plugin marketplace add microsoft/skills-for-fabric
copilot plugin install powerbi-authoring@fabric-collection

Start Copilot and type /skills; semantic-model-authoring should be listed. Then you can call a skill directly:

/semantic-model-authoring Connect to Power BI Desktop and analyze the semantic model against best practices

The Skills for Fabric repo also provides compatibility shims for other agents such as VS Code Copilot, Claude Code, Cursor and Windsurf. The skills are currently in preview.

Prerequisites

Write permission on the model. With only Build permission you can run DAX queries, but you can’t change the model.
To write to Fabric models from the local server, the capacity’s XMLA endpoint must be set to Read Write.
For the hosted server, a Fabric admin must turn on the tenant setting “Users can use the Power BI Model Context Protocol server endpoint”.
Pick a deep-reasoning model. Result quality depends heavily on it.

End-to-end example: cleaning up an inherited sales model in 7 steps

A familiar scenario: you’ve inherited a project. The model mixes naming styles, has 80 measures with no descriptions, and several copy-pasted time intelligence calculations. The session below uses the local server and a PBIP project.

1. Start safe: branch and connect

Create a new Git branch first (git checkout -b ai-cleanup). Then:

Open semantic model from PBIP folder 'C:\Projects\Sales\Sales.SemanticModel'

2. Take inventory

Give me an inventory of this model: tables with row counts, number of measures per table,
relationships (with cardinality and cross-filter direction), and any measures without descriptions.
Do not change anything yet.

“Do not change anything yet” matters. It keeps the agent from reaching for a write tool during discovery.

3. Analyze against best practices

Analyze the model against Power BI modeling best practices. Group findings by severity
(high / medium / low) and, for each, say whether you can fix it or whether it needs my decision.
Propose a plan, but wait for my approval before applying anything.

With the plugin installed, the agent uses the checklist from the semantic-model-authoring skill here. Typical findings: bidirectional filters, key columns left visible, no table marked as a date table, measures without format strings.

4. Naming standard (inside a transaction)

Begin a transaction. Analyze the naming convention of the 'Sales' table and apply the same
pattern to all measures in the model. Show me the old → new names as a table first.
After I approve, apply the renames and commit the transaction.

Running bulk changes inside a transaction means one rollback undoes everything if something goes wrong. This tool exists only on the local server.

5. Descriptions and documentation

Add descriptions to all measures, columns, and tables that explain their purpose and the logic
behind the DAX in plain business terms. Keep each description under 200 characters.

These descriptions aren’t only for people. Fabric Copilot and Power BI data agents read this metadata to understand the model, so this step also gets your model ready for AI.

6. Refactor: move duplicate measures into a calculation group

Refactor measures 'Sales Amount 12M Avg' and 'Sales Amount 6M Avg' into a calculation group,
and add 24M and 3M variants. Then write a DAX query that compares the old and new results
for the last 12 months and run it.

The second sentence is the important one: you’re asking the agent not only for the change but for the test that proves it’s correct.

7. Read the diff, then commit

Because you’re on PBIP, every change shows up in the TMDL files. A measure being renamed and given a description lands in Git as a diff like this (illustrative example):

table Sales
-	measure 'Total Sales Amt' = SUM ( Sales[Amount] )
+	/// Net sales amount in local currency, excluding returns.
+	measure 'Sales Amount' = SUM ( Sales[Amount] )
 		formatString: #,0

Read the diff line by line, check whether any measure names your reports depend on have changed, and only then commit and merge to main.

Six prompt patterns that work

Narrow the scope. Instead of “fix the model”, say “fix the format strings of the measures in the Sales table”.
Ask for a plan before execution. Make “Propose a plan and wait for my approval” a habit.
Ask for a before/after table. Never approve a bulk rename without seeing old and new names.
Ask for tests. After every refactor, have the agent write and run a DAX query that validates the result.
Spell out your rules. Put your naming standard, description length and format string preferences in the prompt.
Wrap bulk work in a transaction. On the local server, use the “Begin a transaction … commit” pattern.

Prompt library

Scenario	Prompt
Naming standard	`Analyze my model's naming conventions and suggest renames to ensure consistency.`
Document the model	`Add descriptions to all measures, columns, and tables that explain their purpose and the logic behind the DAX in plain business terms.`
Markdown documentation	`Generate a Markdown document (.md) that provides complete, professional documentation of this semantic model.`
Translation	`Generate a French translation for my model, including tables, columns, and measures.`
Calculation group	`Refactor measures 'Sales Amount 12M Avg' and 'Sales Amount 6M Avg' into a calculation group, and add 24M and 3M variants.`
Power Query parameters	`Analyze the Power Query code for all tables and create semantic model parameters for hard-coded server and database names.`
Compare two models	`Connect to semantic model 'V1' and 'V2' and benchmark the following DAX query against both models.`
Direct Lake model	`Create a Direct Lake semantic model against lakehouse 'LH_CorpData' using tables 'Product', 'Sales', 'Store'.`

Automation: running with a service principal

The local server can also run with a service principal instead of interactive sign-in. That opens the door to a nightly documentation job or a CI step. Start the server with --authmode serviceprincipal and set these environment variables:

AZURE_CLIENT_ID and AZURE_TENANT_ID
AZURE_CLIENT_SECRET, or AZURE_CLIENT_CERTIFICATE_PATH for a certificate (plus AZURE_CLIENT_CERTIFICATE_PASSWORD if needed)

Other flags worth knowing: --readonly (no writes at all), --skipconfirmation (writes without asking; use only with a backup) and --compatibility Full for Analysis Services targets.

6 rules for using it without breaking your model

The agent works with your permissions, and a misconfigured agent can do destructive things. So:

Back up first. Take a backup of the model before every session.
Work in PBIP + Git. Read every change the agent makes in the TMDL diff, and revert when needed.
Try it outside production. Don’t point it at a live model; use a development workspace.
Apply least privilege. If you only need to read, start the local server with --readonly.
Keep confirmations on. The local server asks before writing. Use --skipconfirmation only when you have a backup.
Know where your data goes. Metadata, schemas and query results are sent to your LLM provider. Be careful when sharing chat logs, too.

Enterprise governance: a checklist for admins

Hosted server: turned on and off with the “Users can use the Power BI Model Context Protocol server endpoint” tenant setting. Pilot it with a security group first.
Local server: there’s no separate tenant setting. The way to block it is to disable the XMLA endpoint, which also stops other XMLA-based tools.
Permissions: clients act with the user’s Fabric RBAC permissions. Don’t give developers more access to production workspaces than they need.
Data policy: agree which LLM provider is allowed under your company’s AI data policy.
Compliance: these servers can talk to clients outside Fabric’s compliance boundary. Put the integration through a security review.

What it can’t do

Modeling only. It doesn’t touch report pages or diagram layouts. (There are separate skills for reports.)
DAX query results are capped at 100,000 rows.
It follows the same rules as modeling operations done through External Tools.
The hosted server has no transaction or trace tools. It’s also stateful, so the client must send the mcp-Session-Id header back on every request.
The local server doesn’t run on macOS.
It isn’t built for end-user Q&A; that’s Fabric IQ’s job.

Troubleshooting

Symptom	Likely cause	Fix
The agent never calls the tools	Chat is in Ask/Edit mode	Switch Copilot to Agent mode
It can read but not change anything	Only Build permission on the model	Request Write permission
Errors when writing to a Fabric model	XMLA endpoint is Read Only	Set it to Read Write in capacity settings
Hosted server sign-in fails	Client needs dynamic OAuth registration, or the tenant setting is off	Switch to the local server, or ask your admin to enable the setting
Agent calls the wrong server, responses are costly	Local and hosted both registered	Remove one
Inconsistent results	Weak model or vague prompt	Pick a deep-reasoning model and narrow the scope

Wrapping up

The Authoring MCP Server turns a model developer’s repetitive work into minutes: bulk renames, documentation, translation, refactoring and tests. Paired with the skills and the plugin, the agent doesn’t just execute commands, it follows Microsoft’s modeling guidance too.

The decision is still yours, though. The setup that works is simple: the agent drafts and tests, you read the diff and approve. Backups, PBIP and Git are the seatbelt.

What’s the first job you’d hand to an agent in your model? Tell me in the comments or on LinkedIn, and I’ll walk through the most requested scenario step by step in a future post.

Sources

STAY IN THE LOOP

New guides, sorted by topic in a single email.

Every Monday, the week's new posts arrive grouped by topic. No new posts, no email.