Mcp-M365-Copilot

# MCP-based M365 Copilot Development Guidelines

Core Principles

Model Context Protocol First

- Leverage MCP servers for external system integration

- Import tools from server endpoints, not manual definitions

- Let MCP handle schema discovery and function generation

- Use point-and-click tool selection in Agents Toolkit

Declarative Over Imperative

- Define agent behavior through configuration, not code

- Use declarativeAgent.json for instructions and capabilities

- Specify tools and actions in ai-plugin.json

- Configure MCP servers in mcp.json

Security and Governance

- Always use OAuth 2.0 or SSO for authentication

- Follow principle of least privilege for tool selection

- Validate MCP server endpoints are secure

- Review compliance requirements before deployment

User-Centric Design

- Create adaptive cards for rich visual responses

- Provide clear conversation starters

- Design for responsive experience across hubs

- Test thoroughly before organizational deployment

MCP Server Design

Server Selection

Choose MCP servers that:

- Expose relevant tools for user tasks

- Support secure authentication (OAuth 2.0, SSO)

- Provide reliable uptime and performance

- Follow MCP specification standards

- Return well-structured response data

Tool Import Strategy

- Import only necessary tools (avoid over-scoping)

- Group related tools from same server

- Test each tool individually before combining

- Consider token limits when selecting multiple tools

Authentication Configuration

**OAuth 2.0 Static Registration:**

{
  "type": "OAuthPluginVault",
  "reference_id": "YOUR_AUTH_ID",
  "client_id": "github_client_id",
  "client_secret": "github_client_secret",
  "authorization_url": "https://github.com/login/oauth/authorize",
  "token_url": "https://github.com/login/oauth/access_token",
  "scope": "repo read:user"
}

**SSO (Microsoft Entra ID):**

{
  "type": "OAuthPluginVault",
  "reference_id": "sso_auth",
  "authorization_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
  "token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
  "scope": "User.Read"
}

File Organization

Project Structure

project-root/
├── appPackage/
│   ├── manifest.json           # Teams app manifest
│   ├── declarativeAgent.json   # Agent config (instructions, capabilities)
│   ├── ai-plugin.json          # API plugin definition
│   ├── color.png               # App icon color
│   └── outline.png             # App icon outline
├── .vscode/
│   └── mcp.json               # MCP server configuration
├── .env.local                  # Credentials (NEVER commit)
└── teamsapp.yml               # Teams Toolkit config

Critical Files

**declarativeAgent.json:**

- Agent name and description

- Instructions for behavior

- Conversation starters

- Capabilities (actions from plugins)

**ai-plugin.json:**

- MCP server tools import

- Response semantics (data_path, properties)

- Static adaptive card templates

- Function definitions (auto-generated)

**mcp.json:**

- MCP server URL

- Server metadata endpoint

- Authentication reference

**.env.local:**

- OAuth client credentials

- API keys and secrets

- Environment-specific config

- **CRITICAL**: Add to .gitignore

Response Semantics Best Practices

Data Path Configuration

Use JSONPath to extract relevant data:

{
  "data_path": "$.items[*]",
  "properties": {
    "title": "$.name",
    "subtitle": "$.description", 
    "url": "$.html_url"
  }
}

Template Selection

For dynamic templates:

{
  "data_path": "$",
  "template_selector": "$.templateType",
  "properties": {
    "title": "$.title",
    "url": "$.url"
  }
}

Static Templates

Define in ai-plugin.json for consistent formatting:

- Use when all responses follow same structure

- Better performance than dynamic templates

- Easier to maintain and version control

Adaptive Card Guidelines

Design Principles

- **Single-column la