Outlook MCP Server

This server uses Microsoft Entra's OAuth 2.0 On-Behalf-Of flow. The client application sends an access token issued for this MCP API; the server validates that token and exchanges it for a delegated Microsoft Graph access token.

Entra application contract

• Client application ID: 9b544eca-bd87-4849-b7fb-e96c944cdca8
• MCP/API application ID: a7e86069-52f5-46b7-9a06-41d411c47410
• Tenant ID: 46c98d88-e344-4ed4-8496-4ed7712e255d
• MCP delegated scope: api://a7e86069-52f5-46b7-9a06-41d411c47410/access_as_user
• OBO Graph scope: https://graph.microsoft.com/.default

The bearer token sent to /mcp must be an access token for the MCP API, not an ID token or a Graph access token. It must contain access_as_user in scp and identify the client application in azp (v2 token) or appid (v1 token).

The MCP application registration must have delegated Microsoft Graph permissions with admin consent and a confidential-client credential. In Kubernetes, create the credential separately; never add its value to this repository:

kubectl create secret generic outlook-mcp-entra `
  --namespace catalyst-prod `
  --from-literal=client-secret='<secret-value>'

For local development, copy .env.example to .env, provide ENTRA_CLIENT_SECRET, and export/load those variables before starting the server. The production manifest reads the secret from outlook-mcp-entra.

A production-ready, forkable template for building MCP (Model Context Protocol) servers that deploy to the Catalyst Kubernetes platform.

This template uses the same proven SDK patterns running in production today (math-mcp-server, hsdes-mcp-server). Copy this folder, fill in your tools, and deploy in under 30 minutes.

Generated servers conform to the Intel IT MCP engineering standard (IT-MCP-STD-001): standardized naming, MCP-native tools tagged with annotations + governance _meta, risk tiers (R0-R3) with runtime enforcement of R2/R3 writes, data-freshness tags, and server-side telemetry (structured JSON logs with a correlation id and gateway-validated caller). A registry.yaml manifest records the server for the registry. (The deployed reference servers math-mcp-server and hsdes-mcp-server predate this convention.)

Prerequisites

Before using this template, make sure you have:

• Python 3.12+ installed locally
• Podman (for container builds) — setup guide
• kubectl configured with a Catalyst cluster kubeconfig
• Harbor access to push images to amr-registry.caas.intel.com/catalyst/

See the full deployment guide for detailed prerequisites and access setup.

Quick Start

1. Copy the template

cp -r templates/mcp-server-template my-new-server
cd my-new-server

2. Find and replace all customization points

Search for >>> CUSTOMIZE across all files and replace the placeholders:

# See all customization points
grep -rn "CUSTOMIZE" .

At minimum, replace:

• your-server-name → your actual server name (e.g., jira-mcp-server)
• API_BASE_URL → the upstream REST API you're wrapping
• Tool definitions in server.py → your actual tools

3. Define your tools

Edit server.py and replace the example tools (core.greeting.get, core.item.get, core.item.update) with your own. Tools are meaningful actions, not a 1:1 mirror of API endpoints — apply the test "would a user describe this action in natural language?".

1. Add a types.Tool(...) entry to the TOOLS list with:
   • name as <domain>.<capability>.<verb_object> (the backing system never appears in a tool name)
   • description + JSON Schema inputSchema
   • annotations=types.ToolAnnotations(...) — map side_effects to hints: none/read => readOnlyHint=True, write_irreversible => destructiveHint=True, idempotentHint from intel.it/idempotent
   • _meta={...} Intel governance tags: risk_tier (R0-R3), side_effects, idempotent, data_classification, plus (for data tools) latency_class / answer_type / source_system
2. Add a matching case "<domain>.<capability>.<verb_object>": block in call_tool()
3. Use _api_request() for upstream API calls, _ok() / _err() for responses
4. For R2 (reversible write) tools, require reason, target_identifiers, idempotency_key; for R3 (irreversible) require reason, target_identifiers, approval_id. The dispatcher enforces these before any upstream call and emits an AUDIT log
5. Update registry.yaml so the registry record matches the server's tools

