Contoso Insurance API + MCP Server

A demo insurance policy servicing and claims API built with FastAPI and FastMCP. The same business logic is exposed two ways:

• REST API at /api/... with Swagger UI at /docs

• MCP server (Streamable HTTP) at /mcp, ready to plug into a Microsoft Foundry voice agent as an MCP tool

• Public "Talk to Sam" page at /, where anyone can talk to that voice agent, avatar included, from the browser

Every response includes a short summary written to be spoken aloud, which keeps realtime voice agents (e.g. gpt-realtime) fast and natural.

Browser (/) ── mic over WebSocket ──▶ /voice/ws relay (managed identity, call limits)
   ▲                                          │
   └── avatar video + voice over WebRTC ──── Foundry voice agent (gpt-realtime, HD voice, avatar)
                                              │  MCP over HTTPS (/mcp, x-api-key)
                                              ▼
                              Azure Container Apps: FastAPI + FastMCP
                                              │
                                InsuranceService ──▶ in-memory seed data (swap for Cosmos DB / SQL)

The relay, MCP server and REST API are one container app; Application Insights traces all three.

MCP tools

Related MCP server: hawksoft-mcp

REST endpoints

Run locally

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
pytest -q
uvicorn app.main:app --reload

• Swagger: http://localhost:8000/docs

• MCP endpoint: http://localhost:8000/mcp

Test the MCP server with the MCP Inspector:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://localhost:8000/mcp

Optional: export API_KEY=some-long-random-value to require an x-api-key header on /api and /mcp.

Or with Docker:

docker build -t insurance-mcp-api .
docker run -p 8000:8000 -e API_KEY=change-me insurance-mcp-api

Deploy to Azure Container Apps

Prerequisites: Azure Developer CLI (azd) and an Azure subscription. No local Docker needed — azd builds the image remotely in Azure Container Registry.

azd auth login
azd env new insurance-mcp            # any environment name
azd env set MCP_API_KEY "$(openssl rand -hex 24)"
# Windows PowerShell: azd env set MCP_API_KEY ([guid]::NewGuid().ToString("N") + [guid]::NewGuid().ToString("N"))
azd up                               # pick subscription + region
azd env get-value MCP_ENDPOINT       # e.g. https://ca-insurance-xxxx.<region>.azurecontainerapps.io/mcp

Telemetry goes to the Application Insights resource appi-<token> (azd env get-value APPLICATIONINSIGHTS_NAME). Requests and dependencies are collected automatically, and each MCP tool call appears as an mcp.tool <name> span, marked failed when the tool returns an error. Locally, telemetry is off unless APPLICATIONINSIGHTS_CONNECTION_STRING is set.

Public voice demo page

The app's home page (/) is a public "Talk to Sam" page: visitors talk to your Foundry voice agent, with its avatar, straight from the browser. The browser streams microphone audio to /voice/ws, and the app relays it to the Foundry voice agent's realtime endpoint using its managed identity, so no Azure key or token ever reaches the visitor. The relay only forwards audio, interruptions and the avatar handshake; visitors can't change the agent's instructions or tools.

It needs a Foundry voice agent (kind: voice), the kind with a voice, avatar and greeting configured in Foundry. The relay connects to that agent's realtime route, /api/projects/<project>/agents/<agent>/endpoint/protocols/voice. Point it at your agent, then run azd up again:

azd env set FOUNDRY_RESOURCE_NAME  <foundry-resource>     # e.g. arul1
azd env set FOUNDRY_RESOURCE_GROUP <its-resource-group>   # e.g. rg_aml
azd env set FOUNDRY_PROJECT_NAME   <project>              # e.g. proj-default
azd env set VOICE_AGENT_NAME       <agent-name>
azd up
azd env get-value VOICE_DEMO_URL

This grants the app's identity Foundry User (formerly Azure AI User) and Cognitive Services User on the Foundry resource, so the account running azd up needs permission to assign roles there (Owner or User Access Administrator).

Because the page is public, every call is capped. Defaults, overridable as container app env vars:

The voice, avatar, greeting and instructions all come from the agent's configuration in Foundry; change them there. If the avatar can't connect (for example on a network that blocks WebRTC), the call continues with voice only.

After code changes, azd deploy updates just the app, which is faster than azd up.

Troubleshooting. The page logs every non-audio event from the agent to the browser console as [voice] <event type> <json>, and the relay records errors and empty responses in Application Insights.

• Sam greets you but never hears you: turn off Echo cancellation in the agent's Advanced settings (see docs/foundry-agent-instructions.md). The relay also asks the service to switch it to a server reference for each call, and the page sends the two-channel audio that mode expects if the setting stays on.

• Every response is empty (0 tokens): the agent isn't a voice agent, or the relay is pointed at the wrong project or agent name.

Continuous deployment from GitHub

azd pipeline config                  # sets up OIDC + repo variables for .github/workflows/azure-dev.yml
gh secret set MCP_API_KEY --body "$(azd env get-value MCP_API_KEY)"

Every push to main then runs tests (ci.yml) and redeploys (azure-dev.yml).

Connect it to the Foundry agent

1. In Microsoft Foundry, open the agent → Tools → Add a MCP tool (custom / remote MCP server).

2. Name: contoso-insurance; Remote MCP server endpoint: the MCP_ENDPOINT value from above.

3. Authentication: key-based, header name x-api-key, value = your MCP_API_KEY.

4. Approval: set to never require approval for the demo, so the voice conversation isn't interrupted.

5. Paste the instructions and greeting from docs/foundry-agent-instructions.md, apply the settings listed there, then Save and try it in the voice playground using the demo callers.

Project layout

app/
  main.py          FastAPI app, mounts MCP at /mcp, API-key middleware
  mcp_server.py    FastMCP tool definitions
  api.py           REST routes
  services.py      Business logic (shared by REST + MCP)
  repository.py    In-memory store loaded from data/seed.json
  security.py      Optional x-api-key check (pure ASGI, streaming-safe)
  telemetry.py     Application Insights setup and per-tool MCP spans
  voice.py         Public voice demo: relay to the Foundry voice agent, with call limits
  static/          "Talk to Sam" page (HTML, CSS, mic capture, WebRTC avatar)
  data/seed.json   Fictional customers, policies, billing, claims
infra/             Bicep for Container Apps, ACR, Log Analytics, Application Insights, managed identity
docs/              Foundry agent instructions and demo script
tests/             pytest: service, REST, MCP, telemetry and voice relay tests

Notes

• All data is fictional. Claims and callbacks you create are stored in memory and reset on restart; the app runs as at most one replica for that reason. It scales to zero when idle, so the first visitor (or the agent's first tool call) after a quiet spell waits a few seconds for it to start, and in-memory data and call counts reset then. Replace InMemoryRepository with a Cosmos DB or SQL implementation for anything beyond a demo.

• Identity verification is a demo pattern (DOB + ZIP), not production-grade authentication.

• The voice page is public and every call costs money (realtime model, neural voice and avatar minutes). Keep the call limits in place, and tighten VOICE_DAILY_SESSION_LIMIT if you share the link widely.

License

MIT