The Citadel · 20 min mission
MCP Plugins and Custom Tools for Microsoft Copilot
Expose live enterprise tools to Copilot through MCP while keeping auth, policy, approval, idempotency, and audit server-side.
Orientation
This guide is for teams deciding whether MCP should be the tool layer behind a Microsoft Copilot agent. It covers the Microsoft 365 declarative-agent MCP plugin path, Copilot Studio MCP tools, federated connector distinctions, and safe tool contracts.
MCP gives Microsoft Copilot a task-level tool contract through a remote server. In the Microsoft 365 extensibility path, a declarative agent can reference a RemoteMCPServer action. In Copilot Studio, MCP can also appear as an action path for existing MCP servers. The design question is not "can the model call a tool?" It is "does the server expose a small, governed, auditable set of tools?"
Use MCP when a single enterprise task needs several live operations, policy checks, optional UI widgets, or a prepare/commit write contract. Use a simple API plugin when one REST facade is enough. Use a connector when the goal is searchable read-only grounding.
Use This When / Avoid This When
Use MCP when
A remote server should own a related tool family: live reads, policy checks, normalized source adapters, approval previews, optional widgets, queues, and idempotent commits.
Avoid MCP when
One OpenAPI operation is enough, the goal is broad search/citations, or the organization cannot operate a remote server with auth, logging, rate limits, DLP review, and incident response.
How to use this interactive section
The MCP Tool Contract Planner is a trust-boundary exercise. It helps you decide which tools belong on the server and which controls must be enforced outside the model.
- Select the tool type: read, prepare, commit, or admin.
- Review how the auth, policy, idempotency, and audit obligations change.
- Compare the output with the tool catalog table below.
- Remove tools that combine unrelated systems, bypass approval, or mutate data without a re-read.
- Use the final catalog as the checklist for server implementation and security review.
MCP Tool Contract Planner
MCP tool contract planner
Give Copilot tools one bounded job
Microsoft 365 Copilot can call remote MCP tools through a declarative agent. The server contract still has to enforce auth, policy, idempotency, and audit.
prepare_confluence_publish
Build a Confluence page preview and an approval token without creating or updating the page.
Inputs
- - spaceKey
- - title
- - reportPayload
- - templateId
Outputs
- - previewHtml
- - approvalId
- - idempotencyKey
- - diffSummary
| Surface | What MCP does there | Guide caveat |
|---|---|---|
| Declarative agent MCP plugin | A Microsoft 365 Copilot declarative agent references a RemoteMCPServer runtime in the plugin manifest | It is still an action inside a declarative agent, not a universal tool added to base Copilot Chat |
| Copilot Studio MCP tool | A custom agent can connect to an existing MCP server and use tools/resources with generative orchestration | Copilot Studio onboarding, auth choices, DLP, and dynamic reflection differ from the declarative-agent package path |
| MCP Apps/widgets | An MCP response can render supported interactive UI in Microsoft 365 Copilot when packaged for that path | Do not assume every OpenAI Apps SDK or generic MCP widget field is supported |
| Federated Copilot connector | Uses MCP for live read-only retrieval without indexing external content into Microsoft 365 | It is not a write tool and should not publish, transition, update, or notify |
| Use MCP when | Use something else when | Control to enforce |
|---|---|---|
| The task is best described as a curated tool set such as search, build report, preview publish, commit publish | One stable REST operation with OpenAPI metadata is enough | Tool names and descriptions must be task-level and business-specific |
| The server needs server-side policy, identity checks, source adapters, and audit in one place | The content only needs read-only search and citations | Every tool call must enforce tenant, project, space, and user authorization |
| Writes must be split into prepare and commit with approval and idempotency | A user only needs a one-off draft in Word, Teams, or Outlook | Commit tools must re-read live state immediately before mutation |
| Tool class | Example | Required server control |
|---|---|---|
| Read/search | jira_search_issues, confluence_search_pages | End-user auth, source allowlists, field caps, pagination, rate-limit handling, source URLs, and partial-result warnings |
| Analyze/build | jira_build_release_risk_report | Deterministic rules, bounded inputs, evidence links, missing-evidence warnings, and no writes |
| Prepare write | prepare_confluence_publish | Preview, target object, diff, approval ID, expiry, payload hash, and idempotency key with no mutation |
| Commit write | commit_confluence_publish | Approval validation, live re-read, version conflict detection, single write, audit record, and rollback metadata |
| Admin/diagnostic | connector_health_check | Restricted roles, minimized output, no secrets, and explicit audit logging |
{
"tools": [
{
"name": "jira_search_issues",
"description": "Run the approved ACME-OPS release JQL and return bounded source-linked issue facts. Does not mutate Jira."
},
{
"name": "jira_build_release_risk_report",
"description": "Build a release risk report from normalized issue facts with citations and missing-evidence warnings."
},
{
"name": "prepare_confluence_publish",
"description": "Create a Confluence preview and approval record. Does not create or update a page."
},
{
"name": "commit_confluence_publish",
"description": "After approval, re-read Confluence version, write once with idempotency, and persist audit."
}
]
}Write-capable MCP tool sequence
Read live source state
Search Jira or Confluence with server-side allowlists, paging, field caps, and source URLs. Return structured facts and partial-result warnings.
Prepare the write
Generate a preview, target object, diff summary, approval ID, expiry, and idempotency key. Do not write in this step.
Collect approval
Persist approval outside the transcript, including approver, timestamp, payload hash, target space or project, and expiration.
Commit after re-read
The commit tool re-reads the target version, checks the approval and payload hash, writes once, and records an audit event.
| Symptom | Likely cause | Recovery step |
|---|---|---|
| No tools appear | Server not running, wrong URL, packaging fetched stale tools, or project lifecycle did not start the server | Start the server, refetch selected tools, verify manifest references, and confirm the reachable HTTPS endpoint |
| Tool selected but answer ignores output | Output is too large, weakly structured, or lacks fields the model can summarize | Return concise JSON with source URLs, warnings, and a reader-ready result object |
| OAuth works locally but not in tenant | Redirect URI, dynamic client registration, consent, or provider metadata differs | Verify redirect URIs, scopes, authorization-server metadata, and tenant consent from a clean user session |
| Read-only tool still asks for confirmation | Tool annotations or platform behavior may not match the desired UX | Separate read and write tools, annotate read-only behavior where supported, and test the target tenant/client |
| Widget fails to render | Unsupported UI metadata, CORS/host URL issue, or auth bridge mismatch | Test plain JSON first, then add only supported widget fields and required redirect/CORS configuration |
Knowledge check
Which MCP tool design is safest for publishing a Confluence report?
Reach the end and this star joins your charted sky.