Copilot Studio MCP

Copilot Studio MCP

コーディングエージェント（VS Code の GitHub Copilot、Claude Code、またはその他の MCP クライアント）がエディターから Microsoft Copilot Studio エージェントの構築、テスト、公開、保守を行える MCP サーバーです。

エージェントは、読み取り、差分確認、コミットができる YAML のフォルダーになります。このサーバーは、Copilot Studio の VS Code 拡張機能と同じ方法でフォルダーを書き込み、公式の Power Platform CLI（pac）を通じて稼働中のエージェントと同期します。また、CLI では対応していない評価、チャット、クラウドフロー、ポータルとの不整合、トランスクリプトについては、Power Platform、Dataverse、BAP、Power Automate、DirectLine の各 API を呼び出します。承認なしに稼働環境へ変更が反映されることはありません。選択肢がまだ決まっていない場合は、ツールは失敗するのではなく質問します。

できること

目的	実行されること	参照先
新しいエージェントを立ち上げて稼働させる	ソリューション内に作成し、指示を生成し、ナレッジ、トピック、ツールを追加して、レビュー、検証、プッシュ、公開し、エージェントと会話します	新しいエージェントを構築する
既存のエージェントを変更する	ファイルにクローンし、コンポーネントを編集または削除し、レビューして、同僚の変更をマージし、プッシュします	既存のエージェントを操作する
エージェントに呼び出すものを追加する	環境に実際にあるものから、コネクタアクション、MCP サーバー、クラウドフロー、AI Builder プロンプト、他のエージェントを選択します	エージェントにツールを追加する
正常に動作するか確認する	公開済みエージェントとのチャット、繰り返し実行可能な会話テスト、ケースごとの結果を確認できる評価実行を行います	公開とテスト
実際のユーザーから学ぶ	トランスクリプト、セッションの結果、エスカレーション率、実際の質問から作成した回帰テストセットを確認します	本番環境の会話から学ぶ
同僚がポータルで行った変更を上書きしない	最後の同期以降のポータルの変更を確認し、競合するプッシュをブロックして、マージします	ワークスペースとポータルを同期する
Logic Apps の JSON を手書きせずに Power Automate フローを書く	ステップから定義を組み立て、フローを作成し、接続をバインドして、有効化し、実行履歴を読み取ります	クラウドフローを構築する
フローが失敗し続ける理由を調べる	失敗したコネクタアクションの背後にある実際のエラーを特定し、正常に動作した実行との差分を確認して、失敗が集中している箇所を把握します	クラウドフローを構築する
テスト環境と本番環境へ移行する	ソリューション全体をプルし、接続と変数をマッピングして、1:1 でデプロイして公開するか、パイプラインを使用します	別の環境へソリューションを出荷する
各ステージが一致していることを確認する	各環境のスナップショットを取得し、比較して、不整合を条件にパイプラインを制御します	DTAP 環境間を比較する
テナントを運用する	環境、セキュリティロール、DLP、テナント設定、ファイルへのバックアップ、チームのオンボーディング、Microsoft 365 エージェントカタログを管理します	テナントを管理する

ツールの全一覧は docs/tools.md に、図は docs/flows.md にあります。どちらも npm パッケージの docs/ に同梱されています。このページの末尾にあるリファレンスセクションでは、このサーバーが書き込み可能なエージェント設定、 認証とアプリ登録、 構成、厳密な制限事項、および Microsoft 独自の pac MCP サーバーとの違いについて説明しています。

ステータス

アーリーリリースです。実際にテスト済みの内容は次のとおりです。

• オフライン：コンパイル済みの出力に対する 251 件のユニットテストに加え、すべてのオーサリングツールの YAML を pac copilot init と pac copilot pack で往復させるパックオラクルを実施しました。
• 実際のテナントで（2026-09-08、docs/live-verification.md のフェーズ A から F）：コネクターレジストリ、pac connection list のレイアウト、pac copilot clone とその同期メタデータ、ドリフト検出と cs_push による競合時の拒否、さらにポータルの CSV インポート形式とメトリクスのステータス文字列を含む評価のエンドツーエンドの経路を検証しました。ポータルで作成したエージェントは問題なく検証されるため、cs_validate は実際のコンテンツに対して誤検出しません。また、この実行で実際のバグも見つかりました。pac copilot publish は「Failed to publish」と表示しながら終了コード 0 を返すため、公開の失敗が成功として報告されていました。修正済みです。
• まだ実環境で検証していない項目：トランスクリプトツール、クイックモードでの cs_check_drift、cs_chat、Dataverse の listBots 経路、ソリューションの環境間移動、フロービルダーが生成するすべてのフロー（まだ環境にインポートされたものはありません）。

未完了項目の簡易リストは docs/verify.md、完全な記録は docs/STATUS.md を参照してください。書き込みを行う操作を確定する前に、ドライランを読んでください。

セットアップ

前提条件

• Node.js 20 以降。
• .NET 10 SDK と Power Platform CLI：dotnet tool install --global Microsoft.PowerApps.CLI.Tool。 SDK がユーザープロファイルにある場合は、DOTNET_ROOT をそのフォルダーに設定してください。そのフォルダーが存在する場合、サーバーはデフォルトで ~/.dotnet を使用します。
• 作業対象の環境用の pac 認証プロファイル。ターミナルで一度作成します： pac auth create --environment <id or URL>。pac を使用するすべての操作（作成、クローン、プル、プッシュ、公開、ソリューション、管理）で、Microsoft 独自のファーストパーティアプリとともにこのプロファイルが使用されます。
• API ベースのツール（環境、評価、チャット、フロー、ドリフト、トランスクリプト）には、セッションから cs_login を実行して Entra にサインインする必要があります。デフォルトではアプリ登録は不要です。必要になる条件と必要なアクセス許可については、認証とアプリ登録を参照してください。

インストールと登録

サーバーは npm で copilot-studio-mcp として公開されているため、通常はインストール不要です。MCP クライアントから npx を指定すれば、初回起動時にパッケージが取得されます。

VS Code 拡張機能 vscode-extension/ も用意されており、サーバーを VS Code の MCP ホストに登録し、以下の環境変数を設定として公開します。サーバーとその 依存関係は VSIX に含まれているため、npm は不要で、初回起動時のネットワーク接続も不要です。 cd vscode-extension && npm install && npm run package でビルドし、生成された .vsix を code --install-extension copilot-studio-mcp-<version>.vsix でインストールします。

ターミナルから、または .vscode/mcp.json（ワークスペース）もしくはユーザーレベルの mcp.json に手動で設定する場合の VS Code：

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

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

Claude Code（ユーザースコープ）：

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

Mistral Vibe の場合は、~/.vibe/config.toml（または $VIBE_HOME/config.toml。作業フォルダー内の ./.vibe/config.toml が優先されます）に設定します。Vibe がサーバーの起動に与える時間はデフォルトで 10 秒です。企業ネットワークでは初回の npx による取得にそれ以上かかることがあるため、グローバルにインストールし、エントリーポイントを node で実行してください（npm root -g でフォルダーを確認できます）。Windows ではパスをシングルクォートで囲んでください。TOML ではダブルクォート内のバックスラッシュがエスケープ文字として解釈されるため、"C:\Users\..." は有効な TOML ではありません。

[[mcp_servers]]
name = "copilot-studio"
transport = "stdio"
command = "node"
args = ['C:\Users\<you>\AppData\Roaming\npm\node_modules\copilot-studio-mcp\dist\index.js']
startup_timeout_sec = 60   # default 10
tool_timeout_sec = 300     # default 60; solution exports and evaluation runs take longer

npm install -g copilot-studio-mcp を実行し、"command": "copilot-studio-mcp" を指定すれば、npx の起動コストを回避できます。サーバーは MCP レジストリに io.github.jgt87/copilot-studio-mcp として公開されています。VS Code の MCP ギャラリー（拡張機能ビューで @mcp を検索）は、GitHub MCP レジストリを通じてここから取得します。クローンから実行する方法については、開発を参照してください。

環境変数は任意で、設定に記載されています。

最初のセッション

1. cs_init。 pac と .NET、pac プロファイルとアクティブなプロファイル、MSAL サインイン、適用中の書き込みポリシー、検出されたワークスペース、およびその次の手順を報告します。また、ツールのプリセット一覧も返します。小規模なモデルでは、プリセットを 1 つ選んでください（小規模なモデルでの実行を参照）。
2. クラウドツールで必要になったら cs_login を実行します。この呼び出しはサーバーからブラウザーを開き、15 秒以内に返ります。それまでにサインインが完了しない場合は、URL とともに status: pending を返すので、自分で URL を開くことができます。その後、次のクラウド呼び出し（または cs_login_status）でトークンが取得されます。この仕組みにより、ツール呼び出しの実行時間に上限を設けているクライアントや、ブラウザーを起動できない場所でサーバーを実行している場合でも、サインインできます。テナントで許可されている場合は、代替手段としてデバイスコード（mode: device_code）を使用できますが、多くのテナントでは条件付きアクセス ポリシーによってブロックされています。
3. 一連の手順を自分で考えるのではなく、特定の作業の手順を確認したい場合は cs_guide <topic> を実行します。getting-started、instructions、knowledge、tools、topics、evaluations、publish-and-test、drift、transcripts、solutions、administration、troubleshooting を指定できます。各ガイドでは、手順ごとに使用するツール、自動化できないポータルでの操作、ワークスペースでの次の手順を説明します。6 つの MCP プロンプト（新しいエージェント、ナレッジの追加、ツールの追加、指示の作成、レビューとプッシュ、ドリフトの確認）では、プロンプトをコマンドとして表示するクライアント向けに、同じ手順を利用できます。

変更前に承認

サーバーが稼働中の Copilot Studio 環境を独自に変更することはありません。変更を実行できるすべてのツール（cs_push、cs_publish、cs_run_evaluation、cs_import_solution、cs_deploy_solution、環境を指定した場合の cs_create_agent、削除ツール、書き込みを行うフローおよび管理ツール、環境を変更する pac ラッパー）は、実行内容を示すドライランを返し、confirm: true を指定して再度呼び出されるまでは、それ以外のことは何も行いません。MCP ハンドシェイクでは、呼び出し元のエージェントにドライランを表示し、あなたが承認した後にのみ confirm を渡すよう指示しています。1 回の承認で承認されるのは、1 回の呼び出しです。

