{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"mcp-m365-copilot","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Best practices for building MCP-based declarative agents and API plugins for Microsoft 365 Copilot with Model Context Protocol integration'\napplyTo: '**/{*mcp*,*agent*,*plugin*,declarativeAgent.json,ai-plugin.json,mcp.json,manifest.json}'\n---\n\n# MCP-based M365 Copilot Development Guidelines\n\n## Core Principles\n\n### Model Context Protocol First\n- Leverage MCP servers for external system integration\n- Import tools from server endpoints, not manual definitions\n- Let MCP handle schema discovery and function generation\n- Use point-and-click tool selection in Agents Toolkit\n\n### Declarative Over Imperative\n- Define agent behavior through configuration, not code\n- Use declarativeAgent.json for instructions and capabilities\n- Specify tools and actions in ai-plugin.json\n- Configure MCP servers in mcp.json\n\n### Security and Governance\n- Always use OAuth 2.0 or SSO for authentication\n- Follow principle of least privilege for tool selection\n- Validate MCP server endpoints are secure\n- Review compliance requirements before deployment\n\n### User-Centric Design\n- Create adaptive cards for rich visual responses\n- Provide clear conversation starters\n- Design for responsive experience across hubs\n- Test thoroughly before organizational deployment\n\n## MCP Server Design\n\n### Server Selection\nChoose MCP servers that:\n- Expose relevant tools for user tasks\n- Support secure authentication (OAuth 2.0, SSO)\n- Provide reliable uptime and performance\n- Follow MCP specification standards\n- Return well-structured response data\n\n### Tool Import Strategy\n- Import only necessary tools (avoid over-scoping)\n- Group related tools from same server\n- Test each tool individually before combining\n- Consider token limits when selecting multiple tools\n\n### Authentication Configuration\n**OAuth 2.0 Static Registration:**\n```json\n{\n  \"type\": \"OAuthPluginVault\",\n  \"reference_id\": \"YOUR_AUTH_ID\",\n  \"client_id\": \"github_client_id\",\n  \"client_secret\": \"github_client_secret\",\n  \"authorization_url\": \"https://github.com/login/oauth/authorize\",\n  \"token_url\": \"https://github.com/login/oauth/access_token\",\n  \"scope\": \"repo read:user\"\n}\n```\n\n**SSO (Microsoft Entra ID):**\n```json\n{\n  \"type\": \"OAuthPluginVault\",\n  \"reference_id\": \"sso_auth\",\n  \"authorization_url\": \"https://login.microsoftonline.com/common/oauth2/v2.0/authorize\",\n  \"token_url\": \"https://login.microsoftonline.com/common/oauth2/v2.0/token\",\n  \"scope\": \"User.Read\"\n}\n```\n\n## File Organization\n\n### Project Structure\n```\nproject-root/\n├── appPackage/\n│   ├── manifest.json           # Teams app manifest\n│   ├── declarativeAgent.json   # Agent config (instructions, capabilities)\n│   ├── ai-plugin.json          # API plugin definition\n│   ├── color.png               # App icon color\n│   └── outline.png             # App icon outline\n├── .vscode/\n│   └── mcp.json               # MCP server configuration\n├── .env.local                  # Credentials (NEVER commit)\n└── teamsapp.yml               # Teams Toolkit config\n```\n\n### Critical Files\n\n**declarativeAgent.json:**\n- Agent name and description\n- Instructions for behavior\n- Conversation starters\n- Capabilities (actions from plugins)\n\n**ai-plugin.json:**\n- MCP server tools import\n- Response semantics (data_path, properties)\n- Static adaptive card templates\n- Function definitions (auto-generated)\n\n**mcp.json:**\n- MCP server URL\n- Server metadata endpoint\n- Authentication reference\n\n**.env.local:**\n- OAuth client credentials\n- API keys and secrets\n- Environment-specific config\n- **CRITICAL**: Add to .gitignore\n\n## Response Semantics Best Practices\n\n### Data Path Configuration\nUse JSONPath to extract relevant data:\n```json\n{\n  \"data_path\": \"$.items[*]\",\n  \"properties\": {\n    \"title\": \"$.name\",\n    \"subtitle\": \"$.description\", \n    \"url\": \"$.html_url\"\n  }\n}\n```\n\n### Template Selection\nFor dynamic templates:\n```json\n{\n  \"data_path\": \"$\",\n  \"template_selector\": \"$.templateType\",\n  \"properties\": {\n    \"title\": \"$.title\",\n    \"url\": \"$.url\"\n  }\n}\n```\n\n### Static Templates\nDefine in ai-plugin.json for consistent formatting:\n- Use when all responses follow same structure\n- Better performance than dynamic templates\n- Easier to maintain and version control\n\n## Adaptive Card Guidelines\n\n### Design Principles\n- **Single-column layout**: Stack elements vertically\n- **Flexible widths**: Use \"stretch\" or \"auto\", not fixed pixels\n- **Responsive design**: Test in Chat, Teams, Outlook\n- **Minimal complexity**: Keep cards simple and scannable\n\n### Template Language Patterns\n**Conditionals:**\n```json\n{\n  \"type\": \"TextBlock\",\n  \"text\": \"${if(status == 'active', '✅ Active', '❌ Inactive')}\"\n}\n```\n\n**Data Binding:**\n```json\n{\n  \"type\": \"TextBlock\",\n  \"text\": \"${title}\",\n  \"weight\": \"bolder\"\n}\n```\n\n**Number Formatting:**\n```json\n{\n  \"type\": \"TextBlock\",\n  \"text\": \"Score: ${formatNumber(score, 0)}\"\n}\n```\n\n**Conditional Rendering:**\n```json\n{\n  \"type\": \"Container\",\n  \"$when\": \"${count(items) \u003e 0}\",\n  \"items\": [ ... ]\n}\n```\n\n### Card Elements Usage\n- **TextBlock**: Titles, descriptions, metadata\n- **FactSet**: Key-value pairs (status, dates, IDs)\n- **Image**: Icons, thumbnails (use size: \"small\")\n- **Container**: Grouping related content\n- **ActionSet**: Buttons for follow-up actions\n\n## Testing and Deployment\n\n### Local Testing Workflow\n1. **Provision**: Teams Toolkit → Provision\n2. **Deploy**: Teams Toolkit → Deploy\n3. **Sideload**: App uploaded to Teams\n4. **Test**: Visit [m365.cloud.microsoft/chat](https://m365.cloud.microsoft/chat)\n5. **Iterate**: Fix issues and re-deploy\n\n### Pre-Deployment Checklist\n- [ ] All MCP server tools tested individually\n- [ ] Authentication flow works end-to-end\n- [ ] Adaptive cards render correctly across hubs\n- [ ] Response semantics extract expected data\n- [ ] Error handling provides clear messages\n- [ ] Conversation starters are relevant and clear\n- [ ] Agent instructions guide proper behavior\n- [ ] Compliance and security reviewed\n\n### Deployment Options\n**Organization Deployment:**\n- IT admin deploys to all or selected users\n- Requires approval in Microsoft 365 admin center\n- Best for internal business agents\n\n**Agent Store:**\n- Submit to Partner Center for validation\n- Public availability to all Copilot users\n- Requires rigorous security review\n\n## Common Patterns\n\n### Multi-Tool Agent\nImport tools from multiple MCP servers:\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"url\": \"https://github-mcp.example.com\"\n    },\n    \"jira\": {\n      \"url\": \"https://jira-mcp.example.com\"\n    }\n  }\n}\n```\n\n### Search and Display\n1. Tool retrieves data from MCP server\n2. Response semantics extract relevant fields\n3. Adaptive card displays formatted results\n4. User can take action from card buttons\n\n### Authenticated Actions\n1. User triggers tool requiring auth\n2. OAuth flow redirects for consent\n3. Access token stored in plugin vault\n4. Subsequent requests use stored token\n\n## Error Handling\n\n### MCP Server Errors\n- Provide clear error messages in agent responses\n- Fall back to alternative tools if available\n- Log errors for debugging\n- Guide user to retry or alternative approach\n\n### Authentication Failures\n- Check OAuth credentials in .env.local\n- Verify scopes match required permissions\n- Test auth flow outside Copilot first\n- Ensure token refresh logic works\n\n### Response Parsing Failures\n- Validate JSONPath expressions in response semantics\n- Handle missing or null data gracefully\n- Provide default values where appropriate\n- Test with varied API responses\n\n## Performance Optimization\n\n### Tool Selection\n- Import only necessary tools (reduces token usage)\n- Avoid redundant tools from multiple servers\n- Test impact of each tool on response time\n\n### Response Size\n- Use data_path to filter unnecessary data\n- Limit result sets where possible\n- Consider pagination for large datasets\n- Keep adaptive cards lightweight\n\n### Caching Strategy\n- MCP servers should cache where appropriate\n- Agent responses may be cached by M365\n- Consider cache invalidation for time-sensitive data\n\n## Security Best Practices\n\n### Credential Management\n- **NEVER** commit .env.local to source control\n- Use environment variables for all secrets\n- Rotate OAuth credentials regularly\n- Use separate credentials for dev/prod\n\n### Data Privacy\n- Only request minimum necessary scopes\n- Avoid logging sensitive user data\n- Review data residency requirements\n- Follow compliance policies (GDPR, etc.)\n\n### Server Validation\n- Verify MCP server is trusted and secure\n- Check HTTPS endpoints only\n- Review server's privacy policy\n- Test for injection vulnerabilities\n\n## Governance and Compliance\n\n### Admin Controls\nAgents can be:\n- **Blocked**: Prevented from use\n- **Deployed**: Assigned to specific users/groups\n- **Published**: Made available organization-wide\n\n### Monitoring\nTrack:\n- Agent usage and adoption\n- Error rates and performance\n- User feedback and satisfaction\n- Security incidents\n\n### Audit Requirements\nMaintain:\n- Change history for agent configurations\n- Access logs for sensitive operations\n- Approval records for deployments\n- Compliance attestations\n\n## Resources and References\n\n### Official Documentation\n- [Build Declarative Agents with MCP (DevBlogs)](https://devblogs.microsoft.com/microsoft365dev/build-declarative-agents-for-microsoft-365-copilot-with-mcp/)\n- [Build MCP Plugins (Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/build-mcp-plugins)\n- [API Plugin Adaptive Cards (Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api-plugin-adaptive-cards)\n- [Manage Copilot Agents (Learn)](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-copilot-agents-integrated-apps)\n\n### Tools and SDKs\n- Microsoft 365 Agents Toolkit (VS Code extension v6.3.x+)\n- Teams Toolkit for agent packaging\n- Adaptive Cards Designer\n- MCP specification documentation\n\n### Partner Examples\n- monday.com: Task management integration\n- Canva: Design automation\n- Sitecore: Content management\n","description":"Best practices for building MCP-based declarative agents and API plugins for Microsoft 365 Copilot with Model Context Protocol integration","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/mcp-m365-copilot.instructions.md"},"manifest":{}},"content_hash":[229,46,110,92,198,230,191,20,254,5,51,10,170,133,11,164,153,137,133,136,144,23,231,215,154,4,64,12,59,152,114,44],"trust_level":"unsigned","yanked":false}