MedRecPro Drug Label Server

MedRecPro MCP Server

MCP (Model Context Protocol) server for the MedRecPro application. Acts as an OAuth 2.1 gateway between MCP clients (Claude, etc.) and the MedRecPro Web API.

Version: 1.0.0 Runtime: ASP.NET Core 8.0 Production URL: https://www.medrecpro.com/mcp

Architecture

                             Azure App Service: "MedRecPro" (Windows, IIS)

+--------------------------------------------------+ | | +------------------+ | / site\wwwroot MedRecProStatic | | Claude / MCP | HTTPS | /api site\wwwroot\api MedRecPro API | | Client |------->| /mcp site\wwwroot\mcp MedRecProMCP | +------------------+ | | | +--------------------------------------------------+ v | +------------------+ v | Cloudflare | +------------------+ | (CDN/WAF/DNS) | | Azure Key Vault | +------------------+ | (medrecprovault)| +------------------+

The MCP server runs as an IIS virtual application at /mcp on the same Azure App Service as the main MedRecPro UI and API. IIS handles path-based routing to three separate ASP.NET Core processes:

Endpoints

All endpoints are externally prefixed with /mcp by the IIS virtual application.

Note: GET /mcp returns HTTP 405 (Method Not Allowed). This is correct behavior. The MCP transport only accepts POST requests. For browser-accessible pages, use /mcp/docs (technical documentation) or /mcp/getting-started (user-facing guide).

Authentication Flow

1. Claude sends POST to /mcp (unauthenticated)

