MCP Remote Server + OAuth: Enterprise Agent Integration

{
  "resource": "https://mcp.yourcompany.com",
  "authorization_servers": ["https://login.microsoftonline.com/{tenant}/v2.0"],
  "scopes_supported": ["mcp:tools", "mcp:resources", "mcp:prompts"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://docs.yourcompany.com/mcp-api"
}

import crypto from 'crypto';
import { URL, URLSearchParams } from 'url';

interface OAuthConfig {
  clientId: string;
  redirectUri: string;
  issuer: string;
  scopes: string[];
}

interface TokenResponse {
  access_token: string;
  token_type: string;
  expires_in: number;
  refresh_token?: string;
  scope: string;
}

interface OIDCDiscovery {
  authorization_endpoint: string;
  token_endpoint: string;
  jwks_uri: string;
  registration_endpoint?: string;
  scopes_supported: string[];
}

class MCPOAuthClient {
  private config: OAuthConfig;
  private discovery: OIDCDiscovery | null = null;
  private codeVerifier: string = '';

  constructor(config: OAuthConfig) {
    this.config = config;
  }

  async initialize(): Promise<void> {
    const discoveryUrl = `${this.config.issuer}/.well-known/openid-configuration`;
    const response = await fetch(discoveryUrl);
    if (!response.ok) {
      throw new Error(`Discovery failed: ${response.status}`);
    }
    this.discovery = await response.json();
  }

  generatePKCE(): { verifier: string; challenge: string } {
    // Generate 43-128 character random verifier (RFC 7636)
    this.codeVerifier = crypto.randomBytes(32)
      .toString('base64url')
      .slice(0, 64);

    // S256 challenge: BASE64URL(SHA256(verifier))
    const challenge = crypto
      .createHash('sha256')
      .update(this.codeVerifier)
      .digest('base64url');

    return { verifier: this.codeVerifier, challenge };
  }

  buildAuthorizationUrl(): string {
    if (!this.discovery) throw new Error('Call initialize() first');

    const { challenge } = this.generatePKCE();

    const params = new URLSearchParams({
      response_type: 'code',
      client_id: this.config.clientId,
      redirect_uri: this.config.redirectUri,
      scope: this.config.scopes.join(' '),
      code_challenge: challenge,
      code_challenge_method: 'S256',
      state: crypto.randomBytes(16).toString('hex'),
    });

    return `${this.discovery.authorization_endpoint}?${params.toString()}`;
  }

  async exchangeCode(authorizationCode: string): Promise<TokenResponse> {
    if (!this.discovery) throw new Error('Call initialize() first');

    const body = new URLSearchParams({
      grant_type: 'authorization_code',
      code: authorizationCode,
      redirect_uri: this.config.redirectUri,
      client_id: this.config.clientId,
      code_verifier: this.codeVerifier,
    });

    const response = await fetch(this.discovery.token_endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: body.toString(),
    });

    if (!response.ok) {
      const error = await response.text();
      throw new Error(`Token exchange failed: ${error}`);
    }

    return response.json();
  }

  async refreshToken(refreshToken: string): Promise<TokenResponse> {
    if (!this.discovery) throw new Error('Call initialize() first');

    const body = new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: this.config.clientId,
      scope: this.config.scopes.join(' '),
    });

    const response = await fetch(this.discovery.token_endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: body.toString(),
    });

    if (!response.ok) {
      throw new Error(`Token refresh failed: ${response.status}`);
    }

    return response.json();
  }
}

// Usage with MCP scopes
const client = new MCPOAuthClient({
  clientId: 'mcp-agent-client-001',
  redirectUri: 'http://localhost:3000/callback',
  issuer: 'https://login.microsoftonline.com/{tenant}/v2.0',
  scopes: ['openid', 'profile', 'mcp:tools', 'mcp:resources'],
});

async function connectToMCPServer() {
  await client.initialize();
  const authUrl = client.buildAuthorizationUrl();
  console.log(`Authorize at: ${authUrl}`);
  // After redirect callback with ?code=xxx
  // const tokens = await client.exchangeCode(code);
}

import time
import json
import hashlib
from typing import Optional
from dataclasses import dataclass, field
from urllib.request import urlopen

import jwt
from jwt import PyJWKClient, PyJWK
from jwt.exceptions import InvalidTokenError, PyJWKClientError