ディスク上のエージェントを変更する場合も、同じ理由から同じように確認を求めます。意図していない編集は簡単にできてしまう一方、気づくのは困難だからです。cs_add_topic、cs_add_knowledge_source、cs_add_tool、cs_add_flow、cs_add_trigger、cs_add_variable、cs_edit_topic、cs_edit_tool、cs_edit_knowledge、cs_update_settings、cs_update_agent、cs_generate_instructions は、最初の呼び出しでは何も書き込みません。代わりに変更内容を返します。作成されるファイルは全体を表示し、編集されるファイルは現在の内容との差分を表示します。同じ呼び出しを confirm: true で繰り返すと、その内容を書き込みます。確認、検証、説明の各操作は読み取り専用のため、何も確認を求めません。

差分だけでは判断できない変更内容であるため、文章フィールドは別途管理されます。プレビューには文字数と、製品の制限まであとどれだけ残っているかが表示されます。制限を超える編集は、プッシュ時に失敗するのではなく、最初から拒否されます。制限値はそれぞれ異なり、instructions は 8000 文字、Settings > Responses > "Response formatting" ボックス（responseInstructions）は 500 文字です。

厳格なロックをかけるには、サーバーの環境で CPS_READ_ONLY=1 を設定します。この場合、環境を変更するツールは登録自体されないため、確認を経て環境に変更を加えることはできません。一方、作成、検証、確認、読み取り専用の各ツールは引き続き利用できます。cs_init は動作モードと、利用できないツールを報告します。test/policy.test.js は、confirm を宣言するツールがその一覧から漏れている場合に失敗するため、2 つのレイヤーにずれが生じることはありません。

ワークフロー全体を通じて、ほかにも 3 つの動作があります。

• エラーの代わりに質問します。 何かが決まっていないために呼び出しを続行できない場合（コネクタ、操作、エージェントなど）、ツールは needsInput: true を返し、必要な情報、理由、サーバーが一覧表示できる場合は実際の選択肢、さらに選択肢を一覧表示するツールを示します。何も書き込まれません。呼び出し元のエージェントがあなたに確認し、再度呼び出します。この仕組みは、MCP エリシテーションに対応していないクライアントも含め、あらゆるクライアントで機能します。
• 時間のかかる呼び出しはバックグラウンドで実行されます。 MCP クライアントがツール呼び出しに設定する上限は約 1 分です。長時間かかる可能性のあるツール（cs_pull_solution、cs_create_auth_profile、環境のプロビジョニング、すべての pac ラッパー）は background: true を受け付け、すぐに jobId を返します。cs_job_status は、サーバー再起動後も保持されるディスク上の記録から、各フェーズと結果を報告します。ジョブを開始する前に、ツールは変更を行ってよいか判断するため、確認の契約に影響はありません。
• 書き込みは再試行されません。 トランスポートエラーまたは 429/5xx で失敗した読み取りは、バックオフを行い Retry-After に従って再試行されます。一方、タイムアウトした公開やインポートは、すでに適用されている可能性があるため、繰り返し実行せず、その旨を報告します。

2 つのアカウント：作成者と管理者

エージェントの作成とテナントの管理では、通常、異なるアカウントを使用します。pac はマシンごとに 1 つの認証プロファイルをアクティブにするため、アカウントごとにプロファイルを作成し、サーバーに切り替えさせます。

pac auth create --name maker --environment <environment id or url>
pac auth create --name admin --environment <environment id or url>

または、セッションから cs_create_auth_profile を name、environment、background: true とともに使用します。pac は独自のブラウザーを開いてサインインを待機します（cs_job_status でプロファイルの作成完了を確認できます）。cs_list_auth_profiles では、プロファイルと現在アクティブなプロファイルを確認できます。

コア同期ツールとソリューションツールでは CPS_PAC_PROFILE、管理者コマンドとテナントのバックアップでは CPS_ADMIN_PROFILE を使用します。すべての pac ラッパーと cs_pac では、明示的な profile も指定できます。サーバーがプロファイルを選択すると、処理後に以前のプロファイルに戻します。また、プロセス内のすべての pac 呼び出しは 1 つのキューを共有するため、複数ステップの操作（ブートストラップ、ソリューションのプルとデプロイ、スナップショット）では、実行全体を通してプロファイルが維持されます。ほかのサーバーインスタンスやターミナルからの pac コマンドは、この連携の対象外です。API ベースのツールで使用される MSAL サインインは別個のもので、pac とは独立しています。

新しいエージェントを作成する

空のフォルダーから、会話できる公開済みエージェントを作成します。各ステップは 1 回のツール呼び出しです。環境を変更するステップでは、まずドライランを実行します。

1. 環境を選択します。 cs_list_environments を使用します（cs_login が必要です）。または、Copilot Studio の URL から環境 ID を取得します。
2. ソリューションを選択または作成します。 cs_list_solutions で既存のソリューションを確認できます。既存のソリューションは、アンマネージドであり、その発行者プレフィックスを使用する限り利用できます。エージェント用のソリューションを新しく作成するには、次のコマンドを使用します：cs_create_solution uniqueName=contoso_Agents publisherPrefix=contoso confirm=true。ソリューションは、エージェントをテスト環境や本番環境に移す際に、後でエクスポートしてインポートする単位となります。そのため、エージェントごとに作成されるままにするより、あらかじめ選んでおくとよいでしょう。
3. その中にエージェントを作成します。 cs_create_agent name="Contoso Support" publisherPrefix=contoso projectDir=./contoso-support environment=<id> solutionName=contoso_Agents confirm=true（ステップ 2 をまとめて実行するには createSolution=true を追加します）。サーバーはローカルで pac copilot init を実行してひな形を作成し、ソリューション名を使ってパックした後、インポートし、ライブエージェントを再度クローンします。これにより、projectDir は既定のシステムトピックを含む、同期接続済みのワークスペースになります。environment を指定しない場合は、ローカルのひな形のみが作成されます。この場合、設定、エージェント、トピックはパックできますが、ナレッジ、ツール、フローはパックできません。 publisherPrefix または projectDir を省略すると、ツールは推測せずに確認します。その際、環境内のパブリッシャー（ソリューションを指定した場合は、そのソリューションのパブリッシャーが使用できる唯一のプレフィックス）を一覧表示し、エージェント名のフォルダーを提案します。プレフィックスについて確認するのは重要です。エージェントが今後持つすべてのコンポーネントのスキーマ名の一部になり（contoso_contososupport.topic.Greeting）、コンポーネントを作成した後で変更するには作り直す必要があり、エージェントを配置するソリューションのパブリッシャーと一致していなければなりません。
4. エージェントの目的を伝えます。 cs_generate_instructions purpose="Answer IT questions and create ServiceNow tickets" audience="Employees" tone="Friendly, brief" boundaries=["never reset passwords"] modelName="Agent instructions" は、AI Builder のプロンプトを使って指示を作成します（cs_list_prompts で環境内のプロンプトを確認できます。プロンプトがない場合は、AI Builder で「write agent instructions」プロンプトを一度作成してください）。下書きを確認し、apply=true を付けて再度呼び出すと、内容が agent.mcs.yml に書き込まれます。その後は、changeRequest を指定して refine=true を使うと、既存の内容を修正できます。または、cs_update_agent で自分で記述することもできます。このツールでは、応答の指示とモード、会話履歴、機能、モデレーション、モデル、会話の開始文も設定できます（設定の全一覧）。
5. エージェントが使えるものを用意します。 公開ウェブサイト、SharePoint、Graph コネクタ、アップロード済みファイルには cs_add_knowledge_source を使います。トリガー フレーズと、メッセージ、質問、条件、変数設定、リダイレクト、HTTP、フロー、生成回答（名前付きナレッジ ソースに任意で範囲指定可能）、アダプティブ カード、転送、終了の各ノードから成る決定論的な会話には cs_add_topic を使います。エージェントが呼び出すツールには cs_add_tool を使います（ツールのワークフロー）。イベント トリガーとグローバル変数には cs_add_trigger と cs_add_variable を使います。
6. 確認して検証します。 cs_review_agent は、ルールベースでワークスペース全体を確認し、10 点満点で評価します。エスカレーションやフォールバックの欠如、ツールの説明の不備、トリガー フレーズの重複、認証のないプライベートなナレッジ、ファイル内のシークレットなどが対象です。各指摘にはルールと修正方法が示されます。続いて cs_validate を実行すると、すべてのファイルが作成スキーマ（744 個の定義）に照らして検証され、ファイル間の整合性も確認されます。何にもバインドされていない接続参照、存在しないカタログ操作、存在しないトピックへのリダイレクトなどが対象です。また、プッシュ時にはエラーにならず、誤った状態で保存されてしまう問題も検出して処理を停止します。具体的には、プルで残ったマージ競合マーカー（プッシュすると、その前までのテキストだけが残ります）、残存する <AGENT_SCHEMA> プレースホルダー、pac が受け付けないファイル名やスキーマ名、200 個を超えるトリガー フレーズなどです。引用符で囲まれていない # によるテキストの切り捨て、終了ノードの後にあるノード、= が抜けた数式、送信アクションのないアダプティブ カード、ソリューションのエクスポートを妨げるピリオドを含むトピック名については、警告が表示されます。
7. プッシュします。 cs_push confirm=true はポータルの「保存」に相当します。下書きエージェントにトピック、ナレッジ、ツールが表示されるようになります。ドライランでは、最初に検証と簡易ドリフトチェックが実行されます。前回のプル以降に同僚がポータルで同じコンポーネントを変更していた場合、プッシュは拒否されます。接続参照を必要とするツールでは、ポータルでの操作が一度必要です。エージェントの「ツール」で対象のツールを開いて「接続」を選択し、その後 cs_pull を実行してバインドを取得します。
8. 公開して会話します。 cs_publish confirm=true を実行し、次に cs_chat utterance="my laptop is slow" を実行します。テストのワークフローを使うと、これを繰り返し実行可能なチェックにできます。

