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.

Related MCP server: Railway MCP Server

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.