nexus-mcp/Identity/copilot-studio-deployment-guide.md

Identity MCP → Copilot Studio Deployment Guide

Overview

This guide walks you through deploying your Identity MCP server to Microsoft Copilot Studio using Option 2: Custom MCP Connector via Power Apps.

Prerequisite: You must have an HTTPS-accessible endpoint for your Identity MCP server. Copilot Studio cannot connect to localhost or STDIO-based servers.

---

Phase 1: Prepare your Identity MCP for HTTP transport

Step 1: Update dependencies (if needed)

Your Identity MCP can now run with streamable HTTP transport. Ensure you have the server extras installed:

cd "MCP Servers/Identity"
uv pip install "mcp[server]>=1.2.0"

Step 2: Configure environment variables

The server now supports two transport modes via environment variables:

For local/VS Code testing (STDIO):

# Default - no env vars needed
export MCP_TRANSPORT=stdio
python identity_mcp_server.py

For Copilot Studio (Streamable HTTP):

export MCP_TRANSPORT=streamable
export MCP_HOST=0.0.0.0          # Bind to all interfaces
export MCP_PORT=8000             # Choose your port
export IDENTITY_BACKEND=ad       # Use Active Directory backend
python identity_mcp_server.py

Step 3: Test streamable transport locally

Before deploying to production, validate the HTTP endpoint works:

# Terminal 1: Start the server
cd "MCP Servers/Identity"
export MCP_TRANSPORT=streamable
export MCP_PORT=8000
export IDENTITY_BACKEND=memory  # Safe mode for testing
python identity_mcp_server.py

# Terminal 2: Test the endpoint
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"test-1"}'

Expected response: JSON with available tools (get_user, search_users_by_name, etc.)

---

Phase 2: Deploy to production hosting

Hosting options

Your Identity MCP must be accessible via HTTPS from Power Platform cloud services. Common options:

1. Azure App Service (recommended for Microsoft ecosystem)
2. Azure Container Instances with HTTPS ingress
3. On-premises IIS with reverse proxy + public HTTPS endpoint
4. VM with nginx/caddy reverse proxy + Let's Encrypt cert

Security requirements

✅ HTTPS only — Power Platform will not connect to HTTP
✅ Valid SSL certificate — self-signed certs will fail
✅ Firewall rules — allow inbound HTTPS from Power Platform IP ranges
✅ Authentication — configure API key or OAuth (see Phase 3)

Example: Azure App Service deployment

# Install Azure CLI if not already installed
az login

# Create resource group
az group create --name rg-identity-mcp --location eastus

# Create App Service plan (Linux)
az appservice plan create \
  --name plan-identity-mcp \
  --resource-group rg-identity-mcp \
  --sku B1 \
  --is-linux

# Create web app with Python runtime
az webapp create \
  --name identity-mcp-wheels \
  --resource-group rg-identity-mcp \
  --plan plan-identity-mcp \
  --runtime "PYTHON:3.11"

# Configure environment variables
az webapp config appsettings set \
  --name identity-mcp-wheels \
  --resource-group rg-identity-mcp \
  --settings \
    MCP_TRANSPORT=streamable \
    MCP_HOST=0.0.0.0 \
    MCP_PORT=8000 \
    IDENTITY_BACKEND=ad \
    AD_USERNAME="svc-identity-mcp@wheelsinc.com" \
    AD_PASSWORD="<secure-password-from-key-vault>"

# Deploy code (from repo root)
cd "MCP Servers/Identity"
zip -r deploy.zip .
az webapp deploy \
  --name identity-mcp-wheels \
  --resource-group rg-identity-mcp \
  --src-path deploy.zip \
  --type zip

# Verify deployment
curl https://identity-mcp-wheels.azurewebsites.net/mcp

Your production URL: https://identity-mcp-wheels.azurewebsites.net

---

Phase 3: Configure authentication (recommended)

Option A: API Key (simplest for Phase 1)

1. Generate a strong API key:

# Generate a secure random key (save this!)
openssl rand -hex 32
# Example output: a1b2c3d4e5f6...

2. Configure your MCP server to validate API keys:

Add to your server code (before tool definitions):

import os
from fastapi import HTTPException, Security
from fastapi.security import APIKeyHeader

API_KEY = os.getenv("MCP_API_KEY")
api_key_header = APIKeyHeader(name="X-API-Key", auto_error=True)

async def verify_api_key(key: str = Security(api_key_header)):
    if key != API_KEY:
        raise HTTPException(status_code=401, detail="Invalid API key")
    return key