flowchart TD
    A["cs_init"] --> B["cs_list_solutions<br/>pick one, or cs_create_solution"]
    B --> C["cs_create_agent<br/>environment + solutionName + confirm"]
    C --> D["cs_generate_instructions<br/>AI Builder prompt, then apply"]
    D --> E["cs_add_topic / cs_add_knowledge_source / cs_add_tool<br/>(cs_list_connectors, cs_describe_connector)"]
    E --> R["cs_review_agent"]
    R --> H["cs_validate"]
    H -- errors --> E
    H -- clean --> I["cs_push confirm"]
    I --> J{"tool needs a connection?"}
    J -- yes --> J1["portal: authorise once"] --> J2["cs_pull"] --> K
    J -- no --> K["cs_publish confirm"]
    K --> L["cs_chat"]

GitHub Copilot ハーネスエージェント（authoringMode: cli-copilot を指定した cs_create_agent）で扱える範囲はより限定的で、初期化、パック、インポート、指示、チャットです。トピックと評価は標準ハーネスの機能です。

既存のエージェントで作業する

多くのエージェントは、ポータルで作成されるなど、すでに存在しています。基本的な流れは、クローン、変更、レビュー、マージ、プッシュです。

1. クローンします。 cs_list_agents（pac または Dataverse 経由）を実行し、次に cs_clone_agent bot=<id or schema name> outputDir=./support-agent を実行します。結果として、agent.mcs.yml、settings.mcs.yml、topics/、knowledge/、actions/、trigger/、variables/、workflows/ と接続参照を含む、同期接続されたワークスペースが作成されます。cs_describe_workspace はその内容を一覧表示し、次の手順で終わります。
2. 変更します。 コンポーネントは、名前、ファイル名、またはパスで指定します。cs_edit_topic はトリガーフレーズ、優先度、ノード（位置または ID で指定）を変更します。cs_edit_tool は説明、入力、接続を変更します。cs_edit_knowledge はサイトまたはトリガー条件を変更します。cs_remove_component はトピック、ナレッジソース、ツール、トリガー、または変数を削除し、ほかで使用されていない接続参照を整理したうえで、参照先がなくなったリダイレクトがあれば通知します。cs_update_agent と cs_update_settings では、エージェント自体の設定を変更できます。追加の手順は、新しいエージェントのフローと同じです。すべての編集で、拡張機能が想定するファイルヘッダーが維持されます。
3. レビューしてマージします。 cs_review_agent を実行し、次に cs_pull で同僚がポータルで変更した内容を取り込みます（pac の 3-way マージ）。その後、cs_validate を実行します。
4. プッシュします。 cs_push confirm=true を実行します。ポータルでの変更とローカルでの編集が同じコンポーネントに及んでいる場合、プッシュはブロックされます。cs_pull で解決できます。force: true を指定すると上書きできます。
5. コミットします。 ワークスペースを git で管理し、プルのたびにコミットします（ツールの結果にリマインダーが表示されます）。その後、ポータルとの差分が確認可能な diff として表示されます。変更を受け入れる場合はコミットし、拒否する場合はローカルバージョンをプッシュします。

この流れに関連する操作として、cs_delete_agent と cs_delete_solution は環境から対象を削除します（confirm）。cs_extract_agent_template と cs_create_agent_from_template は、エージェントをテンプレートに変換して、そこからさらにエージェントを作成します。cs_extract_translations と cs_merge_translations は、ローカライズの往復処理を行います（.resx または .json、whatIf を使用）。cs_quarantine_agent は、エージェントを停止し、再び稼働させます。

エージェントにツールを付与する

Copilot Studio のエージェントは、環境内の任意のコネクタ（Microsoft が公開している1,000種類以上のコネクタとカスタムコネクタ）、コネクタ経由で公開される MCP サーバー、クラウドフロー、AI Builder のプロンプト、他のエージェント、その他のあまり一般的でない種類を呼び出せます。サーバーは、YAML スキーマから種類を、環境からインスタンスを把握します。環境内に何が存在するかを知る唯一の情報源は、この環境です。

1. コネクタを見つけます。 cs_list_connectors search=ServiceNow は、環境のコネクタレジストリを一覧表示します。これはポータルの「ツールを追加」に表示されるものと同じ一覧で、MCP サーバーには印が付いています。サインインしていない場合は、公開されているコネクタリファレンスから生成されたオフライン用シード（表示名から shared_ ID への対応、オペレーションなし）にフォールバックします。これは出発点であり、そのコネクタが利用者に対して有効になっている証明ではありません。
2. オペレーションを見つけます。 cs_describe_connector connector=shared_service-now operation=incident は、コネクタの OpenAPI 定義を operationId、必須および任意のパラメーター、応答フィールドを含むオペレーションに変換します。x-ms-agentic-protocol: mcp-streamable-1.0 は MCP エンドポイントを示します。定義は .cs-catalog/<environment>/ にキャッシュされるため、以降の呼び出しはオフラインで行えます。
3. ツールを追加します。 cs_add_tool では、コネクタのアクション、MCP サーバー、クラウドフロー、AI Builder のプロンプト（cs_list_prompts で一覧表示できます）、接続済みエージェントまたは子エージェント用の型付き仕様と、残りの種類に使用する raw 型を指定します（AI プラグイン、Bot Framework スキル、クライアントアクション、コンピューター操作エージェント）。定義がキャッシュされている場合、operationId を確認し、オペレーションの必須パラメーターから自動入力を補完して、actions/ の下に YAML と接続参照のスタブを書き込みます。まだコネクタやオペレーションを指定していない場合、候補を優先順位順に並べた質問が返されます。
4. ポータルで一度だけ接続します。 接続とは、ポータルからのみ作成できる認証済みリンクです（例外はサービスプリンシパルの Dataverse 接続で、cs_create_connection が作成します）。cs_push の後、エージェントの「ツール」からツールを開いて接続し、その後 cs_pull を実行します。cs_validate は、オペレーションがキャッシュ済み定義に含まれていないツールファイルを警告し、cs_review_agent は、オーケストレーターが選択できる説明になっていないツールを指摘します。

単体テストでは、スキーマにあるツールの種類一覧とサーバーのテーブルを比較します。そのため、新しい種類を導入するスキーマ更新は、その種類が分類されるまでビルドに失敗します。ツールとしてのフローには、スキャフォールド（cs_add_flow、試験運用中）と、フロービルダーで構築してエージェントから参照する実際のフローがあります。

公開とテスト

1. 公開します。 cs_publish confirm=true は、pac copilot publish または publishedon が更新されるまでポーリングする Dataverse の PvaPublish アクションを通じた［公開］ボタンです。

2. チャットします。 cs_chat utterance="..." は、公開済みのエージェントに発話を 1 つ送信し、返信を返します。次のターンでは、返された conversationId を渡します。transport: auto の場合、サーバーはエージェントの認証モードを確認します。認証なしと手動認証のエージェントは DirectLine を経由します（公開済みエージェントのトークンエンドポイントは匿名で利用できるため、アプリは不要です）。Entra 認証が統合されたエージェントは Copilot Studio クライアント SDK を経由し、独自のアプリ ID と CopilotStudio.Copilots.Invoke スコープが必要です（clientId または CPS_CLIENT_ID）。

3. 繰り返し実行できるようにします。 cs_run_conversation_tests は、同じチャット経路を通じて YAML ファイルの発話と期待値を実行し、失敗した内容を報告します。期待値では、表現とエージェントの動作を確認します。usedTool、notUsedTool、usedTopic、notUsedTopic、citedKnowledge は、アクティビティからトピック、ツール、ナレッジの帰属情報を読み取るため、テストでは、実際にツールが呼び出されたのか、単に正しく見える回答が返されたのかを判別できます。すべての結果とすべての cs_chat の返信には、確認されたトピック、ツール、引用が報告されます。判定できない期待値（アクティビティに帰属情報がない場合）は、エージェントの失敗として扱うのではなく、その旨が示されます。帰属情報のキー名はドキュメントに基づいており、実環境での検証は済んでいません。docs/test-verification.md は、これらのキー名を確定するための手順書です。

4. 評価します。 ポータルの［評価］機能では、エージェントに質問のテストセットを実行し、回答ごとにスコアを付けます。API でできないのはテストセットの作成だけなので、手順は次のとおりです。

   • cs_create_test_set_csv suggestFromWorkspace=true は、ポータルのインポート形式で CSV を作成します（最大 100 件）。トピックとナレッジを基にケースを生成します。
   • ポータルの［評価］タブで一度インポートします。
   • cs_list_test_sets を実行し、続けて cs_run_evaluation confirm=true wait=true を実行してから、cs_get_evaluation_run で合格・不合格に分類されたケースごとの結果を確認します。履歴は cs_list_evaluation_runs で確認できます。

flowchart TD
    A["cs_create_test_set_csv"] --> B["portal: Evaluation > Import CSV"]
    B --> C["cs_list_test_sets"] --> D["cs_run_evaluation confirm wait"]
    D --> E["cs_get_evaluation_run"] --> F{"failures?"}
    F -- yes --> G["fix topics / instructions / knowledge"] --> H["cs_push confirm"] --> D
    F -- no --> I["cs_publish confirm"]

本番環境の会話から学ぶ

ユーザーがエージェントを使い始めると、トランスクリプトはテストケースと、エージェントが回答できない質問を把握するための最適な情報源になります。Copilot Studio はすべてのセッションを Dataverse の conversationtranscript テーブルに保存します。サーバーはこのデータを読み取りますが、書き込みは行いません。

• cs_list_transcripts は、指定した期間内のセッションを一覧表示します。日時、ターン数、最初の質問、実行されたトピックとツール、終了方法を確認できます。
• cs_get_transcript は、1 つのセッションの全ターンを、各ターンに帰属するトピックとツールとともに返します。
• cs_summarize_transcripts は、指定した期間の内容を集計します。結果、エスカレーション率、トピックに一致しなかったセッション、上位のトピックとツール、失敗の原因となった質問を確認できます。
• cs_test_set_from_transcripts は、ユーザーが実際に行った質問を基に、評価用のインポート CSV を作成します。失敗を優先するため、次回の評価実行では問題が起きた内容をテストできます。

