MCP Server Demo

A demonstration Model Context Protocol (MCP) server built with FastMCP. It exposes a small set of tools, resources, and prompts over the streamable-http transport and secures every request with Microsoft Entra ID (OAuth 2.0).

The server is designed to run both locally (developer machine) and in Azure (App Service / Container Apps), and it can call downstream Azure services such as Azure Data Explorer (Kusto) as the calling user using the On-Behalf-Of (OBO) flow backed by a federated managed identity.

---

What this project does

At a high level, the server lets an MCP client (e.g. VS Code + GitHub Copilot in agent mode) discover and invoke server-side capabilities after the user signs in with their Microsoft Entra account:

• Tools — callable functions the model can invoke:
  • get_weather(location) — current weather for a city/place via the public Open-Meteo API.
  • get_ip_address() — the server's public IP via ipify.
  • execute_kql(query, cluster?, database?) — runs a Kusto (KQL) query against Azure Data Explorer and returns JSON. Enforces a 1000-row safety cap and runs the query under the caller's identity when Azure-hosted (OBO).
  • add(a, b) — trivial example tool.
  • long_running_task(task_name, steps) — demonstrates progress reporting via the MCP Context.
• Resource — greeting://{name} returns a personalized greeting (dynamic resource template).
• Prompt — greet_user(name, style) returns a reusable greeting prompt.
• Routes — /mcp (the MCP endpoint) plus a public /readme HTML route and the OAuth discovery endpoint /.well-known/oauth-protected-resource.

---

Architecture

Component layout

main.py                 # Server entry point: builds FastMCP, wires auth, registers tools, serves via uvicorn
client.py               # Demo MCP client (acquires a token with DefaultAzureCredential, calls the server)
auth/
  authCheck.py          # EntraTokenVerifier: validates incoming JWTs (signature, issuer, audience, scope/role)
tools/
  weather.py            # register_weather_tools -> get_weather
  findIP.py             # register_ip_tools -> get_ip_address
  executeKQL.py         # register_kql_tools -> execute_kql (OBO + federated managed identity)
GoogleCalendar.py       # Standalone Google Calendar experiment (not wired into the MCP server)
AUTH.md                 # Deep-dive on the Entra ID OAuth setup and gotchas
pyproject.toml /        # Dependencies (mcp[cli], azure-identity, azure-kusto-data, pyjwt[crypto], starlette, uvicorn, ...)
requirements.txt

Request flow

sequenceDiagram
    actor User
    participant Client as MCP Client (VS Code / client.py)
    participant Entra as Microsoft Entra ID
    participant Server as FastMCP Server (/mcp)
    participant Verifier as EntraTokenVerifier
    participant Kusto as Azure Data Explorer

    Client->>Server: GET /.well-known/oauth-protected-resource
    Server-->>Client: issuer + scopes_supported (api://<app>/mcp.access)
    Client->>Entra: Request token for api://<app>/mcp.access
    Entra->>User: Sign in / consent
    Entra-->>Client: Access token (aud = API, scp = mcp.access)
    Client->>Server: MCP request + Bearer token
    Server->>Verifier: verify_token(token)
    Verifier->>Entra: Fetch JWKS signing keys (cached)
    Verifier-->>Server: AccessToken (valid) or reject (401/403)
    Server->>Kusto: execute_kql via OBO (run as caller, Azure-hosted)
    Kusto-->>Server: Result rows
    Server-->>Client: Tool result

Key design points

• FastMCP + streamable-http. OAuth requires the streamable-http transport (stdio cannot do OAuth). The server is built in main.py and served by uvicorn on 0.0.0.0, reading PORT from the environment (App Service injects it).
• Modular tool registration. Each tool group lives in its own module under tools/ and exposes a register_*_tools(mcp) function, keeping main.py thin and tools independently testable.
• Per-user downstream calls (OBO). tools/executeKQL.py reads the caller's validated token via get_access_token() and, when running in Azure, exchanges it through an OnBehalfOfCredential whose client assertion is a federated managed identity (no secret/cert). Locally it falls back to AzureCliCredential (az login) then interactive browser sign-in.
• Safety guardrails. execute_kql refuses to return result sets larger than MAX_ROWS (1000) and asks the caller to aggregate or filter instead.

---

Authentication (brief)

Authentication is implemented with Microsoft Entra ID using OAuth 2.0 bearer tokens. Full details and troubleshooting live in AUTH.md; the essentials:

1. Server advertises a protected resource. AuthSettings in main.py publishes the issuer (https://login.microsoftonline.com/<tenant>/v2.0) and the fully-qualified required scope api://<api-app-id>/mcp.access. The scope must be fully-qualified — a bare mcp.access is interpreted by Entra as a Microsoft Graph scope and fails with AADSTS65002.

2. Token validation happens in EntraTokenVerifier (auth/authCheck.py) for every request:

   • Verifies the JWT signature against Entra's JWKS keys (PyJWKClient, RS256).
   • Accepts both v1 (sts.windows.net/<tid>/) and v2 (login.microsoftonline.com/<tid>/v2.0) issuers.
   • Accepts both audience forms: api://<guid> and the bare <guid>.
   • Authorizes either a delegated user (mcp.access in the scp claim) or an app-only caller (mcpaccess.app in the roles claim, e.g. a managed identity).
   • Re-adds the fully-qualified scope to the returned AccessToken.scopes so the MCP bearer middleware's required_scopes check passes.

3. Client sign-in options:

   • VS Code native sign-in — VS Code reads the discovery endpoint and acquires a token through its built-in Microsoft auth provider; no token handling code needed.
   • Manual bearer token — az account get-access-token --scope "api://<app>/.default" and paste it into .vscode/mcp.json as an Authorization header.
   • Programmatic — client.py uses DefaultAzureCredential (az login locally, managed identity in Azure).

One-time Entra setup (app registration, Expose an API, and pre-authorizing the VS Code and Azure CLI first-party client IDs) is documented in AUTH.md.

---

Running locally

1. Create a .env file with your Entra values:

   ENTRA_TENANT_ID=<your-tenant-id>
   ENTRA_AUDIENCE=api://<api-app-id>
   ENTRA_CLIENT_ID=<client-app-id>
   # Optional, used by execute_kql:
   KUSTO_CLUSTER=https://<cluster>.kusto.windows.net
   KUSTO_DATABASE=<database>
   # Set when deployed:
   # RESOURCE_SERVER_URL=https://<app>.azurewebsites.net
   

2. Install dependencies and start the server:

   pip install -r requirements.txt
   python main.py
   

   The MCP endpoint is served at http://localhost:8000/mcp.

3. Verify the advertised OAuth metadata:

   curl.exe -s http://localhost:8000/.well-known/oauth-protected-resource
   

4. (Optional) Exercise the server with the demo client:

   az login --tenant <your-tenant-id>
   python client.py
   

---

Notes

• main.py includes verbose print statements that are useful for learning/debugging the auth flow; replace them with structured logging for production use.