references/mcp-plugin.md · 24000
a specific claim with key details. Use claim ID or claim number.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } }, { "name": "create-inspection", "description": "Creates a new inspection record. Only claimNumber is required. ID is auto-generated, status defaults to 'open'. claimId is optional.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } }, { "name": "list-inspectors", "description": "Lists all available inspectors with their specializations.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } } ], "runtimes": [ { "type": "RemoteMCPServer", "auth": { "type": "None" }, "spec": { "url": "https://zava-insurance-mcp.azurewebsites.net/mcp", "mcp_tool_description": { "tools": [ { "name": "show-claims-dashboard", "description": "Displays the Zava Insurance claims dashboard showing all claims with status overview, filters, and summary metrics. Supports filtering by status and/or policy holder name. When the user mentions a person's name, first name, last name, or partial name, always pass it as the policyHolderName parameter. The name filter is case-insensitive and supports partial matches.", "inputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "Filter claims by status keyword (e.g. 'Open', 'Approved', 'Pending', 'Denied', 'Closed')" }, "policyHolderName": { "type": "string", "description": "Filter claims by policy holder name. Supports partial, case-insensitive matching." } }, "additionalProperties": false }, "annotations": { "readOnlyHint": true }, "execution": { "taskSupport": "forbidden" }, "_meta": { "ui": { "resourceUri": "ui://zava/claims-dashboard.html" } } }, { "name": "show-claim-detail", "description": "Displays detailed information about a specific insurance claim including related inspections, purchase orders, and contractor assignments. Use claim ID (e.g. '1', '2') or claim number (e.g. 'CN202504990').", "inputSchema": { "type": "object", "properties": { "claimId": { "type": "string", "description": "The claim ID or claim number to look up" } }, "required": ["claimId"], "additionalProperties": false }, "annotations": { "readOnlyHint": true }, "execution": { "taskSupport": "forbidden" }, "_meta": { "ui": { "resourceUri": "ui://zava/claim-detail.html" } } }, { "name": "show-contractors", "description": "Displays the list of contractors available for insurance repair work. Optionally filter by specialty or preferred status.", "inputSchema": { "type": "object", "properties": { "specialty": { "type": "string", "description": "Filter by contractor specialty (e.g. 'Roofing', 'Water Damage', 'Fire')" }, "preferredOnly": { "type": "boolean", "description": "Show only preferred contractors" } }, "additionalProperties": false }, "annotations": { "readOnlyHint": true }, "execution": { "taskSupport": "forbidden" }, "_meta": { "ui": { "resourceUri": "ui://zava/contractors-list.html" } } }, { "name": "update-claim-status", "description": "Updates the status of an insurance claim. Use claim ID (e.g. '1', '2').", "inputSchema": { "type": "object", "properties": { "claimId": { "type": "string", "description": "The claim ID" }, "status": { "type": "string", "description": "New status (e.g. 'Approved', 'Denied', 'Closed', 'Open - Under Investigation')" }, "note": { "type": "string", "description": "Optional note to add to the claim" } }, "required": ["claimId", "status"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "update-inspection", "description": "Updates an inspection record — status, findings, recommended actions, property, or inspector assignment.", "inputSchema": { "type": "object", "properties": { "inspectionId": { "type": "string", "description": "The inspection ID (e.g. 'insp-001')" }, "status": { "type": "string", "description": "New status (e.g. 'completed', 'scheduled', 'in-progress', 'cancelled')" }, "findings": { "type": "string", "description": "Updated findings text" }, "recommendedActions": { "type": "array", "items": { "type": "string" }, "description": "Updated recommended actions" }, "property": { "type": "string", "description": "Updated property address" }, "inspectorId": { "type": "string", "description": "Inspector ID to assign (e.g. 'inspector-003')" } }, "required": ["inspectionId"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "update-purchase-order", "description": "Updates a purchase order status (e.g. approve, reject, complete).", "inputSchema": { "type": "object", "properties": { "purchaseOrderId": { "type": "string", "description": "The purchase order ID (e.g. 'po-001')" }, "status": { "type": "string", "description": "New status (e.g. 'approved', 'rejected', 'completed', 'in-progress')" }, "note": { "type": "string", "description": "Optional note to add" } }, "required": ["purchaseOrderId", "status"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "get-claim-summary", "description": "Returns a text summary for a specific claim with key details. Use claim ID or claim number.", "inputSchema": { "type": "object", "properties": { "claimId": { "type": "string", "description": "Claim ID or claim number" } }, "required": ["claimId"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "create-inspection", "description": "Creates a new inspection record. Only claimNumber is required. ID is auto-generated, status defaults to 'open'. claimId is optional.", "inputSchema": { "type": "object", "properties": { "claimNumber": { "type": "string", "description": "The claim number (e.g. 'CN202504990')" }, "claimId": { "type": "string", "description": "Optional claim ID" }, "taskType": { "type": "string", "description": "Type of inspection: 'initial', 're-inspection', 'final'. Defaults to 'initial'" }, "priority": { "type": "string", "description": "Priority: 'low', 'medium', 'high'. Defaults to 'medium'" }, "status": { "type": "string", "description": "Status. Defaults to 'open'" }, "scheduledDate": { "type": "string", "description": "Scheduled date (ISO string)" }, "inspectorId": { "type": "string", "description": "Inspector ID to assign" }, "property": { "type": "string", "description": "Property address" }, "instructions": { "type": "string", "description": "Inspection instructions" } }, "required": ["claimNumber"], "additionalProperties": false }, "execution": { "taskSupport": "forbidden" } }, { "name": "list-inspectors", "description": "Lists all available inspectors with their specializations.", "inputSchema": { "type": "object", "properties": {} }, "execution": { "taskSupport": "forbidden" } } ] } }, "run_for_functions": [ "show-claims-dashboard", "show-claim-detail", "show-contractors", "update-claim-status", "update-inspection", "update-purchase-order", "get-claim-summary", "create-inspection", "list-inspectors" ] } ] }
> **Note how tools with UI widgets** (e.g., `show-claims-dashboard`, `show-claim-detail`, `show-contractors`) include `annotations`, `execution`, AND `_meta` with `resourceUri` — all copied verbatim from the tools/list response. Tools without UI (e.g., `update-claim-status`) still include `execution` when the server returned it, but omit `annotations` and `_meta` since the server didn't provide them.
Register in `declarative-agent.json`: `{ "actions": [{ "id": "zavaPlugin", "file": "zava-plugin.json" }] }`
---
## Complete Example — Authenticated Server
For an OAuth-protected MCP server at `https://mcp.example.com/mcp`. See [authentication.md](authentication.md) for the full `oauth/register` template (must be added to both `m365agents.yml` and `m365agents.local.yml`).
### `appPackage/example-plugin.json`
```json
{
"$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.4/schema.json",
"schema_version": "v2.4",
"name_for_human": "Example Service",
"description_for_human": "Search and browse Example Service content",
"namespace": "example",
"functions": [
{
"name": "search",
"description": "Search Example Service for content matching a query.",
"capabilities": { "response_semantics": { "data_path": "$.items", "properties": { "title": "$.title", "url": "$.url" }, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "[${title}](${url})", "wrap": true, "maxLines": 2 }] } } }
}
],
"runtimes": [
{
"type": "RemoteMCPServer",
"auth": { "type": "OAuthPluginVault", "reference_id": "${{<PREFIX>_MCP_AUTH_ID}}" },
"spec": {
"url": "https://mcp.example.com/mcp",
"mcp_tool_description": {
"tools": [
{ "name": "search", "description": "Search Example Service for content matching a query.", "inputSchema": { "type": "object", "properties": { "query": { "description": "Search query", "type": "string" } }, "required": ["query"] } }
]
}
},
"run_for_functions": ["search"]
}
]
}
Multiple MCP Servers
You can integrate multiple MCP servers by adding multiple runtimes, each with its own auth type. Each runtime has its own mcp_tool_description.tools and run_for_functions:
{
"functions": [
{ "name": "docs_search", "description": "Search Microsoft docs.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } },
{ "name": "search", "description": "Search authenticated service.", "capabilities": { "response_semantics": { "data_path": "$", "properties": {}, "static_template": { "type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.6", "body": [{ "type": "TextBlock", "text": "${if(title, title, description)}", "wrap": true }] } } } }
],
"runtimes": [
{
"type": "RemoteMCPServer",
"auth": { "type": "None" },
"spec": { "url": "https://learn.microsoft.com/api/mcp", "mcp_tool_description": { "tools": [{ "name": "docs_search", "description": "Search Microsoft docs.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] } }] } },
"run_for_functions": ["docs_search"]
},
{
"type": "RemoteMCPServer",
"auth": { "type": "OAuthPluginVault", "reference_id": "${{<PREFIX>_MCP_AUTH_ID}}" },
"spec": { "url": "https://mcp.example.com/mcp", "mcp_tool_description": { "tools": [{ "name": "search", "description": "Search authenticated service.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] } }] } },
"run_for_functions": ["search"]
}
]
}
Common Issues
| Issue | Solution |
|---|---|
| Plugin fails to load | Verify {name}-plugin.json exists and has correct mcp_tool_description.tools array |
| Tools not recognized | Verify function names match exactly between functions[] and mcp_tool_description.tools[] |
| Runtime errors | Check that run_for_functions includes all functions using that runtime |
| OAuth token errors | Re-authenticate with mcp-remote — cached tokens may have expired |
| <PREFIX>_MCP_AUTH_ID empty | Check oauth/register step in both m365agents.yml and m365agents.local.yml and verify credentials |
| "Invalid redirect URI" | Ensure redirect URI in DCR is https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect |
Best Practices
- Always discover tools via MCP protocol — run the full handshake (initialize → notifications/initialized → tools/list) before writing the plugin manifest. NEVER fabricate tool names or descriptions.
- Full-fidelity tool copying in
mcp_tool_description.tools— each tool object must be a verbatim copy of the tools/list output. Copy every property exactly as returned (inputSchema,annotations,execution,_meta,outputSchema,title, and any other field). The MCP protocol evolves — do NOT maintain a hardcoded allowlist of known fields. If the server returns it, the plugin must include it. Never abbreviate, omit, or rename properties. Do NOT duplicateinputSchemaor other properties infunctions[]. - Inline tools in
mcp_tool_description.tools— do NOT use a separate tools file; embed the tools array directly in the runtime spec - Match function names exactly — copy tool names directly from the tools/list output
- Always add response semantics — every function must have
capabilities.response_semantics, even if using the default (empty body) pattern - Include all tools by default — inline every tool from
tools/listunless the developer explicitly asks to limit the set; for all included tools always keep the complete tool object with all properties - Logos are optional — ask the user if they want a custom logo; if not, use the defaults from
npx -y --package @microsoft/m365agentstoolkit-cli atk new. Logos must be PNG only (no JPG, SVG, etc.)