Copilot Studio は、会話が成功したかどうかを報告しません。結果は、このサーバーがトランスクリプトを読み取って判定したものです（エスカレーション、エージェントが回答できないと述べた場合、ユーザーのターンに返信がなかった場合など）。resolved は、セッションに失敗を示す記録がなかったという意味であり、ユーザーが満足したことを示すものではありません。すべての結果には、この注意事項が繰り返し記載されます。また、cs_guide transcripts では、集計からトランスクリプト 1 件を確認し、回帰テストセットを作成するまでの手順を説明します。トランスクリプトにはユーザーがエージェントに伝えた内容が含まれるため、サインインしているユーザーには、そのテーブルの読み取り権限を付与するロールが必要です。また、結果には顧客データが含まれます。実環境のテナントでの検証は済んでいません。

ワークスペースとポータルを同期した状態に保つ

エージェントをクローンした後も、作成者は Copilot Studio で編集を続けられます。編集を止める仕組みはなく、プラットフォームから通知も送られません。ポータルでの編集はすべて Dataverse の行に反映されます。設定と指示は bot 行に、トピック、ナレッジソース、ツール、トリガー、変数ごとに 1 つの botcomponent 行に記録され、それぞれに更新日時と変更したユーザーが記録されます。サーバーはこれらの行を使って再スキャンせずに差分を確認し、詳細が重要な場合はクローンを使って確認します。

1. 同期スタンプ。 cs_clone_agent、cs_pull、cs_push、cs_create_agent（environment を指定した場合）は .mcs/cs-sync.json に、すべてのワークスペースファイルのフィンガープリントと、Dataverse のサインイン情報がキャッシュされている場合はすべてのコンポーネントの更新日時を書き込みます。cs_describe_workspace で最終同期を確認できます。
2. 簡易チェック。 cs_check_drift（デフォルトは mode: quick）は bot 行とそのコンポーネント行を読み取り、スタンプと比較します。ポータルで変更、追加、削除されたコンポーネント、変更したユーザーと日時、エージェントの設定が変更されたかどうか、公開されていない変更がライブエージェントにあるかどうかを確認します。各コンポーネントはワークスペースファイルに対応付けられ、そのファイルもローカルで変更されている場合、その項目は競合となります。数秒で完了し、pac は不要です。cs_login が必要です。
3. 詳細チェック。 cs_check_drift mode=full は pac copilot clone を一時フォルダーに実行し、スタンプと照合して各ファイルを 3 種類に分類します。local-modified、remote-modified、both-modified（競合）、いずれか一方で追加または削除されたファイルを示し、統合差分も表示します。簡易チェックで差分が報告され、正確な内容を確認したい場合、または Dataverse にサインインしていない場合（pac のプロファイルだけで十分です）に使用します。アップロードされたナレッジファイルはここで確認でき、簡易チェックでは確認できません。
4. プッシュ前チェック。 cs_push のドライランには簡易チェックが含まれるため、確認前に呼び出し元は「前回の pull 以降に Copilot Studio で 3 つのコンポーネントが変更されています」と確認できます。confirm を指定した場合、ポータルでの変更とローカル編集が同じコンポーネントに影響していると、プッシュはブロックされます。cs_pull（pac の三者間マージ）で解決でき、force: true で上書きできます。
5. 台帳としての Git。 cs_pull の後は毎回コミットしてください。cs_check_drift は、ワークスペースがリポジトリ内にあるかどうか、および未コミットのファイル数を報告します。

制限事項。簡易チェックでは、接続（作成者がツールを接続することは想定内であり、すべての比較で接続 ID は無視されます）、アップロードされたナレッジファイル、チャネル構成、セキュリティグループは確認できません。スタンプにコンポーネントごとのベースラインがない場合（同期時に Dataverse にサインインしていなかった場合）、同期時刻に 2 分の猶予を加えて判定するため、同期直後に行われた編集は同期そのものとして扱われます。コンポーネントのクエリは、まだライブ環境で検証されていません。docs/STATUS.md を参照してください。

クラウドフローを構築する

トピックと同じように、ステップ仕様からフローを構築できるため、Logic Apps の JSON を手書きする必要はありません。cs_build_flow_definition は定義をローカルで組み立て、必要な接続参照とともに返します。cs_create_flow は同じ仕様を受け取り、環境またはソリューション内にフローを作成します。cs_update_flow は仕様を受け取り、既存のアンマネージドフローの定義を置き換えます。接続参照は維持されます。

仕様はトリガーと、順番に実行されるステップで構成されます。

トリガー	用途
agent（デフォルト）	Copilot Studio エージェントがツールとして呼び出すフロー。型付き入力と応答を扱います
manual、http	人または HTTP リクエストによって開始されます
recurrence	スケジュール
connector	Dataverse の行作成など、コネクタのイベント
raw	そのほかのトリガーをそのまま記述します
ステップ	出力
---	---
connector	パラメーターと接続参照を含む、コネクター操作（OpenApiConnection）
http	HTTP 呼び出し
condition、foreach、scope	分岐、ループ、グループ化と、それぞれに含まれるネストされたステップ
initializeVariable、setVariable、compose	変数と中間値
terminate	ステータスを指定して実行を終了
response	エージェントが呼び出せるフローや HTTP フローが返す内容（outputs を指定すると自動的に追加されます）
raw	そのほかのアクションをそのまま記述

ビルダーは runAfter を連結して、各ステップが前のステップの完了を待つようにします。また、Power Automate と同じ方法でアクション名を正規化し、使用するコネクターごとに接続参照を 1 つ収集して、ステップ間で再利用します。式には Power Fx ではなく、Logic Apps の式を使用します。@{triggerBody()?['orderId']}、@body('List_rows')?['value']。コネクター ID と操作 ID は cs_list_connectors と cs_describe_connector から取得します。操作のパラメーターは、コネクターのステップの parameters とまったく同じです。

ビルダーの周辺ツールとして、cs_list_flows は環境内のフローを状態、所有者、接続参照とともに表示し、cs_get_flow はフローの完全な定義を返し、cs_delete_flow はフローを完全に削除します。cs_list_flow_runs、cs_get_flow_run、cs_run_flow は実行履歴を読み取り、Power Automate サービス経由で手動実行を開始します（別途サインインが必要です。cs_login scope='flow' を使用してください。サインインしたユーザーは、そのフローの所有者または共同所有者である必要があります）。

接続をバインドします。 接続参照はコネクターを指定し、接続はそのコネクターに対して認証された 1 人のアカウントを表します。この 2 つを紐付けるまでは、フローを実行できません。cs_bind_flow_connection で紐付けます。接続参照が 1 つで、使用可能な接続も 1 つなら、フロー ID 以外は何も必要ありません。選択肢が複数ある場合は、どれを使うか尋ねられます。このツールはフローが使用する 2 種類の形式のいずれかを書き込みます。ソリューションの外部で作成されたフローでは接続を直接指定し、ソリューション経由で追加されたフローでは connectionreference 行を参照します。また、activate: true を指定すると、同じ呼び出しでフローが有効になります。cs_set_flow_state は、バインド済みのフローを単独で有効にします。

実行が失敗した理由を調べます。 実行一覧には、実行が失敗したことしか表示されません。

ツール	わかること
cs_explain_flow_run	この実行が失敗した理由は何ですか？ 失敗したコネクターアクションには、それ自体のエラーメッセージはありません。メッセージはアクションの出力内にあり、数日で期限切れになるリンクの先にあります。そのため、このツールはメッセージを取得し、原因がコネクター、式、タイムアウトのいずれかを示します。また、アクションに渡された入力と、直前に実行されたアクションの出力を並べて表示します。
cs_compare_flow_runs	昨日は動いていました。 失敗した実行を直近の成功した実行と比較し、どのアクションから差が生じたかを示します。compareTriggerData: true を指定すると、トリガーのペイロードで異なるキーを報告します（キー名のみで、値は表示しません）。これにより、入力の不具合かフローの不具合かを判別できます。一方の実行にのみ存在するアクションは、定義自体が変更されたことを意味します。
cs_analyze_flow_health	時々失敗します。 失敗率、実行時間の中央値と 90 パーセンタイル、失敗が発生しているアクションを示します。ほとんどの失敗の原因が 1 つのアクションなら、そのステップの不具合です。多くのアクションにわたって失敗している場合は、接続、スロットリング、または呼び出し先のシステムに原因があると考えられます。

トリガーが失敗した場合、フローは一度も実行されていないため、原因はロジックではなく、トリガーの接続またはパラメーターにあります。実行の詳細は時間が経つと失われます。入力と出力は限られた期間しか保存されないため、失敗が起きたら早めに診断してください。

ビルダーでは対応できないことが 2 つあります。接続をバインドするには、接続があらかじめ対象の環境に存在している必要があります。そのため、新しいフローはオフの状態で作成されます。また、定義は検証済みの往復処理ではなく、Logic Apps のスキーマとエクスポートされたソリューションに準拠しています。そのため、インポートしたら、形式を信頼する前に Power Automate で開いてください。

別の環境にソリューションをデプロイする

エージェントごとの同期は、エージェントが作成された環境に紐づいたままです。テスト環境や本番環境へ移行するには、ソリューションをエクスポートしてインポートします。サーバーでは、プル、設定ファイルの作成、デプロイを行います。

1. 移行する内容を確認します。 cs_list_solutions、続いて cs_describe_solution を実行すると、エージェント、ボットコンポーネント、フロー、接続参照、環境変数、カスタムコネクタがエクスポート、展開され、一覧表示されます。
2. プルします。 cs_pull_solution は、アンマネージドとマネージドの両方の形式でソリューションをエクスポートし、src/ に展開します。また、デプロイ時に読み込まれるマニフェストである solution.json を書き込み、deployment-settings.json を作成し、すべてのエージェントを agents/ に複製します。完全なプルには数分かかるため、background: true を指定し、その後 cs_job_status で進捗を確認してください。結果は、対象ディレクトリ内の pull-job.json にも保存されます。
3. ターゲットをマッピングします。 ターゲット環境で cs_list_connections を実行すると、その環境に存在する接続が表示されます。cs_create_deployment_settings では、各接続参照をそのいずれかにマッピングし、ターゲットの環境変数の値を設定し、エージェントごとに、そのエージェントを使用できる Entra セキュリティグループを指定します。
4. デプロイします。 cs_deploy_solution confirm=true は、設定ファイルを使用してターゲットにインポートし、すべてのエージェントに対して pac copilot publish を実行します（publishAgents はデフォルトで有効です）。接続参照がマッピングされていない場合、allowUnmapped: true を指定しない限り、インポートは拒否されます。src/ を手動で編集した場合は、先に cs_pack_solution を実行してください。