4. Test locally

python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux/macOS
pip install -r requirements.txt
python server.py

Verify the server is running:

# Health check
curl http://localhost:8000/health

# List tools (MCP JSON-RPC)
curl -X POST http://localhost:8000/mcp/ ^
  -H "Content-Type: application/json" ^
  -H "Accept: application/json, text/event-stream" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}"

# Call the greeting tool
curl -X POST http://localhost:8000/mcp/ ^
  -H "Content-Type: application/json" ^
  -H "Accept: application/json, text/event-stream" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"core.greeting.get\",\"arguments\":{\"name\":\"World\"}}}"

5. Build the container

podman build -t your-server-name:1.0.0 .

6. Push to Harbor registry

podman tag your-server-name:1.0.0 amr-registry.caas.intel.com/catalyst/your-server-name:1.0.0
podman push --tls-verify=false amr-registry.caas.intel.com/catalyst/your-server-name:1.0.0

7. Deploy to Kubernetes

# Set kubeconfig for your cluster
$env:KUBECONFIG = "path/to/kube-configs/amr-its-compute-cluster.yaml"

kubectl apply -f k8s-deploy.yaml
kubectl apply -f ingress.yaml

# Watch pod status
kubectl get pods -n catalyst -l app=your-server-name -w

8. Verify the deployment

curl https://api-suite-dev.catalyst.intel.com/your-server-name/health

Auth Patterns

No Auth (Default)

The template ships with no authentication — any client with network access can call your tools. This is appropriate for internal demo servers and tools that don't access sensitive APIs.

Bearer Token Passthrough

If your upstream API requires a user-provided Bearer token (e.g., Intel SSO id_token for HSDES, ServiceNow, etc.), enable the auth middleware:

1. In server.py: Uncomment the TokenExtractorASGI class, the ContextVar, and the get_bearer_token() helper function (clearly marked in the file)
2. In the ASGI wiring section: Swap the Mount line to use TokenExtractorASGI:

   # Comment out this line:
   # Mount("/mcp", app=session_manager.handle_request),
   # Uncomment this line:
   Mount("/mcp", app=TokenExtractorASGI(session_manager.handle_request)),
   

3. In _api_request(): Uncomment the token forwarding lines to attach the Bearer token to upstream requests

See servers/hsdes-mcp-server/ for a complete working example of this pattern.

VS Code MCP Client Configuration

No-auth server

Add to your .vscode/mcp.json or VS Code settings:

{
  "servers": {
    "your-server-name": {
      "type": "http",
      "url": "https://api-suite-dev.catalyst.intel.com/your-server-name/mcp/"
    }
  }
}

Auth server (Bearer token)

{
  "servers": {
    "your-server-name": {
      "type": "http",
      "url": "https://api-suite-dev.catalyst.intel.com/your-server-name/mcp/",
      "headers": {
        "Authorization": "Bearer ${input:your_server_token}"
      }
    }
  },
  "inputs": [
    {
      "id": "your_server_token",
      "type": "promptString",
      "description": "Bearer token (Intel SSO id_token) for your-server-name",
      "password": true
    }
  ]
}

File Overview

File	Purpose
server.py	MCP server with tool definitions and ASGI wiring
requirements.txt	Python dependencies (pinned to tested versions)
Dockerfile	Multi-stage container build with non-root user
k8s-deploy.yaml	Kubernetes Deployment + Service
ingress.yaml	Traefik Ingress + Middleware for external HTTPS access
registry.yaml	IT-MCP-STD-001 registry manifest (server + tool metadata)
.env.example	Environment variable reference (copy to .env)
.vscode/mcp.json	VS Code MCP client configuration

Full Documentation

For the complete deployment pipeline including Podman VM proxy setup, Harbor authentication, kubeconfig management, and troubleshooting:

docs/CATALYST-MCP-DEPLOYMENT-GUIDE.md