@dataclass
class JWKSCache:
    """JWKS cache with TTL and forced-refresh support."""
    jwks_uri: str
    cache_ttl: int = 300  # 5 minutes
    _client: Optional[PyJWKClient] = field(default=None, init=False)
    _last_fetch: float = field(default=0, init=False)
    _keys: dict = field(default_factory=dict, init=False)

    def _should_refresh(self) -> bool:
        return time.time() - self._last_fetch > self.cache_ttl

    def _fetch_keys(self, force: bool = False) -> None:
        if not force and not self._should_refresh():
            return
        self._client = PyJWKClient(
            self.jwks_uri,
            cache_keys=True,
            lifespan=self.cache_ttl,
        )
        self._last_fetch = time.time()

    def get_signing_key(self, token: str, force_refresh: bool = False) -> PyJWK:
        self._fetch_keys(force=force_refresh)
        try:
            return self._client.get_signing_key_from_jwt(token)
        except PyJWKClientError:
            if not force_refresh:
                # Key rotation: force refresh and retry once
                return self.get_signing_key(token, force_refresh=True)
            raise


@dataclass
class TokenValidationConfig:
    """Configuration for MCP token validation."""
    issuer: str
    audience: str
    required_scopes: list[str] = field(default_factory=list)
    algorithms: list[str] = field(default_factory=lambda: ["RS256"])
    clock_skew: int = 30  # seconds


class MCPTokenValidator:
    """Production token validator for MCP Server middleware."""

    def __init__(self, config: TokenValidationConfig, jwks_uri: str):
        self.config = config
        self.jwks_cache = JWKSCache(jwks_uri=jwks_uri)

    def validate_token(self, token: str) -> dict:
        """
        Validate an access token and return decoded claims.
        Raises InvalidTokenError on failure.
        """
        # Step 1: Get signing key (with cache + rotation handling)
        signing_key = self.jwks_cache.get_signing_key(token)

        # Step 2: Decode and validate standard claims
        try:
            claims = jwt.decode(
                token,
                signing_key.key,
                algorithms=self.config.algorithms,
                issuer=self.config.issuer,
                audience=self.config.audience,
                options={
                    "verify_exp": True,
                    "verify_iat": True,
                    "verify_nbf": True,
                    "require": ["exp", "iat", "sub", "iss", "aud"],
                },
                leeway=self.config.clock_skew,
            )
        except InvalidTokenError as e:
            raise InvalidTokenError(f"Token validation failed: {e}")

        # Step 3: Validate scopes
        token_scopes = claims.get("scp", "").split() or claims.get("scope", "").split()
        if self.config.required_scopes:
            missing = set(self.config.required_scopes) - set(token_scopes)
            if missing:
                raise InvalidTokenError(
                    f"Insufficient scopes. Missing: {missing}"
                )

        return claims

    def validate_request(self, authorization_header: str) -> dict:
        """Extract and validate Bearer token from Authorization header."""
        if not authorization_header.startswith("Bearer "):
            raise InvalidTokenError("Missing Bearer prefix")

        token = authorization_header[7:]
        return self.validate_token(token)


# Usage in MCP Server middleware
validator = MCPTokenValidator(
    config=TokenValidationConfig(
        issuer="https://login.microsoftonline.com/{tenant}/v2.0",
        audience="api://mcp-server-prod",
        required_scopes=["mcp:tools"],
    ),
    jwks_uri="https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
)

# In your MCP request handler:
# claims = validator.validate_request(request.headers["Authorization"])
# user_id = claims["sub"]
# proceed with tool execution...

interface OBOTokenRequest {
  grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer';
  client_id: string;
  client_secret: string;
  assertion: string; // The user's access token
  scope: string; // Target API scope
  requested_token_use: 'on_behalf_of';
}

class OBOTokenExchanger {
  private tokenEndpoint: string;
  private clientId: string;
  private clientSecret: string;
  private tokenCache: Map<string, { token: string; expiry: number }> = new Map();

  constructor(tokenEndpoint: string, clientId: string, clientSecret: string) {
    this.tokenEndpoint = tokenEndpoint;
    this.clientId = clientId;
    this.clientSecret = clientSecret;
  }