同じ手順で利用できる品質ゲートと代替手段：cs_check_solution はデプロイ前に Solution Checker を実行します。cs_set_solution_version、cs_solution_online_version、cs_upgrade_solution は、リリース番号の管理と段階的なアップグレードに使用します。cs_publish_customizations は環境内のすべてのカスタマイズを公開します。cs_list_pipelines と cs_deploy_pipeline は、直接インポートする代わりに Power Platform パイプラインを使用します。cs_init_solution_project、cs_clone_solution、cs_sync_solution、cs_add_solution_reference、cs_add_solution_license は、ソース管理されたソリューションプロジェクト（.cdsproj）の管理に使用します。cs_add_solution_component は、既存のコンポーネントをソリューションに追加します。

ツールでは引き継がれないもの

コピーを「1:1」と呼ぶ前に、以下を考慮してください。

• 接続はソリューションに含まれません。 ソリューションに含まれるのは接続の参照です。接続自体（SharePoint、Outlook、Dataverse、MCP サーバーなどへの認証済みリンク）は、対象環境にすでに存在している必要があり、対象環境のユーザーが作成して同意する必要があります。 cs_create_connection は例外ですが、サービスプリンシパルの Dataverse 接続のみが対象です。allowUnmapped: true を指定すると、対象ポータルで誰かがバインドするまで、ツールは未バインドのままになります。
• 接続参照を解決できない場合、クラウドフローはオフの状態で配置されます。 接続をバインドすると、cs_list_flows で有効化されていないフローを確認でき、cs_set_flow_state でそれぞれを有効にできます。この手順にポータルは不要です。
• 環境変数には対象環境の値が必要です。 設定ファイルにはすべての変数が記載されています。値を空欄にすると、対象環境ではソリューションの既定値が引き継がれます。通常、これは開発環境の値です。
• エージェントを利用できるユーザーは環境ごとに異なります。 設定ファイルには、各エージェントの AadGroupId を含む CopilotAgents セクションがあります（pac 2.11.2 で確認済み）。対象環境の Entra グループに対応付ける（cs_create_deployment_settings の copilotAgents）か、インポート後に対象ポータルでアクセスを設定してください。すべてゼロの ID は、グループが設定されていないことを意味します。
• エージェントのコンテンツの一部はソリューションの外部にあります。 アップロードされたナレッジファイル、ナレッジとして使用される Dataverse テーブル、SharePoint のアクセス許可、チャネルの構成（Teams、ウェブ、Microsoft 365 Copilot）は環境固有です。インポート後、対象ポータルでナレッジソースを確認し、チャネルに再公開してください。
• マネージドとアンマネージド。 cs_pull_solution は両方をエクスポートします。下流環境にはマネージドをデプロイし、アンマネージドは開発用にのみ保持してください。マネージドをインポートした後は、対象環境で直接編集できません。
• エージェントごとの同期では環境をまたげません。 cs_clone_agent または cs_pull_solution のワークスペースをプッシュできるのは、ソース環境のみです。agents/<name> ワークスペースを編集してソース環境にプッシュし、その後ソリューションを再度プルしてデプロイしてください。

DTAP 環境を比較する

同じソリューションを開発、テスト、受け入れ、本番へと昇格させるとき、各段階で前の段階と同じものが保たれているかが問題になります。プラットフォームには環境間の差分機能がありませんが、すべての入力にアクセスできるため、サーバーが各環境をスナップショットフォルダーに保存し、オフラインで比較します。

1. cs_snapshot_environment で各段階のスナップショットを作成します（または、順序付きの環境チェーンを受け取り、隣接する各ペアを比較する cs_compare_environments でまとめて作成します）。スナップショットフォルダーには次のものが含まれます。

   snapshots/TEST/
     snapshot.json         label, environment, time, solution version and managed flag,
                           agents with publish state, flows, connection references,
                           environment variables, notes
     agents/<Agent name>/  the agent as YAML, from pac copilot clone
   

   エージェントはソリューションとしてエクスポートせず、複製します。これは、テスト環境や本番環境からマネージドソリューションをエクスポートできないためです。フロー、接続参照、環境変数、公開状態は Dataverse から取得され、cs_login でサインインしている場合は含まれます。サインインしていない場合、スナップショットにはそれらがスキップされたことが記録されます。

2. cs_compare_snapshots で隣接する段階を比較します（DEV と TEST、TEST と ACC、ACC と PROD）。各比較では <A>-vs-<B>.md と .json が出力されます。

3. 判定を確認します。 レポートの冒頭には DRIFT または no drift と表示され、その後に差分、想定される違い、レイヤーごとの表が続きます。変更されたエージェントファイルについては、統合差分も表示されます。

4. 対応します。 エージェントの YAML に差分がある場合、後の段階が遅れているか、その場で編集されています。上記のソリューションフローを使って再度昇格させてください。未バインドの接続参照、存在しないフロー、値のない変数は、デプロイ設定の問題です。設定ファイルを修正して再デプロイしてください。

5. 履歴を保持します。 スナップショットフォルダーは通常のファイルなので、（.mcs/ の状態を除いて）コミットすると、段階ごとのタイムラインを作成できます。

差分とみなされるもの、および段階間の想定される違いは次のとおりです。

レイヤー	差分	想定される違い（差分ではなく、レポートに表示）
ソリューション	バージョンが異なる、ある段階に存在しない	後の段階ではマネージド、開発環境ではアンマネージド
エージェント YAML（トピック、指示、ナレッジ、ツール、トリガー、変数）	正規化後にファイルが変更、追加、削除されている	ID、監査情報、バージョンフィールド、connectionreferences.mcs.yml 内の接続 ID（差分の前に削除）
公開状態	いずれかの段階で最後の公開後に変更されている（未公開の変更）
フロー	ある段階に存在しない、オン／オフ状態が異なる
接続参照	存在しない、コネクタが異なる、ある段階で未バインド	段階ごとに異なる接続にバインドされている
環境変数	存在しない、ある段階で値がない	段階ごとに値が異なる（strictVariables の場合のみ差分）
認証モード	段階間で異なる

パイプラインゲート。 cs_compare_snapshots と cs_compare_environments は failOnDrift を受け取ります。この場合、ツールの結果はエラーになり、スクリプト化された MCP クライアントやパイプラインのステップでジョブを失敗させることができます。TEST から ACC へ昇格させる前に実行する、一般的なゲートの例を示します。

cs_snapshot_environment label=TEST environment=<test id> dir=snapshots/TEST solution=<name>
cs_snapshot_environment label=ACC  environment=<acc id>  dir=snapshots/ACC  solution=<name>
cs_compare_snapshots a=snapshots/TEST b=snapshots/ACC failOnDrift=true

注意事項：すべての段階に、アクティブな pac 認証プロファイルからアクセスできる必要があります（テナントをまたぐ環境チェーンの場合は、段階間で pac auth select を実行し、1 つずつスナップショットを作成してください）。マネージドエージェントで pac copilot clone が正常に動作するかは、実環境で未検証です（代替手段として、Dataverse Web API から同じコンポーネント定義を読み取ります）。アップロードされたナレッジファイルとチャネル設定は、名前とサイズのみが一覧表示されます。Dataverse にサインインしていない場合、比較対象はソリューションのバージョンとエージェント YAML のみとなり、その旨がレポートに記載されます。

テナントを管理する

管理は管理者アカウント（2 つのアカウント）で実行します。profile を渡すか、CPS_ADMIN_PROFILE を一度設定してください。変更はすべて同じドライランと confirm を経由します。リセット、削除、コピー、復元は環境全体を破棄または上書きするため、ドライランで失われる内容を確認できます。

• 設定をファイルにバックアップします。 cs_backup_tenant は、テナント設定、環境、DLP ポリシー、環境グループ、サービスプリンシパル、登録済みアプリケーション、テンプレート、および各環境の詳細、ソリューション、エージェント、接続、セキュリティロール、プラットフォームのバックアップなど、テナント設定全体をフォルダーに書き出します。解析済みの行と並べて生の出力も保存され、取得に失敗した項目は切り離されるため、バックアップの残りは引き続き保存されます。

• テナントを読み取り、変更します。 環境と進行中の操作、テナント設定（JSON ファイルに読み出して、1 項目を変更）、DLP ポリシー（組み合わせ可能なコネクタ）、環境グループ、セキュリティロール、サービスプリンシパルと登録済みアプリケーション、マネージド環境のガバナンス、管理モードとバックアップの保持期間、環境のライフサイクル（作成、コピー、バックアップ、復元、リセット、削除）を管理できます。それぞれ 1 つの cs_admin_* ツールで実行します（一覧）。

• 新しい環境にチームをオンボーディングします。 cs_admin_create_environment（時間がかかるため、background: true と cs_job_status を併用してください）を実行してから、CSV を指定して cs_admin_assign_users を実行します。

  UPN,Security Roles,Business Unit
  [email protected],"System Customizer,Basic User",Sales
  [email protected],Environment Maker,
  

  pac では 1 回の呼び出しにつき 1 人のユーザーと 1 つのロールを指定するため、この名簿の場合は 5 回の呼び出しが必要です。このツールは名簿を展開し、ドライランでユーザーとロールの各組み合わせをすべて表示したうえで、1 回の承認で実行します。各行は独立しているため、UPN の入力を間違えても、その行を報告したうえで残りは実行されます。名簿が実際にはグループを指す場合は、cs_admin_assign_group を使用してください。Entra グループをロールにバインドする呼び出しは、メンバー数にかかわらず 1 回で済み、新たに参加したメンバーにはアクセス権が引き継がれます。ロール名は環境ごとに異なります（新しい環境に対して cs_admin_list_security_roles を実行します）。環境にまだプロビジョニングされていないユーザーには、その環境でロールを割り当てることができません。

