Mock MCP Server

A mock MCP (Model Context Protocol) proxy server with two-part authentication, SSE notifications, and CIMD-based client identity. Built as a .NET 8 ASP.NET Core app. Models a real-world architecture where an MCP proxy authenticates clients via CIMD (AAD App #1) and internally authenticates to a backend MCP server via a separate AAD app (App #2).

Two-Part Authentication Flow

VS Code (MCP Client)
  │
  ├─ CIMD OAuth ──→ AAD App #1 ──→ proxy token
  │
  ├─ tools/list ──→ [discover_tools only]
  │
  ├─ tools/call discover_tools ──→ elicitation URL
  │       │
  │       └─ User opens browser → /backend-auth/login
  │             → Entra login (AAD App #2)
  │             → Backend tokens stored server-side
  │             → "Success, close window"
  │
  ├─ tools/list ──→ [full tools list]
  │
  └─ tools/call echo ──→ proxy uses stored backend token internally

Part 1: Proxy Auth (CIMD + AAD App #1)

1. Client discovers PRM at /.well-known/oauth-protected-resource
2. Client authenticates via CIMD OAuth flow (/oauth/authorize → /oauth/token)
3. Client receives a proxy token — this is the only token the client ever sees
4. With proxy token, tools/list returns only discover_tools

Part 2: Backend Auth (AAD App #2, server-side)

5. Client calls discover_tools → receives elicitation URL
6. User opens URL in browser → authenticates against AAD App #2
7. Backend tokens (access + refresh) stored server-side, keyed by proxy token
8. Now tools/list returns full tools and tools/call works
9. Client continues using the same proxy token — backend tokens are never exposed

Endpoints

| Method | Route | Description | |--------|-------|-------------| | GET | /.well-known/oauth-protected-resource | Protected Resource Metadata (PRM) | | GET | /.well-known/oauth-authorization-server | OAuth Authorization Server Metadata | | GET | /oauth/authorize | OAuth authorization endpoint (CIMD) | | GET | /oauth/callback | Entra ID callback (proxy auth) | | POST | /oauth/token | OAuth token endpoint (proxy auth) | | GET/POST | /mcp | MCP JSON-RPC endpoint | | GET | /backend-auth/login | Start backend auth (AAD App #2) | | GET | /backend-auth/callback | Backend auth callback | | GET | /backend-auth/status | Check backend auth status | | GET | /cimd-policy | Current CIMD policy configuration | | GET/POST | /backend/mcp | Backend MCP server (JSON-RPC + SSE) |

Supported MCP Methods

• initialize - Returns server capabilities
• tools/list - Returns available tools (expands after consent)
• tools/call - Executes a tool call (echo, get_weather, calculate)
• resources/list - Returns available resources (empty)
• prompts/list - Returns available prompts (empty)

Streaming Proxy Architecture (SSE Sidecar)

After backend auth completes, the proxy needs to receive server-initiated notifications from the backend MCP server. The BackendSseManager acts as an in-process SSE sidecar:

1. Client ↔ Proxy: SSE established at initialize (proxy token)
2. After backend auth: sidecar opens SSE to GET /backend/mcp (backend token)
3. Backend sends notification → sidecar reads it → relays via McpServer.NotifyClient() → written to client SSE
4. Tool calls are stateless POST forwarding (proxy → backend), no SSE involved

In production, the sidecar would be a separate Azure Container App per environment, keeping backend SSE connections off APIM.

Configuration

Auth Modes

Set MCP_AUTH_MODE in local.settings.json:

| Mode | Description | |------|-------------| | mock (default) | No external calls. Auth codes and tokens generated locally. Good for offline testing. | | entra | Real Azure AD integration. Redirects to Entra ID for user authentication. Requires AAD app registration. |

Auth Strategy

Set MCP_AUTH_STRATEGY in local.settings.json:

| Strategy | Description | |----------|-------------| | cimd (default) | Proxy acts as its own OAuth Authorization S

... View full README on GitHub