copilot-studio-mcp

# Copilot Studio MCP

An MCP server that lets a coding agent (GitHub Copilot in VS Code, Claude Code, or any other MCP
client) build, test, ship and look after Microsoft Copilot Studio agents from the editor.

An agent becomes a folder of YAML you can read, diff and commit. The server writes that folder the
way the Copilot Studio VS Code extension does, syncs it with the live agent through the official
Power Platform CLI (`pac`), and calls the Power Platform, Dataverse, BAP, Power Automate and
DirectLine APIs for what the CLI does not cover: evaluations, chat, cloud flows, portal drift,
transcripts. Nothing reaches a live environment without your approval, and when a choice is still
open the tool asks a question instead of failing.

## What you can do with it

| You want to | What happens | Read |
| --- | --- | --- |
| Stand up a new agent and get it live | create it inside a solution, generate instructions, add knowledge, topics and tools, review, validate, push, publish, talk to it | [Build a new agent](#build-a-new-agent) |
| Change an agent that already exists | clone it to files, edit or remove components, review, merge what colleagues changed, push | [Work on an existing agent](#work-on-an-existing-agent) |
| Give the agent something to call | connector actions, MCP servers, cloud flows, AI Builder prompts, other agents, chosen from what the environment actually has | [Give the agent tools](#give-the-agent-tools) |
| Know whether it works | chat with the published agent, repeatable conversation tests, evaluation runs with per-case results | [Publish and test](#publish-and-test) |
| Learn from real users | transcripts, session outcomes, escalation rate, a regression test set built from real questions | [Learn from production conversations](#learn-from-production-conversations) |
| Not overwrite what a colleague did in the portal | see portal changes since your last sync, block a push that would collide, merge | [Keep the workspace and the portal in sync](#keep-the-workspace-and-the-portal-in-sync) |
| Write a Power Automate flow without hand-writing Logic Apps JSON | compose a definition from steps, create the flow, switch it on, read its run history | [Build cloud flows](#build-cloud-flows) |
| Move to test and production | pull the whole solution, map connections and variables, deploy 1:1, publish; or use a pipeline | [Ship a solution to another environment](#ship-a-solution-to-another-environment) |
| Prove the stages match | snapshot each environment, compare, gate a pipeline on drift | [Compare environments across DTAP](#compare-environments-across-dtap) |
| Run the tenant | environments, security roles, DLP, tenant settings, backups to files, onboarding a team, the Microsoft 365 agent catalogue | [Administer the tenant](#administer-the-tenant) |

The complete tool list is in [docs/tools.md](docs/tools.md) and the diagrams in
[docs/flows.md](docs/flows.md). The reference sections at the end of this page cover the
[agent settings the server can write](#agent-settings-this-server-can-write),
[authentication and permissions](#authentication-and-app-registration),
[configuration](#configuration), the [hard limits](#what-is-and-is-not-possible) and
[how this differs from pac's own MCP server](#how-this-differs-from-microsofts-own-pac-mcp-server).

## Status

Early release. What has actually been exercised:

- **Offline**: 251 unit tests over the compiled output, plus a pack oracle that round-trips every
  authoring tool's YAML through `pac copilot init` and `pac copilot pack`.
- **Against a real tenant** (2026-09-08, phases A to F of `docs/live-verification.md`): the
  connector registry, the `pac connection list` layout, `pac copilot clone` and its sync metadata,
  drift detection and the `cs_push` conflict refusal, and the evaluation path end to end including
  the portal's CSV import format and the metric status strings. A portal-made agent validates
  clean, so `cs_validate` produces no false positives on real content. That run also caught a real
  bug: `pac copilot publish` prints "Failed to publish" and exits 0, so a failed publish was being
  reported as a success. Fixed.
- **Not yet verified live**: the transcript tools, `cs_check_drift` in quick mode, `cs_chat`, the
  Dataverse `listBots` path, moving a solution between environments, and every flow the flow
  builder produces (none has been imported into an environment yet).

`docs/verify.md` is the short list of what is still open, `docs/STATUS.md` the full record. Read
the dry run before confirming anything that writes.

## Set up

### Prerequisites

- Node.js 20+.
- .NET 10 SDK and the Power Platform CLI: `dotnet tool install --global Microsoft.PowerApps.CLI.Tool`.
  If the SDK lives in your user profile, set `DOTNET_ROOT` to that folder; the server defaults it
  to `~/.dotnet` when that folder exists.
- A pac auth profile for the environment you work in, created once in a terminal:
  `pac auth create --environment <id or URL>`. Everything that goes through pac (create, clone,
  pull, push, publish, solutions, administration) uses it, with Microsoft's own first-party app.
- For the API-based tools (environments, evaluations, chat, flows, drift, transcripts): an Entra
  sign-in through `cs_login`, done from the session. By default no app registration is needed;
  [Authentication and app registration](#authentication-and-app-registration) says when you need
  one and which permissions it must carry.

### Install and register

The server is on npm as `copilot-studio-mcp`, so the usual install is no install: point your MCP
client at `npx`, and the first start fetches the package.

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Copilot_Studio_MCP-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22copilot-studio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22copilot-studio-mcp%22%5D%7D)

VS Code, from a terminal or by hand in `.vscode/mcp.json` (workspace) or the user-level `mcp.json`:

```sh
code --add-mcp '{"name":"copilot-studio","command":"npx","args":["-y","copilot-studio-mcp"]}'
```

```json
{
  "servers": {
    "copilot-studio": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "copilot-studio-mcp"],
      "env": { "CPS_WORKSPACE": "${workspaceFolder}" }
    }
  }
}
```

Claude Code (user scope):

```sh
claude mcp add-json copilot-studio '{"type":"stdio","command":"npx","args":["-y","copilot-studio-mcp"]}' --scope user
```

`npm install -g copilot-studio-mcp` with `"command": "copilot-studio-mcp"` avoids the npx start-up
cost. The server is published to the MCP Registry as `io.github.jgt87/copilot-studio-mcp`, which is
what VS Code's MCP gallery (Extensions view, search `@mcp`) draws from through the GitHub MCP
Registry. To run from a clone instead, see [Development](#development).

Environment variables are optional and listed under [Configuration](#configuration).

### The first session

1. **`cs_init`.** Reports pac and .NET, the pac profiles and which one is active, the MSAL sign-in,
   the write policy in force, the workspace it found and the next steps for it. It also returns a
   menu of tool presets; on a smaller model pick one (see
   [Running on a smaller model](#running-on-a-smaller-model)).
2. **`cs_login`** when a cloud tool needs it. The call opens the browser from the server and returns
   within 15 seconds; if the sign-in has not finished by then it returns `status: pending` with the
   URL so you can open it yourself, and the next cloud call (or `cs_login_status`) picks the token
   up. That is what makes sign-in work from clients that cap tool-call duration or run the server
   where no browser can be launched. Device code (`mode: device_code`) is the alternative where the
   tenant allows it; many block it by Conditional Access policy.
3. **`cs_guide <topic>`** when you want the walkthrough for one job rather than inventing a
   sequence: `getting-started`, `instructions`, `knowledge`, `tools`, `topics`, `evaluations`,
   `publish-and-test`, `drift`, `transcripts`, `solutions`, `administration`, `troubleshooting`.
   Each names the tool per step, the portal steps that cannot be automated, and the next steps for
   your workspace. Six MCP prompts (new agent, add knowledge, add tool, write instructions, review
   and push, check drift) wrap the same walkthroughs in clients that show prompts as commands.

## Approval before anything changes

The server never changes a live Copilot Studio environment on its own. Every tool that can
(`cs_push`, `cs_publish`, `cs_run_evaluation`, `cs_import_solution`, `cs_deploy_solution`,
`cs_create_agent` with an environment, the delete tools, the flow and admin tools that write, and
the environment-changing pac wrappers) returns a **dry run** describing what it would do, and does
nothing else, until it is called again with `confirm: true`. The calling agent is instructed, in the
MCP handshake, to show that dry run and pass `confirm` only after you agree; one approval covers one
call. Writing YAML, editing, reviewing and validating are local file operations and need no
approval; sending them to Copilot Studio does.

For a hard lock, set `CPS_READ_ONLY=1` in the server's environment: the environment-changing tools
are then not registered at all, so no confirmation can reach the environment, while authoring,
validation, review and the read-only tools keep working. `cs_init` reports the mode and which tools
are withheld. `test/policy.test.js` fails if a tool that declares `confirm` is missing from that
list, so the two layers cannot drift apart.

Three more behaviours you will meet in every workflow:

- **A question instead of an error.** When a call cannot proceed because something has not been
  decided (which connector, which operation, which agent), the tool returns `needsInput: true` with
  what it needs, why, the real choices when the server can list them