• Microsoft 365 エージェントカタログ。 cs_list_agents は 1 つの環境の bots テーブルを読み取り、Power Platform の境界で処理を終了します。カタログ（Microsoft Graph。cs_login scope='graph' による別個のサインインが必要です）はテナント全体を対象とし、cs_publish の次に確認すべき疑問、つまりエージェントが実際に誰かに届いたかどうかに答えます。cs_list_org_agents は各エージェントを利用できるユーザー、デプロイ先、ブロックされているかどうかを報告します。プラットフォーム、ホスト、要素の種類、最終更新日で絞り込むことができます。cs_get_org_agent は 1 つのエントリ全体を返し、cs_block_org_agent はテナント内の全ユーザーに対するエージェントのブロックと解除を行い、cs_reassign_org_agent は以前の所有者が離れたときに新しい所有者へ引き継ぎます（どちらも confirm が必要です）。Microsoft Agent 365 ライセンスが必要です。グローバルクラウドのみを対象としており、稼働中のテナントでは未検証です。また、ブロックと再割り当ては Graph beta でのみ利用できます。

専用ツールのない pac コマンドはすべて cs_pac から実行できます。読み取り専用コマンドはすぐに実行され、それ以外のコマンドはドライランを返し、confirm が必要です。Copilot Studio の範囲外にある pac グループ（application、canvas、catalog、code、data、managed-identity、model、modelbuilder、package、pages、pcf、plugin、power-fx、telemetry、test、tool）は、意図的にそのまま残しています。

このサーバーが書き込めるエージェント設定

エージェントの設定は2つのファイルに保存され、サーバーは両方を読み込み、検証して反映します。この表では、ポータルに表示される項目と、それを書き込むフィールドおよびツール引数の対応を示しています。ここにある変更はすべてローカルファイルへの変更で、実行前にプレビューが表示され、confirm: true の場合にのみ書き込まれます。cs_push で変更を適用し、cs_publish で公開します。instructions は製品によって8000文字までに制限されており、プレビューでは文字数がカウントされます。

agent.mcs.yml（エージェント定義）。cs_update_agent で書き込みます。

ポータル	フィールド	引数
指示	instructions	instructions、appendInstructions（または cs_generate_instructions）
応答：回答の文言と書式（「応答の書式設定」）	responseInstructions	responseInstructions、appendResponseInstructions - 500文字。プレビューでカウントされます
応答：応答モード	defaultResponseMode	defaultResponseMode：Auto、ThinkDeeper、QuickResponse
エージェントが参照する会話履歴	historyType	history：none または conversation。historyMessages と併用します
機能：Web ブラウジング、コードインタープリター、画像生成、Teams／SharePoint／メール／会議／人物検索	gptCapabilities	capabilities（渡した切り替え項目のみ変更されます）
一般知識：モデルがナレッジソース以外の内容にも回答できるか	aISettings.useModelKnowledge	useModelKnowledge
コンテンツモデレーション	aISettings.contentModeration	contentModeration：Minimum から Maximum
ファイル分析、セマンティック検索	aISettings.isFileAnalysisEnabled、aISettings.isSemanticSearchEnabled	isFileAnalysisEnabled、isSemanticSearchEnabled
モデル	aISettings.model.modelNameHint	modelNameHint
会話スターター	conversationStarters	conversationStarters、addConversationStarters
表示名	displayName	displayName

値は作成スキーマに照らして検証されるため、許可されたセットに含まれない応答モードやモデレーションレベルは、書き込まれずに拒否されます。

settings.mcs.yml（エージェントの実行方法）。たとえば {"configuration.settings.GenerativeActionsEnabled": true} のようなドットパスを使い、cs_update_settings で書き込みます。

ポータル	パス
生成オーケストレーションのオン／オフ	configuration.settings.GenerativeActionsEnabled
認証	authenticationMode（None、Integrated、Manual）、authenticationTrigger、accessControlPolicy
言語	language
エージェントを他のエージェントから呼び出せるか	configuration.isAgentConnectable
分析、テレフォニー、音声、ネットワーク	configuration.analyticsSettings、isTelephonyEnabled、botSpeechSettings、networkSettings

ツールがこれらに依存しているため、cs_update_settings は authoringModel、recognizer.kind、template の変更を拒否します。スキーマで許可されているその他のフィールドは cs_lookup_schema で確認でき、手動で行った変更は cs_validate で検証できます。

注意点が1つあります。これらのフィールド名は作成スキーマのもので、稼働中のエージェントとの往復を経て得られたものではないため、どのポータルのコントロールがどのフィールドに対応するかは推測です。確実に確認するには、ポータルで値を設定してから cs_clone_agent を実行し、比較してください。

認証とアプリ登録

このサーバーは MSAL のパブリッククライアント（対話型ブラウザーまたはデバイスコード）を使ってユーザーをサインインさせます。クライアントシークレットは使用しないため、必要な権限はすべて、サインイン中のユーザーとして動作する委任された権限です。同じ API 上にヘッドレスパイプラインを構築する人向けに、Microsoft が提供している場合に限り、アプリケーション権限も以下に記載しています。MCP クライアント内での cs_login の動作については、最初のセッションを参照してください。

独自のアプリ登録が必要ですか？

状況	アプリの登録が必要ですか？
pac コマンド（cs_create_agent、cs_clone_agent、cs_pull、cs_push、cs_pack、pac 経由の cs_publish、full モードの cs_check_drift、すべての cs_*_solution ツール、およびすべての pac ラッパー）	いいえ。pac auth create は Microsoft 独自のファーストパーティアプリでサインインします。
既定のクライアント ID を使うクラウドツール（cs_list_environments、Dataverse 経由の cs_list_agents、Dataverse 経由の cs_publish、cs_check_drift、評価、認証不要または手動認証のエージェントに対する cs_chat）	いいえ。サーバーは、Power Platform API、Dataverse、Power Apps サービスで事前承認されているファーストパーティの VS Code クライアント ID 51f81489-12ee-4a9e-aaae-a2591f45987d を使います。Microsoft 独自の Copilot Studio ツールも同じ ID を使います。
同じツールを使うが、テナントでその ID がブロックされている場合（アプリの同意ポリシー、条件付きアクセス、「ユーザーの割り当てが必要」）	はい。以下の手順で登録を作成し、CPS_CLIENT_ID を設定してください。
**統合認証（Entra SSO）**を使うエージェントに対する cs_chat	はい。常に必要です。ファーストパーティ ID は、サードパーティ向けの CopilotStudio.Copilots.Invoke 権限を持っていません。cs_chat に clientId を渡すか、CPS_CLIENT_ID を設定してください。
ヘッドレス CI（サービスプリンシパル、ユーザーなし）	現時点でこのサーバーではサポートされていません（パブリッククライアントのみ）。パイプラインでは、Dataverse アプリケーションユーザーとともに pac auth create --applicationId ... --clientSecret ... を使うか、サービスプリンシパルに RBAC ロールを割り当てたうえで Power Platform API を使ってください。

独自のアプリ登録に必要な権限（Entra ID > アプリの登録 > API のアクセス許可 > 「組織で使用している API」）：

使用する機能	Entra で選択する API	権限	委任またはアプリケーション	備考
cs_chat（トランスポート sdk、Entra SSO エージェント）	Power Platform API（アプリ ID 8578e004-a5c6-46e7-913e-12f58912df43）	CopilotStudio.Copilots.Invoke	このサーバーが使用するのは委任権限です。同名のアプリケーション権限は、機密クライアント（Microsoft 365 Agents SDK）向けに存在しますが、ここでは使用しません。	通常、管理者の同意が必要です。リダイレクト URI は http://localhost（モバイル アプリケーションとデスクトップ アプリケーション）です。
cs_list_test_sets、cs_run_evaluation、cs_get_evaluation_run、cs_list_evaluation_runs、cs_download_evaluation_snapshot	Power Platform API	トークン スコープ https://api.powerplatform.com/.default。評価エンドポイントが宣言するのは .default のみです。権限リファレンスには、より細かい評価用権限はありません。	委任のみです。Power Platform API にはアプリケーション権限がありません。サービス プリンシパルは、代わりに RBAC ロールを通じてアクセス権を取得します。	Microsoft 独自のツールで、ファーストパーティの ID を使用して確認済みです。カスタム登録では未確認です。呼び出しで 403 が返る場合、サインインしたユーザーにエージェントのメーカー アクセス権が必要です。
cs_list_environments、Dataverse URL の自動検索、cs_list_connectors、cs_describe_connector、cs_bind_flow_connection の接続検索	PowerApps Service（アプリ ID 475226c6-020e-4fb2-8a90-7a972cbfc1d4）	User（「Power Apps Service API にアクセス」）	委任です。	BAP 環境 API（api.bap.microsoft.com）、コネクタ レジストリ、接続一覧（api.powerapps.com）を呼び出します。接続一覧には、サインインしたユーザーが表示できる環境内のすべての接続が表示され、他のユーザーが所有する接続も含まれます。接続をバインドすると、その接続の所有者としてフローが実行されます。
cs_list_agents（dataverse 経由）、cs_publish（dataverse 経由）、cs_create_agent が選択肢として提示する発行元とソリューションの検索、cs_chat の認証モード検出、cs_check_drift（クイック モード）、cs_push のドリフト事前確認、cs_clone_agent／cs_pull／cs_push が記録するコンポーネント スタンプ、フロー ツール（cs_list_flows、cs_get_flow、cs_create_flow、cs_update_flow、cs_set_flow_state、cs_delete_flow、および cs_bind_flow_connection の Dataverse 部分）、トランスクリプト ツール（cs_list_transcripts、cs_get_transcript、cs_summarize_transcripts、cs_test_set_from_transcripts）	Dynamics CRM（Dataverse、アプリ ID 00000007-0000-0000-c000-000000000000）	user_impersonation	委任です。アプリケーション権限はありません。Dataverse へのサーバー間アクセスには、各環境でセキュリティ ロールを持つアプリケーション ユーザーが必要です。	ユーザーには、ボットの読み取りと発行が可能な Dataverse セキュリティ ロール（System Customizer または Copilot Studio メーカー ロール）が引き続き必要です。ドリフト チェックが読み取るのは bot テーブルと botcomponent テーブルのみで、どのメーカー ロールでも読み取り可能です。Dataverse への書き込みは行いません。cs_create_agent は、推測ではなく実際のプレフィックスを選択肢として提示するためにのみ、publishers（および名前付きソリューションの発行元）を読み取ります。この読み取りに失敗した場合、失われるのは選択肢だけで、ツールの利用には影響しません。トランスクリプト ツールは、ユーザーがエージェントに実際に話した内容を保持する conversationtranscript を読み取ります。これは他のテーブルより機密性の高いテーブルであるため、サインインしたユーザーには読み取りを許可するロールが必要であり、結果は顧客データとして扱う必要があります。ワークスペースの同期メタデータに Dataverse URL がない場合、上記の PowerApps Service 権限を通じて URL を検索します。
cs_list_flow_runs、cs_get_flow_run、cs_run_flow、cs_explain_flow_run、cs_compare_flow_runs、cs_analyze_flow_health	Microsoft Flow（Power Automate サービス、アプリ ID 7df0a125-d3be-4c96-aa54-591f83ff541c）	User（トークン スコープ https://service.flow.microsoft.com/.default。CPS_FLOW_SCOPE で上書き）	委任です。	Dataverse および Power Platform API とは別のリソースであるため、個別に同意が必要です。cs_login scope='flow' でサインインしてください。サインインしたユーザーは、フローの所有者または共同所有者である必要があります。エンドポイントとスコープは Power Automate ポータルが呼び出すサービスから取得したもので、テナントでは未確認です。診断ツールは、サービスから返されるアクションの入力と出力への SAS 署名付きコンテンツ リンクもたどります。これらのリンクには独自の署名が含まれているため、ベアラー トークンなしで取得され、有効期限は数日後です。
cs_list_org_agents、cs_get_org_agent	Microsoft Graph（アプリ ID 00000003-0000-0000-c000-000000000000）	CopilotPackages.Read.All（CPS_GRAPH_SCOPE でスコープを上書き）	このサーバーが使用するのは委任権限です。同名のアプリケーション権限は読み取り用に存在します。	Microsoft 365 エージェント カタログは、さらに別のリソースです。cs_login scope='graph' でサインインしてください。Microsoft Agent 365 ライセンスが必要で、グローバル クラウドでのみ利用できます（GCC、DoD、21Vianet には対応していません）。/v1.0/copilot/admin/catalog/packages を読み取ります。稼働中のテナントでは未確認です。
cs_block_org_agent、cs_reassign_org_agent	Microsoft Graph	CopilotPackages.ReadWrite.All（CPS_GRAPH_WRITE_SCOPE で上書き）	委任のみです。Microsoft は、これら 2 つの操作に対するアプリケーション権限を提供していません。	上記と同じライセンスおよびクラウドの制限が適用されます。cs_login scope='graph_write' でサインインしてください。これらは /beta でのみ利用できるため、読み取りに使用したバージョンにかかわらず /beta に固定されます。ブロックはテナント全体に適用され、すべてのユーザーに直ちに反映されます。稼働中のテナントでは未確認です。
cs_get_connector_consent_bypass、cs_set_connector_consent_bypass、cs_download_channel_manifest	Power Platform API	トークン スコープ https://api.powerplatform.com/.default。リファレンスには、より細かい権限は定義されていません。	委任のみです。	評価と同じリソースです。同意バイパスはエージェントの管理者設定であるため、書き込み（および場合によっては読み取り）には Power Platform または Copilot Studio の管理者ロールが必要です。マニフェストのダウンロードには、メーカー アクセス権と、Microsoft 365／Teams チャネルに公開済みのエージェントが必要です。3 つすべて、公開されているリファレンスに従っており、稼働中のテナントでは未確認です。
認証なしまたは手動認証のエージェント（DirectLine）用の cs_chat	なし	なし	該当なし	公開済みエージェントの DirectLine トークン エンドポイントは匿名です。
pac の対話型サインイン	なし	なし	該当なし	Microsoft 独自のアプリです。pac auth create --environment <id>。
独自に登録する手順：

