Approval Workflow — MCP App for Microsoft 365 Copilot

An enterprise-grade Model Context Protocol (MCP) server built on C# .NET 8 that surfaces approval workflow management directly inside Microsoft 365 Copilot. Approvers can query, approve, reject, and delegate requests using natural language — with a rich interactive widget rendered inline in the Copilot chat pane.

Architecture

┌─────────────────────────────────────────────┐
│          Microsoft 365 Copilot              │
│  (BizChat / Teams / Copilot Studio)         │
└────────────────┬────────────────────────────┘
                 │ MCP over HTTPS (Streamable HTTP)
                 ▼
┌─────────────────────────────────────────────┐
│     ApprovalWorkflow.McpServer              │
│     ASP.NET Core 8  ·  Azure App Service    │
│                                             │
│  ┌─────────────────┐  ┌──────────────────┐  │
│  │  MCP Tools      │  │  MCP Resource    │  │
│  │  ─ QueryTool    │  │  ─ Widget HTML   │  │
│  │  ─ DecisionTool │  │    (ui://)       │  │
│  └────────┬────────┘  └──────────────────┘  │
│           │                                 │
│  ┌────────▼────────────────────────────┐    │
│  │  ApprovalWorkflow.Infrastructure    │    │
│  │  ─ ApprovalService (EF Core)        │    │
│  │  ─ GraphNotificationService         │    │
│  └────────┬────────────────────────────┘    │
└───────────┼─────────────────────────────────┘
            │
   ┌────────┴────────────┐
   │                     │
   ▼                     ▼
Azure SQL            Microsoft Graph
(Approval data)      (Teams + Email notifications)

Security: All MCP endpoints are protected by Entra ID (JWT bearer auth). The App Service uses Easy Auth as an additional layer. Secrets are stored exclusively in Azure Key Vault, accessed via the App Service Managed Identity.

Solution Structure

ApprovalWorkflow/
├── ApprovalWorkflow.sln
├── src/
│   ├── ApprovalWorkflow.McpServer/          # ASP.NET Core 8 — MCP host
│   │   ├── Tools/
│   │   │   ├── ApprovalQueryTool.cs         # GetPendingApprovals, GetApprovalDetails
│   │   │   └── ApprovalDecisionTool.cs      # ApproveRequest, RejectRequest, DelegateRequest
│   │   ├── Resources/
│   │   │   └── ApprovalWidgetResource.cs    # Serves widget HTML at ui://approval/widget.html
│   │   ├── wwwroot/widget/index.html        # Copilot-rendered approval widget
│   │   ├── Program.cs
│   │   └── appsettings.json
│   ├── ApprovalWorkflow.Core/               # Domain models & interfaces
│   │   ├── Models/
│   │   │   ├── ApprovalRequest.cs
│   │   │   ├── ApprovalDecision.cs
│   │   │   └── ApprovalStatus.cs
│   │   └── Interfaces/
│   │       ├── IApprovalService.cs
│   │       └── INotificationService.cs
│   └── ApprovalWorkflow.Infrastructure/     # EF Core + Microsoft Graph
│       ├── Data/AppDbContext.cs
│       └── Services/
│           ├── ApprovalService.cs
│           └── GraphNotificationService.cs
├── frontend/widget/index.html               # Source copy of the widget
├── infra/main.bicep                         # Azure infrastructure (IaC)
└── .vscode/
    ├── mcp.json                             # Local MCP client config
    ├── launch.json
    └── tasks.json

Prerequisites

Entra ID App Registration

A Global Administrator or Application Administrator must complete this section once.

1. Open Entra admin centre → App registrations → New registration

2. Name: ApprovalWorkflow-MCP

3. Supported account types: Single tenant

4. Redirect URI: https://<your-app>.azurewebsites.net/.auth/login/aad/callback

5. Expose an API:

   • Set Application ID URI: api://<client-id>
   • Add scope: Approvals.ReadWrite (Admin + user consent)

6. API permissions (Application permissions — grant admin consent):

   Permission	Purpose
   User.ReadBasic.All	Resolve approver email to Entra Object ID
   Chat.Create	Create 1:1 Teams chats for notifications
   ChatMessage.Send	Send Adaptive Cards via Teams
   Mail.Send	Send decision email notifications

7. Certificates & secrets → New client secret → copy value immediately

8. Store the secret in Key Vault (see Key Vault Setup)

9. Note your Tenant ID, Client ID, and Application ID URI for configuration

Key Vault Setup

# Create Key Vault (or use the Bicep deployment below)
az keyvault create \
  --name <vault-name> \
  --resource-group <rg> \
  --location <region>

# Store secrets — note the double-dash delimiter which maps to ':' in ASP.NET Core config
az keyvault secret set --vault-name <vault-name> \
  --name "AzureAd--ClientSecret" --value "<client-secret>"

az keyvault secret set --vault-name <vault-name> \
  --name "ConnectionStrings--AzureSql" \
  --value "Server=<server>.database.windows.net;Database=ApprovalWorkflow;Authentication=Active Directory Managed Identity;"

az keyvault secret set --vault-name <vault-name> \
  --name "ApplicationInsights--ConnectionString" --value "<ai-connection-string>"

Configuration

appsettings.json contains placeholder values. In production all secrets are resolved from Key Vault via Managed Identity. For local development use User Secrets.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<your-client-id>",
    "ClientSecret": "<from-key-vault>",
    "Audience": "api://<your-client-id>"
  },
  "ConnectionStrings": {
    "AzureSql": "<from-key-vault>"
  },
  "KeyVault": {
    "Uri": "https://<vault-name>.vault.azure.net/"
  },
  "ApprovalWorkflow": {
    "AppUrl": "https://<app-service-name>.azurewebsites.net",
    "NotificationMailbox": "approvals@yourdomain.com"
  },
  "ApplicationInsights": {
    "ConnectionString": "<from-key-vault>"
  }
}

