mcp-create-declarative-agent

---
mode: 'agent'
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
description: 'Create a declarative agent for Microsoft 365 Copilot by integrating an MCP server with authentication, tool selection, and configuration'
model: 'gpt-4.1'
tags: [mcp, m365-copilot, declarative-agent, model-context-protocol, api-plugin]
---

# Create MCP-based Declarative Agent for Microsoft 365 Copilot

Create a complete declarative agent for Microsoft 365 Copilot that integrates with a Model Context Protocol (MCP) server to access external systems and data.

## Requirements

Generate the following project structure using Microsoft 365 Agents Toolkit:

### Project Setup
1. **Scaffold declarative agent** via Agents Toolkit
2. **Add MCP action** pointing to MCP server
3. **Select tools** to import from MCP server
4. **Configure authentication** (OAuth 2.0 or SSO)
5. **Review generated files** (manifest.json, ai-plugin.json, declarativeAgent.json)

### Key Files Generated

**appPackage/manifest.json** - Teams app manifest with plugin reference:
```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
  "manifestVersion": "devPreview",
  "version": "1.0.0",
  "id": "...",
  "developer": {
    "name": "...",
    "websiteUrl": "...",
    "privacyUrl": "...",
    "termsOfUseUrl": "..."
  },
  "name": {
    "short": "Nome do Agente",
    "full": "Nome Completo do Agente"
  },
  "description": {
    "short": "Descrição curta",
    "full": "Descrição completa"
  },
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "declarativeAgent",
        "file": "declarativeAgent.json"
      }
    ]
  }
}
```

**appPackage/declarativeAgent.json** - Agent definition:
```json
{
  "$schema": "https://aka.ms/json-schemas/copilot/declarative-agent/v1.0/schema.json",
  "version": "v1.0",
  "name": "Nome do Agente",
  "description": "Descrição do Agente",
  "instructions": "Você é um assistente que ajuda com [domínio específico]. Use as ferramentas disponíveis para [capacidades].",
  "capabilities": [
    {
      "name": "WebSearch",
      "websites": [
        {
          "url": "https://learn.microsoft.com"
        }
      ]
    },
    {
      "name": "MCP",
      "file": "ai-plugin.json"
    }
  ]
}
```

**appPackage/ai-plugin.json** - MCP plugin manifest:
```json
{
  "schema_version": "v2.1",
  "name_for_human": "Nome do Serviço",
  "description_for_human": "Descrição para usuários",
  "description_for_model": "Descrição para o modelo de IA",
  "contact_email": "suporte@empresa.com",
  "namespace": "nomeDoServico",
  "capabilities": {
    "conversation_starters": [
      {
        "text": "Exemplo de consulta 1"
      }
    ]
  },
  "functions": [
    {
      "name": "nomeDaFuncao",
      "description": "Descrição da função",
      "capabilities": {
        "response_semantics": {
          "data_path": "$",
          "properties": {
            "title": "$.title",
            "subtitle": "$.description"
          }
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "MCP",
      "spec": {
        "url": "https://api.servico.com/mcp/"
      },
      "run_for_functions": ["nomeDaFuncao"],
      "auth": {
        "type": "OAuthPluginVault",
        "reference_id": "${{OAUTH_REFERENCE_ID}}"
      }
    }
  ]
}
```

**/.vscode/mcp.json** - MCP server configuration:
```json
{
  "serverUrl": "https://api.servico.com/mcp/",
  "pluginFilePath": "appPackage/ai-plugin.json"
}
```

## MCP Server Integration

### Supported MCP Endpoints
The MCP server must provide:
- **Server metadata** endpoint
- **Tools listing** endpoint (exposes available functions)
- **Tool execution** endpoint (handles function calls)

### Tool Selection
When importing from MCP:
1. Fetch available tools from server
2. Select specific tools to include (for security/simplicity)
3. Tool definitions are auto-generated in ai-plugin.json

### Authentication Types

**OAuth 2.0 (Static Registration)**
```json
"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "${{OAUTH_REFERENCE_ID}}",
  "authorization_url": "https://auth.servico.com/authorize",
  "client_id": "${{CLIENT_ID}}",
  "client_secret": "${{CLIENT_SECRET}}",
  "scope": "read write"
}
```

**Single Sign-On (SSO)**
```json
"auth": {
  "type": "SSO"
}
```

## Response Semantics

### Define Data Mapping
Use `response_semantics` to extract relevant fields from API responses:

```json
"capabilities": {
  "response_semantics": {
    "data_path": "$.results",

…