1. Entra ID > アプリの登録 > 新規登録。シングルテナントを選択します。認証で、リダイレクト URI に http://localhost（cs_login の対話型認証で MSAL が使用するループバック）を指定し、プラットフォーム モバイル アプリケーションとデスクトップ アプリケーションを追加します。mode: device_code で cs_login を使用する場合は、パブリック クライアント フローを許可するを「はい」に設定します。
2. 表のアクセス許可を追加します。名前または上記の ID で検索しても Power Platform API が表示されない場合は、サービス プリンシパルがテナントにありません。az ad sp create --id 8578e004-a5c6-46e7-913e-12f58912df43（または New-MgServicePrincipal -AppId 8578e004-a5c6-46e7-913e-12f58912df43）で作成し、もう一度検索します。
3. テナントの管理者の同意を付与するか、各ユーザーが初回サインイン時に対話形式で同意するようにします。
4. MCP サーバーの環境変数に ID を設定します：CPS_CLIENT_ID=<application (client) id> および CPS_TENANT_ID=<directory (tenant) id>。cs_chat では、呼び出しごとに clientId を指定することもできます。

設定

すべての環境変数は任意です：

変数	機能
CPS_WORKSPACE	エージェントが起動するワークスペース（VS Code：${workspaceFolder}）。設定されていない場合、サーバーは現在のディレクトリ、その直下のディレクトリ、または上位ディレクトリでマーカーファイルを探します
CPS_TENANT_ID, CPS_CLIENT_ID	cs_login の Entra テナントとアプリ登録。既定のテナントは organizations、既定のクライアントはファーストパーティの VS Code ID です
CPS_ENVIRONMENT_ID, CPS_ENVIRONMENT_URL, CPS_AGENT_ID	ワークスペースに同期メタデータがない場合のクラウドツールの既定値。明示的な引数、ワークスペースのメタデータ、これらの値、BAP の検索の順に優先されます
CPS_PAC_PROFILE, CPS_ADMIN_PROFILE	メーカーコマンドおよび管理者コマンド用の pac 認証プロファイル（2 つのアカウント）
CPS_READ_ONLY	環境を変更するすべてのツールを無効にします（変更前の承認）
CPS_TOOLS, CPS_TOOLS_EXCLUDE	ツール一覧を絞り込みます：プリセットおよびワイルドカード * を使ったカンマ区切りの名前（以下）
CPS_FLOW_SCOPE, CPS_GRAPH_SCOPE, CPS_GRAPH_WRITE_SCOPE	Power Automate サービスおよび Microsoft Graph のトークン スコープを上書きします
CPS_CACHE_DIR, PAC_PATH, DOTNET_ROOT	トークンキャッシュの場所、pac 実行ファイル、.NET ルート

小型モデルでの実行

ツール一覧は148個あり、作業を始める前のスキーマだけで約 50k tokens を消費します。最先端モデルなら問題ありませんが、小型モデルはコンテキストの大半をメニューに費やし、その中から適切なものを選びにくくなります。サーバーの環境で CPS_TOOLS にプリセットを設定するか、セッション中にユーザーが選べるようにします。cs_init は質問、選択肢の表、プリセットごとの現在の件数を含む toolPresets ブロックを返し、cs_set_tool_preset がその回答を適用します。

プリセット	ツール数	使用する場面
full（デフォルト）	148	すべてを使う場合。大規模モデルを使う場合、またはタスクに必要なものがまだ分からない場合
core	34	1つのエージェントを構築または変更して、稼働させる場合。通常はこちらを選びます
authoring	25	ファイルの作成と確認のみを行う場合。サインインは不要で、環境に反映されることもありません
admin	49	管理者アカウントでテナントを管理し、cs_backup_tenant も使う場合
solutions	25	ソリューションの取得、デプロイ、比較と、インポート時に無効のままになったフローのバインドを行う場合

何も削除されません。プリセットによって変わるのは提示されるツールだけです。cs_init、cs_guide、cs_set_tool_preset、cs_job_status はどのプリセットでも利用できるため、セッション中いつでも選択を変更できます。cs_pac は core、admin、solutions に含まれるため、プリセットで非表示になる pac コマンドにも引き続きアクセスできます。また、cs_init は、ツールが見つからない場合に、それが存在しないのではなく非表示であることを伝えます。プリセットは相互に、またグロブと組み合わせて使えます。例：CPS_TOOLS=core,cs_admin_*、または CPS_TOOLS_EXCLUDE=cs_*_pipeline,cs_env_*,cs_*_auth_profile。SDK は切り替え時に notifications/tools/list_changed を送るため、それに対応しているクライアントには短縮された一覧がすぐに反映されます。一覧をキャッシュするクライアントでは、再起動が必要です。実行時に切り替えられるのは、起動時に登録された範囲を狭める場合のみです。すべてのプリセットを選択できるようにするには、CPS_TOOLS を設定しないでください。

モデルが適切なツールを選ぶか確認する

これほど長いツール一覧では、適切なツールへのルーティングが課題になります。説明文によって、「昨夜、フローが失敗したのはなぜですか？」という質問が cs_explain_flow_run に届くか、別の質問に答えるツールに届くかが決まります。このパッケージには確認用の機能が付属しているため、ここに記載された数値を信頼するのではなく、自分のプリセット、自分のモデル、自分の言い回しで測定できます。

npx copilot-studio-mcp-routing-eval --dry-run                       # free: shows the corpus and the cost
npx copilot-studio-mcp-routing-eval --preset core --repeat 3 --yes
npx copilot-studio-mcp-routing-eval --cases ./my-questions.json --yes

クライアントに表示されるのとまったく同じ状態でツール一覧をモデルに提示し、発話を1つずつ処理して、最初に指定されたツールを採点します。--cases には、同梱の reference/routing-cases.json と同じ形式の独自ファイルを指定できます。実際にユーザーが尋ねる質問のほうが、ここに同梱されている質問よりも確かな根拠になるためです。ANTHROPIC_API_KEY を設定している場合は、ツール一覧をキャッシュされたプレフィックスとして Messages API を呼び出します。実行コストは数セントです。設定していない場合は、claude CLI と、そのマシンですでにサインイン済みのアカウントを使います。いずれの場合も、ケースごとにモデルを1回呼び出して実費が発生するため、--yes を指定しない限り何も実行されません。

結果は1回だけで判断せず、--repeat 3 で確認してください。 Haiku 4.5 での測定では、同じビルドでも実行ごとにスコアが2ケース分変動し、ケースの3分の1は毎回異なる回答になりました。1回の実行では、実際には改善していない変更を、改善したと判断してしまうことがあります。レポートでは、対処する価値のある常に誤ルーティングされるケースと、結果が揺れて根拠にならないケースを分けています。