Local Development

1. Clone and restore

git clone <repo-url>
cd ApprovalWorkflow
dotnet restore

2. Set User Secrets

cd src/ApprovalWorkflow.McpServer

dotnet user-secrets set "AzureAd:TenantId"     "<your-tenant-id>"
dotnet user-secrets set "AzureAd:ClientId"     "<your-client-id>"
dotnet user-secrets set "AzureAd:ClientSecret" "<your-client-secret>"
dotnet user-secrets set "ConnectionStrings:AzureSql" "Server=localhost;Database=ApprovalWorkflow;Trusted_Connection=True;TrustServerCertificate=True;"
dotnet user-secrets set "ApprovalWorkflow:NotificationMailbox" "approvals@yourdomain.com"
dotnet user-secrets set "ApprovalWorkflow:AppUrl" "https://localhost:7001"

3. Apply EF Core migrations

# From solution root
dotnet ef migrations add InitialCreate `
  --project src/ApprovalWorkflow.Infrastructure `
  --startup-project src/ApprovalWorkflow.McpServer

dotnet ef database update `
  --project src/ApprovalWorkflow.Infrastructure `
  --startup-project src/ApprovalWorkflow.McpServer

4. Run

dotnet run --project src/ApprovalWorkflow.McpServer
# Listening on https://localhost:7001

5. Verify the MCP handshake

POST https://localhost:7001/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "test", "version": "1.0" }
  }
}

Expected: a JSON response listing ApprovalWorkflow.McpServer with tools and resources capabilities.

6. Expose locally for Copilot testing

# Azure Dev Tunnels CLI (recommended — Microsoft-hosted, no auth challenge)
devtunnel user login
devtunnel host -p 7001 --allow-anonymous

Or use the VS Code Ports panel: forward port 7001 and set visibility to Public.

MCP Tools Reference

All tools resolve the caller's identity from the oid JWT claim set by Entra ID. Unauthenticated requests return 401 Unauthorized.

Category Filter Values

The category parameter on GetPendingApprovals is a free-form string. Recommended conventions:

Azure Deployment

Option A — Bicep (recommended)

# Create resource group
az group create --name rg-approval-workflow --location uksouth

# Deploy all infrastructure
az deployment group create \
  --resource-group rg-approval-workflow \
  --template-file infra/main.bicep \
  --parameters appName=approval-workflow \
               sqlAdminPassword='<secure-password>'

The Bicep template provisions:

Option B — VS Code Azure App Service extension

1. Install the Azure App Service extension
2. Ctrl+Shift+P → "Azure App Service: Deploy to Web App"
3. Select Create new Web App → .NET 8 → Linux
4. After deployment, add KeyVault__Uri to App Settings in the Azure portal

Post-deployment checklist

• Grant App Service Managed Identity get + list on Key Vault secrets
• Add all three secrets to Key Vault (ClientSecret, AzureSql connection string, App Insights connection string)
• Configure Easy Auth with your Entra App Registration Tenant ID and Client ID
• Set ApprovalWorkflow:AppUrl App Setting to the live App Service hostname
• EF migrations run automatically at first startup via MigrateAsync()

Connecting to Microsoft 365 Copilot

Via Copilot Studio

1. Go to copilotstudio.microsoft.com
2. Create → New agent → Configure tab
3. Scroll to Tools → Add a tool → Model Context Protocol
4. Fill in:
   • Server name: ApprovalWorkflow
   • Server description: Manages pending approval requests for the authenticated user
   • Server URL: https://<your-app>.azurewebsites.net/mcp
   • Authentication: OAuth 2.0 (configure with your Entra App Registration)
5. Publish → Channels → Microsoft Teams and Microsoft 365 Copilot

Via .vscode/mcp.json (local development only)

{
  "servers": {
    "approval-workflow": {
      "type": "http",
      "url": "https://localhost:7001/mcp"
    }
  }
}

Notifications

The GraphNotificationService sends notifications via Microsoft Graph:

Notifications are fire-and-forget — failures are logged to Application Insights but do not affect the decision response.

Database Migrations

Migrations apply automatically at startup and are idempotent — safe for Blue/Green or slot deployments. To generate a migration after a model change:

dotnet ef migrations add <MigrationName> `
  --project src/ApprovalWorkflow.Infrastructure `
  --startup-project src/ApprovalWorkflow.McpServer

Security Considerations

• Never commit secrets — use User Secrets locally and Key Vault in production
• The /mcp endpoint requires a valid Entra ID bearer token at all times
• CORS is restricted to known Copilot origins only
• Azure SQL has public network access disabled in the Bicep template — use Private Endpoint or App Service VNet Integration for production workloads
• Key Vault soft delete is enabled with 90-day retention to protect against accidental deletion

Contributing

1. Fork the repository and create a feature branch: git checkout -b feature/your-feature
2. Follow the existing namespace and layering conventions (Core → Infrastructure → McpServer)
3. All new MCP tools must include [Description] attributes — these are surfaced directly to Copilot as tool documentation
4. Test locally against the .vscode/mcp.json configuration before raising a PR
5. Open a pull request against main with a clear description of the change and any configuration impacts

License

This project is licensed under the MIT License. See LICENSE for details.