1. Server returns 401 with WWW-Authenticate header pointing to PRM
2. Claude fetches /mcp/.well-known/oauth-protected-resource
3. Claude fetches /mcp/.well-known/oauth-authorization-server
4. Claude registers via /mcp/oauth/register (Dynamic Client Registration)
5. Claude redirects user to /mcp/oauth/authorize?provider=google
6. User authenticates with Google/Microsoft
7. Provider redirects to /mcp/oauth/callback/{provider}
8. MCP server resolves upstream IdP email to numeric DB user ID via POST /api/users/resolve-mcp (auto-provisions user if they don't exist in the database)
9. MCP server issues authorization code with numeric sub claim (standard JWT name), redirects to Claude
10. Claude exchanges code for tokens via /mcp/oauth/token
11. Claude sends authenticated POST to /mcp with Bearer MCP JWT
12. MCP server forwards MCP JWT to MedRecPro API for each tool call (McpBearer auth scheme)

User Resolution and Auto-Provisioning

During the OAuth callback (step 9), the MCP server must map the upstream identity provider's identifier (Google sub / Microsoft GUID) to a numeric MedRecPro database user ID. The API's getEncryptedIdFromClaim() method expects a numeric NameIdentifier claim — without this resolution, all API calls would fail with 401.

How it works:

1. OAuthEndpoints.cs extracts email, display name, and provider from upstream IdP claims
2. UserResolutionService generates a temporary MCP JWT and calls POST /api/users/resolve-mcp
3. The API's UsersController.ResolveMcpUser() looks up the user by email:

• User exists: Returns their encrypted database user ID
• User doesn't exist: Auto-provisions a new user record (matching AuthController.createUserForExternalLogin() defaults: EmailConfirmed=true, Timezone="UTC", Locale="en-US", no password), then returns the encrypted ID

1. UserResolutionService decrypts the encrypted ID using the shared Security:DB:PKSecret via StringCipher
2. OAuthEndpoints.cs replaces the upstream NameIdentifier claim with the numeric database user ID
3. McpTokenService.normalizeClaimType() converts ClaimTypes.NameIdentifier to the standard JWT sub claim during token creation, and OutboundClaimTypeMap is cleared to prevent double-mapping
4. The MCP JWT is issued with the numeric user ID as the sub claim, enabling all API calls to succeed

Key architecture:

• TokenForwardingHandler forwards the MCP JWT directly to the API (not the upstream Google/Microsoft token). The API's McpBearer authentication scheme validates these MCP-signed JWTs.
• Both the MCP server and API share Security:DB:PKSecret from Azure Key Vault for StringCipher encryption/decryption of user IDs.
• UserResolutionService uses a dedicated "MedRecProApiDirect" named HttpClient (without TokenForwardingHandler) to avoid circular token forwarding during resolution.
• Claim normalization: McpTokenService normalizes .NET ClaimTypes URIs to standard JWT short names (sub, name, email, given_name, family_name) before token creation. Both JWT handlers set MapInboundClaims = false so claims retain their short names when read back. The API's ClaimHelper resolves user IDs from both ClaimTypes.NameIdentifier (cookie auth) and "sub" (MCP JWT auth).

Compiler Directives (#if DEBUG)

Route paths use compiler directives to handle IIS virtual application path stripping. This follows the same pattern as ApiControllerBase in the MedRecPro API project.

Problem: IIS strips the /mcp prefix from requests before forwarding to the app. A request to www.medrecpro.com/mcp/oauth/authorize arrives at Kestrel as /oauth/authorize. Routes must account for this.

Files with compiler directives:

• Program.cs - MCP transport, health check, docs, getting-started, image serving, PRM redirect
• Endpoints/OAuthEndpoints.cs - OAuth route group prefix
• Endpoints/OAuthMetadataEndpoints.cs - Well-known metadata paths

Config-driven (no directives needed):

• OAuth callback URLs - Built from McpServer:ServerUrl at runtime
• OAuth metadata document contents - Built from McpServer:ServerUrl at runtime
• Protected Resource Metadata - Built from McpServer:ServerUrl at runtime

---

Setup Guide

Prerequisites

• .NET 8.0 SDK
• Azure subscription with:
• App Service (Windows, IIS) - shared with MedRecPro
• Key Vault (medrecprovault)
• Application Insights (optional)
• Cloudflare account with medrecpro.com domain
• Google Cloud Console project with OAuth 2.0 credentials
• Microsoft Entra ID app registration

1. Local Development Setup

Clone and restore

git clone <repo-url>

cd MedRecProMCP dotnet restore

Configure user secrets

dotnet user-secrets init

dotnet user-secrets set "McpServer:JwtSigningKey" " " dotnet user-secrets set "Jwt:Key" " " dotnet user-secrets set "Jwt:Issuer" "http://localhost:5233/mcp" dotnet user-secrets set "Jwt:Audience" "http://localhost:5233/mcp" dotnet user-secrets set "Jwt:ExpirationMinutes" "60" dotnet user-secrets set "Jwt:UpstreamTokenEncryptionKey" "<32-char-aes-key>" dotnet user-secrets set "Authentication:Google:ClientId" " " dotnet user-secrets set "Authentication:Google:ClientSecret" " " dotnet user-secrets set "Authentication:Microsoft:ClientId" " " dotnet user-secrets set "Authentication:Microsoft:ClientSecret:Dev" " " dotnet user-secrets set "Authentication:Microsoft:TenantId" " " dotnet user-secrets set "Security:DB:PKSecret" " "

Run locally

dotnet run

The server runs at http://localhost:5233. In DEBUG mode, endpoints include the /mcp prefix:

• Health check: http://localhost:5233/
• MCP transport: http://localhost:5233/mcp (POST only)
• Documentation: http://localhost:5233/mcp/docs
• Getting started: http://localhost:5233/mcp/getting-started
• Screenshot images: http://localhost:5233/mcp/docs/images/{filename}
• OAuth metadata: http://localhost:5233/mcp/.well-known/oauth-authorization-server

2. Azure App Service Setup

Add virtual application

In Azure Portal:

1. Navigate to App Service "MedRecPro" > Configuration > Path mappings
2. Click "+ Add virtual application or directory"
3. Configure:

• Virtual path: /mcp
• Physical path: site\wwwroot\mcp
• Type: Check Application

1. Click Save

Key Vault secrets

Ensure the following secrets exist in Azure Key Vault (medrecprovault). These are shared with the MedRecPro API since both apps use the same Key Vault:

Note: Key Vault uses -- as separator. ASP.NET Core maps these to : in configuration (e.g., Jwt--Key becomes Jwt:Key).

Managed identity

The App Service must have a system-assigned managed identity with Get and List permissions on Key Vault secrets. Since the MCP virtual application shares the same App Service as the API, the existing managed identity should already have access.

3. OAuth Provider Configuration

Google Cloud Console

1. Go to Google Cloud Console > APIs & Services > Credentials
2. Edit your OAuth 2.0 Client ID
3. Add authorized redirect URIs:

• https://www.medrecpro.com/mcp/oauth/callback/google (production)
• http://localhost:5233/mcp/oauth/callback/google