  async exchangeToken(userToken: string, targetScope: string): Promise<string> {
    // Check cache first (keyed by user token hash + scope)
    const cacheKey = this.computeCacheKey(userToken, targetScope);
    const cached = this.tokenCache.get(cacheKey);
    if (cached && cached.expiry > Date.now() + 60000) {
      return cached.token;
    }

    const body = new URLSearchParams({
      grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
      client_id: this.clientId,
      client_secret: this.clientSecret,
      assertion: userToken,
      scope: targetScope,
      requested_token_use: 'on_behalf_of',
    });

    const response = await fetch(this.tokenEndpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: body.toString(),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(
        `OBO exchange failed: ${error.error_description || error.error}`
      );
    }

    const result = await response.json();

    // Cache the exchanged token
    this.tokenCache.set(cacheKey, {
      token: result.access_token,
      expiry: Date.now() + result.expires_in * 1000,
    });

    return result.access_token;
  }

  private computeCacheKey(token: string, scope: string): string {
    const crypto = require('crypto');
    return crypto
      .createHash('sha256')
      .update(`${token}:${scope}`)
      .digest('hex');
  }
}

// Usage in MCP tool handler
const oboExchanger = new OBOTokenExchanger(
  'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token',
  process.env.MCP_CLIENT_ID!,
  process.env.MCP_CLIENT_SECRET!,
);

async function handleDatabaseQuery(userToken: string, query: string) {
  // Exchange user's MCP token for a database API token
  const dbToken = await oboExchanger.exchangeToken(
    userToken,
    'api://database-service/.default'
  );

  // Call downstream database API with delegated identity
  const result = await fetch('https://db-api.internal/query', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${dbToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sql: query }),
  });

  return result.json();
}

enum MCPScope {
  TOOLS = 'mcp:tools',        // Invoke tools
  RESOURCES = 'mcp:resources', // Access resources
  PROMPTS = 'mcp:prompts',    // Use prompt templates
}

// Fine-grained scope extensions (custom)
enum MCPToolScope {
  TOOLS_READ = 'mcp:tools:read',     // List/describe tools only
  TOOLS_EXECUTE = 'mcp:tools:execute', // Actually invoke tools
  TOOLS_ADMIN = 'mcp:tools:admin',    // Manage tool registrations
}

function authorizeToolCall(
  claims: Record<string, unknown>,
  toolName: string
): boolean {
  const scopes = (claims.scp as string || '').split(' ');
  
  // Check base scope
  if (!scopes.includes(MCPScope.TOOLS) && 
      !scopes.includes(MCPToolScope.TOOLS_EXECUTE)) {
    return false;
  }
  
  // Check tool-specific authorization (from custom claims or policy)
  const allowedTools = claims['mcp_allowed_tools'] as string[] || [];
  if (allowedTools.length > 0 && !allowedTools.includes(toolName)) {
    return false;
  }
  
  return true;
}

version: "3.9"

services:
  mcp-server:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
      - MCP_PORT=8080
      - OAUTH_ISSUER=https://login.microsoftonline.com/${TENANT_ID}/v2.0
      - OAUTH_AUDIENCE=api://mcp-server-prod
      - OAUTH_JWKS_URI=https://login.microsoftonline.com/${TENANT_ID}/discovery/v2.0/keys
      - OAUTH_REQUIRED_SCOPES=mcp:tools
      - OBO_CLIENT_ID=${MCP_CLIENT_ID}
      - OBO_CLIENT_SECRET=${MCP_CLIENT_SECRET}
      - RATE_LIMIT_RPM=100
      - LOG_LEVEL=info
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
      restart_policy:
        condition: on-failure
        max_attempts: 3

  nginx:
    image: nginx:1.25-alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - mcp-server

  redis:
    image: redis:7-alpine
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

volumes:
  redis-data:

# nginx.conf (relevant snippet)
server:
  listen: 443 ssl
  server_name: mcp.yourcompany.com
  
  ssl_certificate: /etc/nginx/certs/fullchain.pem
  ssl_certificate_key: /etc/nginx/certs/privkey.pem
  ssl_protocols: TLSv1.3
  ssl_prefer_server_ciphers: "off"
  
  add_header: Strict-Transport-Security "max-age=31536000; includeSubDomains" always
  
  location /:
    proxy_pass: http://mcp-server:8080
    proxy_set_header: Host $host
    proxy_set_header: X-Real-IP $remote_addr
    proxy_set_header: X-Forwarded-For $proxy_add_x_forwarded_for
    proxy_set_header: X-Forwarded-Proto $scheme
    
    # SSE/Streaming support
    proxy_buffering: "off"
    proxy_cache: "off"
    proxy_read_timeout: 86400s