3. Store API key in your hosting environment:

# Azure App Service
az webapp config appsettings set \
  --name identity-mcp-wheels \
  --resource-group rg-identity-mcp \
  --settings MCP_API_KEY="<your-generated-key>"

Option B: OAuth 2.0 (for Phase 3+ with user delegation)

OAuth configuration is outlined in the OpenAPI file. Defer to Phase 3 when write operations are enabled.

---

Phase 4: Import OpenAPI schema to Power Apps

Step 1: Customize the OpenAPI file

Edit identity-mcp-openapi.yaml:

1. Update host: Replace your-identity-mcp-host.yourdomain.com with your actual production URL:

   host: identity-mcp-wheels.azurewebsites.net
   

2. Configure authentication: Uncomment the security method you chose (API key is already configured).

3. Save the file.

Step 2: Create custom connector in Power Apps

1. Go to your Copilot Studio agent

2. Navigate to Tools page

3. Click Add a tool

4. Select New tool

5. Select Custom connector

   ➜ You're redirected to Power Apps

6. In Power Apps:

   • Click New custom connector
   • Select Import OpenAPI file
   • Upload identity-mcp-openapi.yaml
   • Click Continue

Step 3: Configure connector security

On the Security tab:

If using API Key:

• Authentication type: API Key
• Parameter label: API Key
• Parameter name: X-API-Key
• Parameter location: Header

If using OAuth 2.0:

• Follow the OAuth configuration from the Microsoft Learn doc (linked in References)

Click Create connector when done.

Step 4: Test the connector

1. On the Test tab, click New connection
2. Enter your API key (if using API key auth)
3. Click Create connection
4. In the Operations section, select InvokeIdentityMCP
5. Paste a test MCP request payload:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": "test-1"
}

6. Click Test operation
7. Expected result: 200 OK with list of available tools

---

Phase 5: Add connector to Copilot Studio agent

1. Return to Copilot Studio (close Power Apps tab)
2. On the Add tool dialog:
   • Select your newly created Identity MCP connector
   • Click Create a new connection (or use existing)
3. Authenticate if prompted
4. Click Add to agent

---

Phase 6: Validate end-to-end

Test in agent chat

1. Open your agent's Test chat panel

2. Ask a question that should trigger Identity MCP tools:

   Example prompts:

   • "Get user details for jsmith"
   • "Who are the members of the VPN-Users group?"
   • "Find users who haven't logged in for 90 days"

3. Check tool invocation:

   • Open the trace/tool panel (if available)
   • Confirm the Identity MCP tool was invoked
   • Validate the response matches expected data

Troubleshooting validation

Issue	Check
Tool not invoked	Improve connector description and operation summary so orchestrator understands when to call it
401 Unauthorized	Verify API key matches in both server config and connector connection
500 Server error	Check server logs for backend failures (AD connectivity, permissions)
Tool returns empty results	Test the same query via manual PowerShell to isolate MCP vs AD issue

---

Security & governance checklist

Before enabling for production use:

• HTTPS with valid certificate confirmed
• API key (or OAuth) authentication enabled and tested
• Service account permissions validated (Read Directory Data only for Phase 1)
• Audit logging verified (tool name, params, timestamp, result)
• Connector restricted to authorized agents only
• Rate limiting configured (if available in hosting environment)
• Connection timeout tested under load
• Disaster recovery plan documented (connector re-import procedure)

---

Maintenance procedures

Update connector after schema changes

If you modify tool definitions or add new tools:

1. Update identity-mcp-openapi.yaml with new endpoint details
2. In Power Apps, navigate to Custom connectors
3. Select Identity MCP connector
4. Click Update from OpenAPI file
5. Upload the updated YAML
6. Click Update connector
7. Test updated operations on the Test tab
8. Return to Copilot Studio and verify new tools are available

Monitor API usage

Check connector call metrics regularly:

1. Power Apps → Custom connectors → Identity MCP
2. View Analytics tab for:
   • Call volume
   • Error rates
   • Latency trends

---

References

• Microsoft Learn: Add existing MCP server to agent
• Microsoft Learn: Custom connectors in Power Apps
• Model Context Protocol Specification
• Internal: identity-mcp-install-guide.md (Phase 0-4 governance procedures)

---

Revision history

Version	Date	Author	Changes
1.0	2026-03-11	N. Castaldi	Initial deployment guide for Option 2 (Custom Connector) path