ハンドシェイクの手順は、小型モデル向けに書かれています。ルールは1行に1つ、各指示の前に明示的なトリガーを置き、最初の実運用で確認された失敗（クライアントの約60秒の制限で呼び出しが途中終了する、サーバーバイナリが古くツールが見つからない、サインインしておらずクラウドツールが失敗する、pac が失敗を報告しながら終了コードは0を返す）と、それぞれに対する対応策を示すセクションを設けています。

可能なことと不可能なこと

機能	方法	状態
エージェントをファイルとして扱い、双方向に同期する	pac copilot init / clone / pull / push / pack / publish	公式、GA
トピック、ナレッジ、ツール、トリガー、フローを YAML として扱う	VS Code 拡張機能のワークスペースレイアウトと pac copilot push	公式
ローカル検証	microsoft/skills-for-copilot-studio の JSON スキーマ（MIT）＋構造チェック	このサーバー
評価を実行し、結果を読み取る	Power Platform API の makerevaluation エンドポイント	公式、GA、標準ハーネス
公開済みエージェントとチャットする	DirectLine v3（認証不要／手動認証のエージェント）または Copilot Studio クライアント SDK（Entra SSO）	公式
公開する	pac copilot publish または Dataverse PvaPublish	公式
クラウドフローを読み取り、作成、変更、削除する	Dataverse の workflow 行（clientdata 内の定義）	公式 API、実環境での形式は未検証
フローの接続をバインドする	clientdata の接続参照、またはソリューションから取り込まれたフローの connectionreference 行	公式 API、実環境での形式は未検証
フローの実行履歴、実行の開始	Power Automate Process Simple API	ポータルが呼び出すサービス、実環境では未検証
失敗した実行を説明し、成功した実行との差分を比較し、フローの信頼性を評価する	同じ API の実行ごとのアクションルートと、API が返す SAS 署名付きコンテンツリンク	このサーバー、実環境では未検証
最後の同期以降のポータルとの相違	ローカルの同期タイムスタンプと bot および botcomponent の各行を照合	このサーバー
テナント構成をファイルにする	pac admin の読み取りコマンドでフォルダーに出力	このサーバー

このサーバーが隠すのではなく、回避している厳格な制限：

1. 評価テストセットは API 経由で作成できません。 cs_create_test_set_csv は、ポータルにインポートする CSV を書き出します（最大 100 ケース）。一度インポートすれば、実行と結果の取得は自動化されます。
2. コネクタ、MCP、プロンプトのツールには、ポータルでしか承認できない接続が必要です。 cs_add_tool は YAML と接続参照のスタブを書き出し、ポータルでの手順を返します。 例外はサービスプリンシパルの Dataverse 接続で、これは cs_create_connection で作成できます。新しいクラウドフローがオフの状態で作成されるのも同じ制限によるものです。接続をバインドしてから cs_set_flow_state を実行してください。
3. 評価とトピック YAML は標準ハーネスの機能です。 GitHub Copilot ハーネスのエージェント（--authoring-mode cli-copilot）で使えるのは、init / pack / import / instructions / chat のみです。
4. Copilot Studio は会話が成功したかどうかを報告しません。 トランスクリプトツールはアクティビティから結果を推定します。各率は調査の手がかりとして扱い、アクションを実行する前にトランスクリプトを確認してください。
5. 環境に一度も接続されていないワークスペースでは、pack に含まれる内容が少なくなります。 pac 2.11.2 で確認済みです。--environment を指定せずに pac copilot init で作成したワークスペースに対して pac copilot pack を実行すると、settings、agent、topics のみがパッケージ化され、knowledge/、actions/、tools/、trigger/、variables/、workflows/、connectionreferences.mcs.yml は拒否されます。これらのフォルダーは、同期接続されたワークスペース（clone、または environment を指定した init）から pac copilot push で処理します。作成ツールは、pack のみのワークスペースである場合にその旨を通知します。

Microsoft 独自の pac MCP サーバーとの違い

Power Platform CLI には、組み込みの MCP サーバー（pac copilot mcp --run、プレビュー、「Power Platform Management MCP Server」という名称）が付属しています。これは pac 自体を自然言語で操作するためのフロントエンドで、各ツールは pac コマンドを 1 つ実行します。pac 2.11.2 で調べたところ、70 個のツールが公開されており、そのうち Copilot Studio に関するものは 1 つだけ（copilot_publish）です。51 個はテナント管理、マネージド ID、モデル駆動型アプリと生成ページ、Power Pages、コードアプリ、コード生成に関するものです。

	pac MCP サーバー（pac copilot mcp）	copilot-studio-mcp（このリポジトリ）
目的	自然言語で pac コマンドを実行し、テナントと環境を管理する	エディターから Copilot Studio エージェントを構築、テスト、公開、保守する
Copilot Studio のコマンド	copilot_publish のみ	初期化、クローン、プル、プッシュ、パック、公開、ステータス、一覧、削除、テンプレート、翻訳、隔離、AI Builder の手順
作成	なし	トピック、ナレッジソース、ツール（コネクタ／MCP／フロー／プロンプト／エージェント）、トリガー、変数、エージェント独自の設定を YAML で管理。2 日目以降の編集と削除、スキーマ検証（744 件の定義）、スコア付きのルールベースレビュー
テスト	なし	評価テストセットと実行（Power Platform API）、DirectLine またはクライアント SDK を使ったチャット、ローカルでの会話テスト、本番のトランスクリプト
ALM	ソリューションの一覧、エクスポート、インポート、チェック	デプロイ設定ファイルを使ってソリューション全体をプルし、1:1 で再デプロイ。Solution Checker、バージョン管理、段階的アップグレード、パイプライン、DTAP スナップショットと比較
差分	なし	最後の同期以降にポータルで行われた変更（Dataverse の簡易チェック、クローン全体の差分）と、競合時にブロックするプッシュ前チェック
安全性	サーバーにドライランはありません。唯一のゲートはクライアントの承認プロンプトです	環境を変更するすべてのツールは、confirm: true になるまでドライランを返します。ログと結果ではシークレットがマスクされます。CPS_READ_ONLY を設定すると書き込みツールはすべて利用できなくなります
テナント管理	管理コマンドをネイティブツールとして提供	管理コマンドに加え、cs_backup_tenant とユーザー一覧へのオンボーディングを、別の管理者認証プロファイルで実行
クラウドフロー	生の pac コマンド以外はなし	一覧表示、読み取り、作成、再構築、有効化／無効化、実行履歴、ステップベースの定義ビルダー
ガイダンス	ツールの説明	ハンドシェイク時の使用手順、cs_guide のウォークスルー、MCP プロンプト、ワークスペースごとの次の手順、引数エラーではなく実際の選択肢を提示する質問
その他の pac グループ	マネージド ID、モデル、ページ、コード、modelbuilder をネイティブツールとして提供	cs_pac から利用可能（読み取り専用コマンドは即時実行、それ以外は confirm が必要）
サインイン	pac 認証プロファイル	pac 認証プロファイルに加え、pac が対応していない API（評価、Dataverse の読み取り、環境、チャット）には MSAL を使用
ツール一覧	固定	プリセットと CPS_TOOLS ／ CPS_TOOLS_EXCLUDE でクライアントごとに絞り込み可能

どちらも stdio サーバーで、並べて登録できます。pac のサーバーはテナント管理に、こちらはエージェント作業に使えます。実用上の注意点として、pac のサーバーは起動時に stdout へ JSON ではない行を出力するため、厳格な MCP クライアントでは拒否される場合があります。

出典：組み込み MCP サーバーで Power Platform CLI を使用する、 pac 2.11.2 の tools/list の調査（2026-09-07）。

どのように連携するか

flowchart LR
    VS["VS Code / GitHub Copilot"] --> TOOLS
    CC["Claude Code"] --> TOOLS
    subgraph SERVER["copilot-studio-mcp"]
        TOOLS["MCP tool call"] --> SYNC["Sync layer: pac copilot, pac solution, pac admin"]
        TOOLS --> AUTH["Authoring layer: YAML + schema validation, flow builder"]
        TOOLS --> CLOUD["Cloud layer: evaluations, publish, chat, flows, drift"]
    end
    AUTH --> WS["Agent workspace on disk: topics, knowledge, actions, workflows"]
    SYNC --> WS
    SYNC --> DV["Dataverse / Copilot Studio"]
    SYNC --> BACKUP["Tenant backup and solution folders on disk"]
    CLOUD --> PPAPI["Power Platform API"]
    CLOUD --> DV
    CLOUD --> FLOW["Power Automate service: flow runs"]
    CLOUD --> DL["Published agent: DirectLine or SDK"]

実際のテナントでの検証

クラウドワークフローは、ドキュメントと公開されているスキーマに基づいて構築され、フェーズ A から F は 2026-09-08 に初めて実環境で検証されました。docs/verify.md は現在のフォローアップリストです。 docs/live-verification.md は完全な実行手順書です。フェーズ A から D は読み取り専用で、テナントに手を加えることなく、未解決の疑問のほとんどを解消します。フェーズ E から G は書き込みを行い、その旨が明記されています。docs/verification-template.md は記入する結果ファイルで、scripts/redact-verification.mjs は GUID、組織 URL、メールアドレス、トークンを安定した仮名に置き換えるため、結果を公開リポジトリから共有できます。 docs/STATUS.md は完全な履歴記録です。docs/test-verification.md はフィードバックループ（静的チェック、動作テスト、トランスクリプト、ループの完了）の実行手順書です。そのフェーズ 1 では、実環境のアクティビティに、会話テストが読み取るトピック、ツール、引用の帰属情報が含まれるかどうかを確認します。

開発

git clone https://github.com/jgt87/copilot-studio-mcp.git
cd copilot-studio-mcp
npm install
npm run build                 # dist/index.js is the server: register it as "command": "node", "args": ["<repo>/dist/index.js"]
npm test                      # build + unit tests (fixtures, no network)
node scripts/smoke.mjs        # drive the built server over stdio
node scripts/oracle-pack.mjs  # pac copilot init + authoring tools + pac copilot pack

reference/bot.schema.yaml-authoring.json と reference/templates は microsoft/skills-for-copilot-studio に由来します（MIT ライセンス。reference/LICENSE.skills-for-copilot-studio.txt を参照）。test/fixtures/pac-* のフィクスチャは pac copilot init で生成されました。

MIT ライセンス。