The user wants me to create an HTTPS server that acts as an MCP (Model Context Protocol) security proxy with: 1. Native OAuth authorization 2. MCP server routing for authorized tokens based on token scopes Let me think about what this involves: **MCP (Model Context Protocol)**: This is Anthropic's protocol for connecting AI assistants to external data sources and tools. MCP servers expose tools, resources, and prompts. The proxy would sit between MCP clients and MCP servers. **Architecture needed:** 1. **HTTPS Server** - TLS termination 2. **OAuth Authorization Server** functionality or integration: - Token issuance (or validation against external IdP) - Token introspection/validation - Scope-based authorization 3. **Routing logic** - based on token scopes, route to different MCP backend servers 4. **MCP Proxy logic** - forward JSON-RPC messages to appropriate backend MCP servers Key components: 1. **OAuth 2.0 with JWT tokens**: - Issue tokens via client credentials / authorization code flow - Validate JWT signatures (using JWKS or shared secret) - Extract scopes from tokens 2. **Scope-to-route mapping**: - e.g., `mcp:filesystem:read` → filesystem MCP server - `mcp:github` → GitHub MCP server - Scopes determine which backend servers and which methods/tools are accessible 3. **MCP Protocol handling**: - MCP uses JSON-RPC 2.0 over various transports (stdio, SSE, HTTP+SSE, Streamable HTTP) - Methods: `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`, `notifications/*` - The proxy should filter `tools/list` results based on scopes, and authorize `tools/call` based on scopes Let me design this in Node.js (TypeScript or JavaScript) since that's common for MCP work, or Python. Node.js with the MCP SDK would be natural. Let me use Node.js with TypeScript-ish approach but keep it as JavaScript for simplicity, or provide TypeScript. Actually, let me think about what makes a good response. The user wants a complete, working example. I should: 1. Provide the complete server code 2. Include OAuth token endpoint (client credentials flow for simplicity, maybe mention how to plug a real IdP) 3. JWT validation 4. Scope-based routing configuration 5. MCP JSON-RPC proxying with method/tool filtering 6. TLS setup 7. Instructions to generate certs and run Let me architect: ``` Client → HTTPS → [Auth Middleware: validate Bearer JWT] → [Scope Router] → [Policy Filter] → Backend MCP Server A/B/C ``` Backend MCP servers could be spawned stdio processes or remote SSE/HTTP. For simplicity and completeness, I'll proxy the Streamable HTTP transport (and optionally spawn stdio servers via the MCP SDK and bridge them). Approach: Use `@modelcontextprotocol/sdk` to act as a client to backend servers (spawning them as stdio processes), and expose an HTTP(S) front that handles Streamable HTTP. The proxy: - Validates OAuth tokens (JWT) - Maps scopes → server access + method/tool filtering - Routes namespaced tool calls Alternatively, simpler and more robust: pure HTTP proxy that forwards MCP JSON-RPC requests to backend MCP Streamable HTTP endpoints, with authorization checks and response filtering. Let me write a comprehensive implementation. I'll go with Node.js + TypeScript? Long code. Maybe pure JavaScript (ESM) to reduce friction. Use minimal dependencies: - No external deps ideally: Node's built-in `https`, `crypto` for JWT HMAC/RSA verification... but real deployments use JWKS. To keep dependencies low, implement: - Token endpoint issuing JWTs signed with HS256 (shared secret) — mention RS256/JWKS for production - JWT verification with crypto - Backend servers: configured as upstream URLs (Streamable HTTP). Provide example config and show how to run e.g. `@modelcontextprotocol/server-filesystem` via `npx` ... but those are stdio. Hmm. Better: Spawn stdio MCP servers as child processes and bridge to them using JSON-RPC over stdio manually (no SDK dependency). That's a fair amount of code but doable: spawn process, write JSON-RPC lines framed per MCP stdio transport (newline-delimited JSON), read responses, match IDs. MCP stdio transport: messages are JSON-RPC messages delimited by newlines. So I can implement a lightweight stdio client: initialize, send request, await matching id. Plan for the proxy: **Components:** 1. `config.js` - server registry: ```js const servers = { filesystem: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'], requiredScope prefix... }, ... }; ``` 2. Scope mapping: ```js const scopeMap = { 'mcp:filesystem': { server: 'filesystem', tools: ['read_file','list_directory'], methods: [...] } } ``` Or compute per-tool scopes like `mcp:filesystem:read_file`. Design: scopes like `server:` grant access to a server; `tool::` grant specific tools; `mcp:readonly` etc. Keep simple: - Scope `servers:` → can connect to server `` - Scope `tools:` → can list/call tools on that server... Let me define a clear policy model: ``` { "servers": { "fs": { "transport": "stdio", "command": "...", "args": [...] }, "web": { "transport": "http", "url": "https://upstream/mcp" } } } ``` Policy from token scopes: - `mcp` — base access to proxy - `server:` — may use that backend server - `tool::` or `.` — may call specific tool (if no tool-specific scopes configured, server scope grants all) - Wildcard `*` variants Routing: The MCP client initializes with the proxy as a single logical MCP server that aggregates tools from authorized backends, namespaced as `__`? The MCP spec commonly uses namespacing when aggregating. Simpler: expose single endpoint; `tools/list` aggregates tools from all authorized backends with prefix `.`; `tools/call` parses prefix, checks scope, routes. That's a legit proxy design. Methods allowed/controlled: - `initialize` → proxy responds itself (aggregate serverInfo) - `ping` - `tools/list` → aggregate filtered by scopes - `tools/call` → route - `resources/list`, `resources/read` → route with prefix - `prompts/list`, `prompts/get` - Block/deny others OAuth endpoints: - `POST /oauth/token` — client_credentials grant, registers scopes; validate client against static registry (client_id/secret) - Discovery: `/.well-known/oauth-authorization-server` (RFC 8414) - Protected resource metadata: `/.well-known/oauth-protected-resource` (RFC 9728) - WWW-Authenticate header with `resource_metadata` on 401 (MCP auth spec) Also JWT fallback: accept tokens issued by external IdP via JWKS? That adds complexity; mention it and maybe implement JWKS fetch as optional. Keep code manageable: implement HS256 internal issuer + config option for external issuer with JWKS verification using `crypto` and fetch. That might be too long. I'll implement local issuer with HS256 and a stub/config for JWKS verification maybe. Let me decide: implement both but compactly? JWKS verification requires RSA verify — `crypto.verify` with public key from JWK (can convert JWK → KeyObject via `crypto.createPublicKey({ key: jwk, format: 'jwk' })`). Actually Node supports JWK import! So JWKS verify is maybe 30 lines. Could include optional. Length concern: The full solution is big. The user asked to "create" it — code-heavy answer is expected. I'll aim for a comprehensive single-file-ish project with a few files: - `server.mjs` — main HTTPS + MCP proxy + OAuth - `config.mjs` or config.json — servers + clients + policy - `README` instructions inline in the response Maybe split: 1. `config.js` (clients, servers, scope policy) 2. `oauth.js` (token issuance, JWT sign/verify, discovery) 3. `backend.js` (stdio bridge class + http upstream class) 4. `proxy.js` (MCP routing/aggregation) 5. `server.js` (https wiring) Response format: headers per language guidelines—use markdown with code blocks. Include: - Architecture overview (brief) - Full code - Setup: openssl cert generation, npm, run - Example: get token, list tools, call tool, scope denial example - Production notes/hardening Let me write the code carefully. **OAuth module:** ```js // oauth.mjs import crypto from 'node:crypto'; const b64u = (buf) => Buffer.from(buf).toString('base64url'); export class OAuthIssuer { constructor({ issuer, secret, ttl = 3600 }) { this.issuer = issuer; this.secret = secret; this.ttl = ttl; } sign(payload) { const header = { alg: 'HS256', typ: 'JWT' }; const data = `${b64u(JSON.stringify(header))}.${b64u(JSON.stringify(payload))}`; const sig = crypto.createHmac('sha256', this.secret).update(data).digest('base64url'); return `${data}.${sig}`; } issueToken({ sub, client_id, scope }) { const now = Math.floor(Date.now() / 1000); return this.sign({ iss: this.issuer, sub, client_id, scope, iat: now, exp: now + this.ttl, jti: crypto.randomUUID(), }); } verify(token) { // returns {ok, claims?, error?} } } ``` Token endpoint handler: parse form body, validate grant_type=client_credentials, client auth via basic or body, check requested scopes ⊆ client's allowed scopes, issue. WWW-Authenticate: on 401 `Bearer resource_metadata="https://host/.well-known/oauth-protected-resource"`. **Scope policy:** ```js export function buildPolicy(scopeString) { const scopes = new Set(scopeString.split(/\s+/).filter(Boolean)); return { scopes, serverAllowed: (alias) => scopes.has(`server:${alias}`) || scopes.has('server:*'), toolAllowed: (alias, tool) => scopes.has(`tool:${alias}:${tool}`) || scopes.has(`tool:${alias}:*`) || (!hasAnyToolScopesFor(scopes, alias) && (scopes.has(`server:${alias}`) || scopes.has('server:*'))), }; } ``` Hmm: if user has `server:fs` but also `tool:fs:read_file`, semantics get murky. Define: tool-specific scopes, if present for that server, act as allowlist; otherwise server scope allows all tools. Also support `mcp:readonly`? That maps to only safe methods. Maybe add `mcp:read` / `mcp:write`? Could overcomplicate. Add method-level gating: treat resources/read and prompts/get as read; tools/call as execute. Maybe map scope `server::read`? Hmm. Simplify policy axes: - `server:` or `server:*` → server visible - `tool::` / `tool::*` / `tool:*:*` → tool allowlist (union) - If no `tool:` scopes at all for an allowed server, all its tools allowed. Also `mcp:methods` could gate resources/prompts. I'll gate resources and prompts behind server scope too, plus optional `resource::*`? Too much. I'll mention extension points. **Backend connectors:** Stdio McpBackend: ```js import { spawn } from 'node:child_process'; import readline from 'node:readline'; class StdioBackend { constructor(name, { command, args, env }) { this.name = name; this.command = command; this.args = args; this.pending = new Map(); this.nextId = 1; this.ready = this.start(); } start() { this.proc = spawn(this.command, this.args, { stdio: ['pipe','pipe','inherit'] }); const rl = readline.createInterface({ input: this.proc.stdout }); rl.on('line', (line) => { let msg; try { msg = JSON.parse(line); } catch { return; } if (msg.id !== undefined && this.pending.has(msg.id)) { const { resolve } = this.pending.get(msg.id); this.pending.delete(msg.id); resolve(msg); } }); return this.request('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'mcp-security-proxy', version: '1.0.0' }, }).then(() => this.notify('notifications/initialized', {})); } request(method, params) { const id = this.nextId++; return new Promise((resolve, reject) => { const timer = setTimeout(() => { this.pending.delete(id); reject(new Error('timeout')); }, 30000); this.pending.set(id, { resolve: (m) => { clearTimeout(timer); resolve(m); }, reject }); this.proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n'); }); } notify(method, params) { this.proc.stdin.write(JSON.stringify({ jsonrpc:'2.0', method, params }) + '\n'); } } ``` HttpBackend (Streamable HTTP upstream): POST JSON, handle `application/json` or SSE response; parse SSE events for result. Basic: ```js class HttpBackend { constructor(name, { url, headers }) { ... } async request(method, params, meta) { const res = await fetch(this.url, { method:'POST', headers: { 'content-type':'application/json', 'accept':'application/json, text/event-stream', ...this.headers }, body: JSON.stringify({jsonrpc:'2.0', id: crypto.randomUUID(), method, params }) }); const ct = res.headers.get('content-type') || ''; if (ct.includes('text/event-stream')) { parse SSE for response message } else return await res.json(); } } ``` SSE parsing: read lines, `data:` accumulate, find JSON-RPC with matching id... I need a small SSE parser. Doable. Initialize for upstream HTTP with session id (mcp-session-id header) handling. This adds complexity; I'll implement session capture: on initialize response, capture `mcp-session-id` header, send `notifications/initialized`. Include. **Proxy handler:** For each authenticated request on `/mcp` (POST): - Parse JSON-RPC (support batch? keep single + notifications) - `initialize`: return proxy capabilities: tools, resources, prompts; serverInfo proxy. - `tools/list`: iterate allowed servers, fetch `tools/list` from each, namespace names `.`, filter by policy, aggregate. Cache tool list per token? Cache per backend with TTL. - `tools/call`: parse name `alias.tool`, check policy, forward with original name, return result. Optionally namespace content? Return as-is. - `resources/list`: aggregate with uri prefixing? URIs can't be namespaced easily; add metadata? I'll prefix uri scheme: `alias+originaluri`? For resources, common aggregation routes by `resourceTemplates`. To keep scope routing strict and simple, I could route resources/read by matching template prefix `alias://`? That's invasive. Simpler: resources list aggregated where each server exposes its own URIs; on `resources/read`, try each allowed server (first success). Scope gating still applies per server. Fine, note it. - `prompts/list` aggregate with name prefix; `prompts/get` route. - Unknown → error -32601, or -32603. GET `/mcp` → 405 or SSE not supported (we could say no SSE for client side; we expose simple POST JSON-RPC, aka "Streamable HTTP without streaming", acceptable minimal transport). MCP spec Streamable HTTP: client POSTs and server may reply JSON. That's fine for requests with responses. We'll also accept GET → 405. Actually returning 405 signals SSE unsupported which is allowed. Response format for MCP: must set `Accept: application/json, text/event-stream` from client per spec, but we don't need to enforce. **Per-request scoping:** The policy comes from the token claims. **Tool caching:** `backend.listTools()` cached; invalidate after `notifications/tools/list_changed`? Keep simple TTL cache or cache once after init. I'll cache at startup lazily with TTL 60s. **HTTPS server:** `https.createServer({key, cert}, handler)`. Route: - `POST /oauth/token` - `GET /.well-known/oauth-authorization-server` - `GET /.well-known/oauth-protected-resource` - `POST /mcp` (auth) - `GET /health` Auth middleware for /mcp: `Authorization: Bearer `, verify, build policy, attach. Also rate limiting? Mention hardening notes. **Client registry (config):** ```js const clients = { 'demo-client': { secret: 'demo-secret', scopes: ['server:fs','tool:fs:read_file','tool:fs:list_directory','server:fetch','tool:fetch:fetch'] }, 'admin': { secret: '...', scopes: ['server:*','tool:*:*'] }, }; ``` Also generate secrets via env. **Config for backends:** ```js const backends = { fs: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/srv/data'] }, // http example // upstream: { type: 'http', url: 'http://localhost:9000/mcp', headers: {} } }; ``` Now full code assembly. Let me write it cleanly. File layout: - `package.json` - `src/config.mjs` - `src/oauth.mjs` - `src/backends.mjs` - `src/proxy.mjs` - `src/server.mjs` Let me now write each. **oauth.mjs:** ```js import crypto from 'node:crypto'; const b64url = (input) => Buffer.from(typeof input === 'string' ? input : JSON.stringify(input)).toString('base64url'); export class OAuthServer { constructor({ issuer, secret, ttlSeconds = 3600, clients }) { this.issuer = issuer; this.secret = secret; this.ttl = ttlSeconds; this.clients = clients; // Map or object } ... } ``` Token endpoint logic: ```js async handleTokenRequest(req, res) { const body = await readFormBody(req); if (body.grant_type !== 'client_credentials') return jsonError(res, 400, 'unsupported_grant_type'); const creds = parseClientAuth(req, body); // basic or body const client = this.clients[creds.id]; if (!client || !timingSafeEq(client.secret, creds.secret)) return jsonError(res, 401, 'invalid_client', {'WWW-Authenticate':'Basic realm="oauth"'}); const requested = (body.scope || client.scopes.join(' ')).split(/\s+/).filter(Boolean); if (!requested.every(s => client.scopes.includes(s))) return jsonError(res, 400, 'invalid_scope'); const token = this.issue({ sub: creds.id, client_id: creds.id, scope: requested.join(' ') }); res.writeHead(200, {'content-type':'application/json', 'cache-control':'no-store'}); res.end(JSON.stringify({ access_token: token, token_type: 'Bearer', expires_in: this.ttl, scope: requested.join(' ') })); } ``` JWT verify: split, check alg HS256, signature compare with timingSafeEqual, parse JSON, check iss, exp, nbf. Discovery docs: ```js metadata() { return { issuer: this.issuer, token_endpoint: `${this.issuer}/oauth/token`, grant_types_supported: ['client_credentials'], token_endpoint_auth_methods_supported: ['client_secret_basic','client_secret_post'], scopes_supported: [...], code_challenge_methods_supported: undefined }; } protectedResourceMetadata() { return { resource: `${this.issuer}/mcp`, authorization_servers: [this.issuer], bearer_methods_supported: ['header'], scopes_supported: [...] }; } ``` **backends.mjs:** as sketched. Add graceful failure: if backend fails init, mark unhealthy, return empty lists. For SSE parsing on HTTP upstream: ```js async function readSse(res) { const reader = res.body? — use res.text() then parse lines splitting on \n\n events, take lines starting with 'data: ', join, JSON.parse each, find rpc response; } ``` Simpler: `const text = await res.text();` then split events on `\n\n`, parse data lines, collect JSON-RPC messages; find the one with `id === sentId`. Fine for moderate payloads. Session id capture: from initialize response headers `mcp-session-id`. Then include header on subsequent requests, and `MCP-Protocol-Version` header maybe. I'll capture and send. **policy.mjs** maybe fold into proxy. ```js export class Policy { constructor(scopeString) { this.scopes = new Set((scopeString||'').split(/\s+/).filter(Boolean)); } canSeeServer(alias) { return this.has(`server:${alias}`) || this.has('server:*'); } canCallTool(alias, tool) { if (!this.canSeeServer(alias)) return false; const toolScopes = [...this.scopes].filter(s => s.startsWith(`tool:${alias}:`)).concat(this.scopes.has('tool:*:*') ? [...] : []); // simplest: if any tool scope exists that could apply to this alias (including wildcards), enforce allowlist; else allow all on visible server } } ``` Define precisely: - `tool:*:*` grants all tools on any visible server. - `tool::*` grants all tools on alias. - `tool::` grants that tool. - If no tool scopes match alias (and no global wildcards), fall back to server visibility (all tools allowed). Rules: ```js canCallTool(alias, tool) { if (!this.canSeeServer(alias)) return false; if (this.scopes.has('tool:*:*')) return true; if (this.scopes.has(`tool:${alias}:*`)) return true; if (this.scopes.has(`tool:${alias}:${tool}`)) return true; // if the token carries ANY tool: scopes, treat them as an allowlist (deny by omission) const anyToolScope = [...this.scopes].some(s => s.startsWith('tool:')); return !anyToolScope; } ``` Similarly for resources/prompts maybe just gate by server visibility, plus `resources:` scopes optional. Keep to tools + servers, note extension. Also a global `mcp:access` scope required to use endpoint? Could require scope `mcp` — eh, any valid token works; scopes only constrain. Fine. **proxy.mjs:** ```js export class McpProxy { constructor(backends) { this.backends = backends; // { alias: Backend } this.toolCache = new Map(); // alias -> { ts, tools } } async handle(request, policy) { // request = JSON-RPC msg const { method, params, id } = request; switch (method) { case 'initialize': return ok(id, { protocolVersion: negotiate, capabilities: { tools: {}, resources: {}, prompts: {} }, serverInfo: {...}, instructions }); case 'ping': return ok(id, {}); case 'tools/list': return this.listTools(id, policy); case 'tools/call': return this.callTool(id, params, policy); case 'resources/list': ... case 'resources/read': ... case 'prompts/list': ... case 'prompts/get': ... case 'notifications/initialized': return null; // notification default: return err(id, -32601, `Method not allowed by proxy: ${method}`); } } } ``` Namespacing: `${alias}.${toolName}`. Names with dots are allowed in MCP tool names (MCP tool name regex allows `[a-zA-Z0-9_.-]`? Actually spec: SHOULD be `[a-zA-Z0-9_-]{1,64}`? The spec (2024-11-05) says name SHOULD match that... hmm, dots may violate SHOULD. Many proxies use `__`. I'll use `${alias}__${tool}` to be safe. And support un-nested alias parse: split on first `__`. tools/list aggregation: ```js async listTools(id, policy) { const out = []; await Promise.all(Object.entries(this.backends).map(async ([alias, be]) => { if (!policy.canSeeServer(alias)) return; let tools = await this.getTools(alias); // cached for (const t of tools) { if (!policy.canCallTool(alias, t.name)) continue; out.push({ ...t, name: `${alias}__${t.name}`, description: `[${alias}] ${t.description ?? ''}` }); } })); return ok(id, { tools: out }); } ``` Cache: ```js async getTools(alias) { const c = this.toolCache.get(alias); if (c && Date.now() - c.ts < 60000) return c.tools; const res = await this.backends[alias].request('tools/list', {}); const tools = res.result?.tools ?? []; this.toolCache.set(alias, { ts: Date.now(), tools }); return tools; } ``` Wrap errors: if backend errors → empty list (log). callTool: ```js async callTool(id, params, policy) { const name = params?.name ?? ''; const sep = name.indexOf('__'); if (sep <= 0) return err(id, -32602, 'Tool name must be namespaced as __'); const alias = name.slice(0, sep), toolName = name.slice(sep + 2); if (!this.backends[alias]) return err(id, -32602, `Unknown server '${alias}'`); if (!policy.canCallTool(alias, toolName)) { audit(...); return err(id, -32001, `Forbidden: token lacks scope 'tool:${alias}:${toolName}' or server access`); } const resp = await this.backends[alias].request('tools/call', { ...params, name: toolName }); if (resp.error) return err(id, resp.error.code, resp.error.message, resp.error.data); return ok(id, resp.result); } ``` resources/list: aggregate `resources` array, annotate with `_meta: {proxy: {server: alias}}`? And templates likewise. resources/read: determine target: exact match from cached resource list mapping uri→alias, else fan out. Simpler: fan out sequentially across visible servers; first success wins; also enforce scope by server visibility. Implement with cached resource lists mapping to alias; on read, try servers whose cached template/uri matches, else all visible. Let me do: build uri→alias from cached list; if mapping exists, call that; else try all visible servers until success. Good enough for demo. prompts similar to tools with prefixing. **Audit log:** console JSON lines: ts, client, method, tool, decision. **server.mjs:** ```js import https from 'node:https'; import fs from 'node:fs'; const config = loadConfig(); const oauth = new OAuthServer(...); const proxy = new McpProxy(buildBackends(config.backends)); const server = https.createServer({ key, cert }, async (req, res) => { const url = new URL(req.url, base); ... }); ``` Also send MCP required `WWW-Authenticate` on 401. Body parsing helper with size limit. Handle batch arrays? MCP 2024-11 removed batching; but older send batches. Handle single; if array, map. Easy to add: if Array → Promise.all and return array (filter nulls for notifications). Notifications: no id → return null → respond 202 with no body. Requests → JSON. Our response content-type application/json. **Certs:** instructions: ``` openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost" ``` **package.json:** ```json { "name": "mcp-security-proxy", "version": "1.0.0", "type": "module", "scripts": { "start": "node src/server.mjs" } } ``` Zero runtime deps (backends spawn npx servers). Nice selling point. Config file `config.mjs`: ```js export default { issuer: 'https://localhost:8443', port: 8443, jwtSecret: process.env.JWT_SECRET ?? 'dev-only-secret', tokenTtlSeconds: 3600, tls: { keyFile: 'key.pem', certFile: 'cert.pem' }, clients: { 'reader': { secret: process.env.CLIENT_READER_SECRET ?? 'reader-secret', scopes: ['server:fs', 'tool:fs:read_file', 'tool:fs:list_directory'] }, 'power': { secret: ..., scopes: ['server:*', 'tool:*:*'] }, }, backends: { fs: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()] }, // example of upstream http // weather: { type: 'http', url: 'http://127.0.0.1:9000/mcp' }, }, }; ``` Careful: exposing local cwd read. Use a `./data` dir. Edge: `npx -y @modelcontextprotocol/server-filesystem` exists as official server? Official: `@modelcontextprotocol/server-filesystem` yes exists (read/list/write/search/move/get info). Good demo. **Test flow:** ```bash TOKEN=$(curl -sk -X POST https://localhost:8443/oauth/token \ -d 'grant_type=client_credentials&client_id=reader&client_secret=reader-secret' | jq -r .access_token) curl -sk https://localhost:8443/mcp -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` Call: ``` -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fs__read_file","arguments":{"path":"..."}}}' ``` Denial example: try `fs__write_file` with reader token → -32001 Forbidden. Also mention `ListChanged` notifications etc. Also important MCP nuance: initialize protocolVersion negotiation — echo client's version if provided, else default '2024-11-05'... Use '2025-03-26'? Keep echo of client version, fallback '2024-11-05'. Timing-safe compare for client secret & JWT sig. Now, also, RFC 9728 protected resource metadata requires `resource`. Provide both well-known endpoints, and set `WWW-Authenticate: Bearer resource_metadata="..."` header on 401, per MCP authorization spec (2025-06-18 spec requires 401 + WWW-Authenticate on protected resource, pointing to PRM URL; older spec used server metadata). Good to implement PRM endpoint. Write the code with attention to correctness. Potential pitfalls: - readline interface on stdout only catches `\n`-delimited JSON — MCP stdio is newline-delimited, yes. - requests before ready: ensure `await backend.ready` before forwarding; store promise; handle rejection → backend dead. - Multiple concurrent requests fine via pending map with unique ids. - Child process stderr: inherit or pipe to logger; use `stdio: ['pipe','pipe','inherit']` fine. - On process exit, reject pending. Also cap concurrent access? Not needed. HTTP upstream: initialize once lazily, capture session. Also upstream may require `MCP-Protocol-Version` header after init. Add when we have session. Edge: response JSON-RPC messages from backend that aren't responses (server→client requests/notifications) — ignore in stdio too except log. Fine. Now write final answer structure: 1. Quick architecture diagram (ASCII) 2. Scope model & routing table 3. File tree 4. Code files 5. Setup + run + test commands 6. Hardening notes Keep prose concise; code dominates. Format guidelines: markdown, headers, code blocks. This is a substantial dev task, longer response is fine. Let me write the final code carefully, mentally checking syntax. **src/config.mjs** ```js export default { issuer: process.env.ISSUER ?? 'https://localhost:8443', port: Number(process.env.PORT ?? 8443), jwtSecret: process.env.JWT_SECRET ?? 'dev-only-change-me', tokenTtlSeconds: 3600, tls: { keyFile: process.env.TLS_KEY ?? 'key.pem', certFile: process.env.TLS_CERT ?? 'cert.pem', }, clients: { reader: { secret: process.env.READER_SECRET ?? 'reader-secret', scopes: ['server:fs', 'tool:fs:read_file', 'tool:fs:list_directory'], }, ops: { secret: process.env.OPS_SECRET ?? 'ops-secret', scopes: ['server:*', 'tool:*:*'], }, }, backends: { fs: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', './data'], timeoutMs: 30_000, }, }, }; ``` **src/oauth.mjs** ```js import crypto from 'node:crypto'; const b64url = (v) => Buffer.from(typeof v === 'string' ? v : JSON.stringify(v)).toString('base64url'); const safeEq = (a, b) => { const ba = Buffer.from(String(a)), bb = Buffer.from(String(b)); return ba.length === bb.length && crypto.timingSafeEqual(ba, bb); }; export class OAuthAuthorizationServer { constructor({ issuer, secret, ttlSeconds, clients }) { this.issuer = issuer.replace(/\/$/, ''); this.secret = secret; this.ttl = ttlSeconds; this.clients = clients; } // --- token issuance (client_credentials) --- issueToken({ sub, scope }) { const now = Math.floor(Date.now() / 1000); const claims = { iss: this.issuer, sub, client_id: sub, scope, iat: now, nbf: now, exp: now + this.ttl, jti: crypto.randomUUID() }; const header = b64url({ alg: 'HS256', typ: 'JWT' }); const body = b64url(claims); const sig = crypto.createHmac('sha256', this.secret).update(`${header}.${body}`).digest('base64url'); return { token: `${header}.${body}.${sig}`, claims }; } verifyToken(token) { const parts = String(token ?? '').split('.'); if (parts.length !== 3) throw new TokenError('malformed'); const [h, p, sig] = parts; const header = JSON.parse(Buffer.from(h, 'base64url').toString()); if (header.alg !== 'HS256') throw new TokenError('unexpected alg'); const expect = crypto.createHmac('sha256', this.secret).update(`${h}.${p}`).digest('base64url'); if (!safeEq(expect, sig)) throw new TokenError('bad signature'); const claims = JSON.parse(Buffer.from(p, 'base64url').toString()); const now = Math.floor(Date.now() / 1000); if (claims.iss !== this.issuer) throw new TokenError('bad issuer'); if (typeof claims.exp !== 'number' || now >= claims.exp) throw new TokenError('expired'); if (claims.nbf && now < claims.nbf) throw new TokenError('not yet valid'); return claims; } metadata() {...} protectedResourceMetadata() {...} scopesSupported() { const set = new Set(['server:*', 'tool:*:*']); ... from clients scopes return [...set]; } } export class TokenError extends Error {} ``` JSON parse errors should be caught in verify → wrap try/catch throwing TokenError. **Token endpoint handler** – put in server.mjs: ```js async function handleToken(req, res) { if (req.method !== 'POST') return send(res, 405, { error: 'method_not_allowed' }); const form = new URLSearchParams(await readBody(req)); const grant = form.get('grant_type'); // client auth: Basic header preferred let id = form.get('client_id'), secret = form.get('client_secret'); const auth = req.headers.authorization; if (auth?.startsWith('Basic ')) { const [cid, cs] = Buffer.from(auth.slice(6), 'base64').toString().split(':'); id = decodeURIComponent(cid); secret = decodeURIComponent(cs); } if (grant !== 'client_credentials') return send(res, 400, { error: 'unsupported_grant_type', error_description: 'only client_credentials is supported' }); const client = cfg.clients[id]; if (!client || !secret || !safeEq(client.secret, secret)) { res.setHeader('WWW-Authenticate', 'Basic realm="token"'); return send(res, 401, { error: 'invalid_client' }); } const requested = (form.get('scope')?.trim() || client.scopes.join(' ')).split(/\s+/).filter(Boolean); const granted = requested.filter(s => client.scopes.includes(s)); if (granted.length !== requested.length) { return send(res, 400, { error: 'invalid_scope', error_description: 'requested scope exceeds client permissions' }); } const { token } = oauth.issueToken({ sub: id, scope: granted.join(' ') }); send(res, 200, { access_token: token, token_type: 'Bearer', expires_in: cfg.tokenTtlSeconds, scope: granted.join(' ') }, { 'cache-control': 'no-store', pragma: 'no-cache' }); } ``` **Policy in proxy.mjs:** ```js export class ScopePolicy { constructor(scopeString = '') { this.scopes = new Set(scopeString.split(/\s+/).filter(Boolean)); } canSeeServer(alias) { return this.scopes.has('server:*') || this.scopes.has(`server:${alias}`); } canCallTool(alias, tool) { if (!this.canSeeServer(alias)) return false; if (this.scopes.has('tool:*:*')) return true; if (this.scopes.has(`tool:${alias}:*`)) return true; if (this.scopes.has(`tool:${alias}:${tool}`)) return true; const hasAnyToolScope = [...this.scopes].some((s) => s.startsWith('tool:')); return !hasAnyToolScope; } canReadResource(alias) { return this.canSeeServer(alias); } // extend with resource: scopes as needed canUsePrompt(alias, prompt) { if (!this.canSeeServer(alias)) return false; if (this.scopes.has('prompt:*:*')) return true; if (this.scopes.has(`prompt:${alias}:*`)) return true; if (this.scopes.has(`prompt:${alias}:${prompt}`)) return true; const hasAny = [...this.scopes].some(s => s.startsWith('prompt:')); return !hasAny; } } ``` Include prompts for symmetry. **backends.mjs:** ```js import { spawn } from 'node:child_process'; import readline from 'node:readline'; import crypto from 'node:crypto'; export class StdioBackend { constructor(alias, cfg) { this.alias = alias; this.cfg = cfg; this.nextId = 1; this.pending = new Map(); this.ready = null; } start() { const { command, args = [], env = {}, timeoutMs = 30000 } = this.cfg; this.timeoutMs = timeoutMs; this.proc = spawn(command, args, { env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'inherit'] }); this.proc.on('exit', (code) => { for (const [, p] of this.pending) p.reject(new Error(`backend ${this.alias} exited (${code})`)); this.pending.clear(); }); const rl = readline.createInterface({ input: this.proc.stdout }); rl.on('line', (line) => { let msg; try { msg = JSON.parse(line); } catch { return; } if (msg && msg.id != null) { const p = this.pending.get(msg.id); if (p) { this.pending.delete(msg.id); p.resolve(msg); } } }); this.ready = (async () => { const res = await this.request('initialize', { protocolVersion: '2025-06-18', capabilities: { tools: {}, resources: {}, prompts: {} }, clientInfo: { name: 'mcp-security-proxy', version: '1.0.0' }, }); this.notify('notifications/initialized'); return res; })(); this.ready.catch((e) => console.error(`[backend:${this.alias}] init failed:`, e.message)); return this.ready; } request(method, params = {}) { if (!this.proc || this.proc.exitCode !== null) return Promise.reject(new Error(`backend ${this.alias} not running`)); const id = this.nextId++; return new Promise((resolve, reject) => { const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`timeout calling ${this.alias}.${method}`)); }, this.timeoutMs); this.pending.set(id, { resolve: (v) => { clearTimeout(timer); resolve(v); }, reject: (e) => { clearTimeout(timer); reject(e); } }); this.proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n'); }); } notify(method, params = {}) { if (this.proc && this.proc.exitCode === null) this.proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'); } } ``` Wait: `request` checks timeoutMs property; set before ready. In start, set this.timeoutMs before calling request. OK. HTTP backend: ```js export class HttpBackend { constructor(alias, cfg) { this.alias = alias; this.url = cfg.url; this.headers = cfg.headers ?? {}; this.sessionId = null; this.timeoutMs = cfg.timeoutMs ?? 30000; } async init() { /* initialize + session capture */ } async request(method, params = {}) { ... } notify(method, params = {}) { fire-and-forget POST } } ``` Implementation: ```js start() { this.ready = (async () => { const res = await this.#rpc('initialize', { protocolVersion: '2025-06-18', capabilities: { tools: {}, resources: {}, prompts: {} }, clientInfo: { name: 'mcp-security-proxy', version: '1.0.0' }, }); await this.#notify('notifications/initialized'); return res; })(); this.ready.catch(...) return this.ready; } async #rpc(method, params) { const id = crypto.randomUUID(); const headers = { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...this.headers }; if (this.sessionId) headers['mcp-session-id'] = this.sessionId; const ctrl = new AbortController(); const t = setTimeout(() => ctrl.abort(), this.timeoutMs); try { const res = await fetch(this.url, { method: 'POST', headers, body: JSON.stringify({ jsonrpc: '2.0', id, method, params }), signal: ctrl.signal }); if (res.headers.get('mcp-session-id')) this.sessionId = res.headers.get('mcp-session-id'); const ct = res.headers.get('content-type') ?? ''; if (!res.ok) throw new Error(`upstream ${res.status}`); if (ct.includes('text/event-stream')) { const msgs = parseSse(await res.text()); const hit = msgs.find((m) => m.id === id); if (!hit) throw new Error('no matching response in SSE stream'); return hit; } return await res.json(); } finally { clearTimeout(t); } } ``` `parseSse(text)`: split on /\r?\n\r?\n/, for each event collect data lines, JSON.parse join('\n'), push. Notifications: POST, treat 202/200 ok. **proxy.mjs:** ```js export class McpProxy { constructor(backends) { this.backends = backends; this.cache = new Map(); this.ttlMs = 60_000; } async ready() { await Promise.allSettled(Object.values(this.backends).map(b => b.start())); } } ``` Wait — backends unify: give both classes `start()` returning ready promise and `request/notify`. Proxy constructor receives map alias→backend. In server.mjs: build map, then `await proxy.ready()`. Tool listing with per-alias failure tolerance: ```js async #toolsOf(alias) { cached... const resp = await be.request('tools/list'); catch → [] } ``` Policy filter + prefix. Resource list: fetch `resources/list` and `resourceTemplates/list` (tolerate method not found). resources/read: ```js async #readResource(id, params, policy) { const uri = params?.uri; const visible = Object.keys(this.backends).filter(a => policy.canSeeServer(a)); // find alias from cache mapping const map = this.#resourceIndex.get(uri); ... } ``` Simplify: try visible backends one by one until result without error; first `result` wins; if all error → return last error as -32602-ish. Also check `policy.canReadResource(alias)` — same as server visibility for now. Hmm, but blindly fanning out on read is a bit ugly; alternative: require URI prefix `alias://...` for routed read? That changes semantics of URIs. I'll implement "index from list cache; fallback fan-out" approach and document. Actually simpler and honest: maintain `resourceIndex` built whenever resources/list called (uri → alias). On read with unknown mapping, fan out to visible servers, first success wins. OK. prompts similar tools with prefix `alias__prompt`. initialize: ```js case 'initialize': { const pv = params?.protocolVersion ?? '2025-06-18'; return ok(id, { protocolVersion: pv, capabilities: { tools: { listChanged: false }, resources: { listChanged: false }, prompts: { listChanged: false } }, serverInfo: { name: 'mcp-security-proxy', version: '1.0.0' }, instructions: 'Tools are namespaced as __. Access is scope-gated.', }); } ``` Also handle `notifications/*` client notifications → ignore (return undefined → 202). Audit trail: ```js const audit = (event) => console.log(JSON.stringify({ ts: new Date().toISOString(), ...event })); ``` Log auth success, tool calls allow/deny. **server.mjs:** ```js import https from 'node:https'; import fs from 'node:fs'; import cfg from './config.mjs'; import { OAuthAuthorizationServer, TokenError } from './oauth.mjs'; import { StdioBackend, HttpBackend } from './backends.mjs'; import { McpProxy, ScopePolicy } from './proxy.mjs'; const readBody = (req, limit = 1_000_000) => new Promise((resolve, reject) => { let size = 0; const chunks = []; req.on('data', (c) => { size += c.length; if (size > limit) { reject(new Error('payload too large')); req.destroy(); } else chunks.push(c); }); req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8'))); req.on('error', reject); }); const send = (res, status, obj, headers = {}) => { const body = JSON.stringify(obj); res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body), ...headers }); res.end(body); }; ``` Build backends: ```js const backends = {}; for (const [alias, bc] of Object.entries(cfg.backends)) { backends[alias] = bc.type === 'stdio' ? new StdioBackend(alias, bc) : new HttpBackend(alias, bc); } const oauth = new OAuthAuthorizationServer({ issuer: cfg.issuer, secret: cfg.jwtSecret, ttlSeconds: cfg.tokenTtlSeconds, clients: cfg.clients }); const proxy = new McpProxy(backends); ``` Request handler routing: ```js const server = https.createServer({ key: fs.readFileSync(cfg.tls.keyFile), cert: fs.readFileSync(cfg.tls.certFile) }, async (req, res) => { try { const u = new URL(req.url, cfg.issuer); const path = u.pathname; if (path === '/health') return send(res, 200, { ok: true }); if (path === '/oauth/token' && req.method === 'POST') return handleToken(req, res); if (path === '/.well-known/oauth-authorization-server') return send(res, 200, oauth.metadata()); if (path === '/.well-known/oauth-protected-resource') return send(res, 200, oauth.protectedResourceMetadata()); if (path === '/mcp') return handleMcp(req, res); return send(res, 404, { error: 'not_found' }); } catch (e) { send(res, 500, { error: 'internal_error' }); } }); ``` handleMcp: ```js async function handleMcp(req, res) { if (req.method !== 'POST') { return send(res, 405, { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'POST required' } }, { allow: 'POST' }); } const auth = req.headers.authorization ?? ''; const m = auth.match(/^Bearer (.+)$/i); const wwwAuth = `Bearer resource_metadata="${cfg.issuer}/.well-known/oauth-protected-resource"`; if (!m) return send(res, 401, { error: 'missing_token' }, { 'www-authenticate': wwwAuth }); let claims; try { claims = oauth.verifyToken(m[1]); } catch (e) { return send(res, 401, { error: 'invalid_token', error_description: e.message }, { 'www-authenticate': `${wwwAuth}, error="invalid_token"` }); } const policy = new ScopePolicy(claims.scope); let payload; try { payload = JSON.parse(await readBody(req)); } catch { return send(res, 400, { jsonrpc:'2.0', id:null, error:{code:-32700, message:'Parse error'} }); } if (Array.isArray(payload)) { const replies = (await Promise.all(payload.map(p => proxy.handle(p, policy, claims)))).filter(Boolean); if (!replies.length) { res.writeHead(202); return res.end(); } return send(res, 200, replies); } const reply = await proxy.handle(payload, policy, claims); if (!reply) { res.writeHead(202); return res.end(); } send(res, 200, reply); } ``` Wait — MCP spec: server should return 202 with empty body for notifications/responses-only. Good. proxy.handle(message, policy, claims): if no `id` and method starts 'notifications/' → return undefined. If no id otherwise → error -32600. Validate jsonrpc === '2.0'. Start: ```js proxy.ready().then(() => { server.listen(cfg.port, () => console.log(`🔒 MCP security proxy on ${cfg.issuer}`)); }); ``` But oauth handleToken needs cfg.oauth etc within closure; fine. Define handler functions inside server.mjs module scope using config — simplest as top-level functions referencing module-scope vars. handleToken references cfg and oauth — fine. safeEq import from oauth.mjs — export it. Also add `getScopesSupported`: union of client scopes + wildcards. In metadata. Also `POST /oauth/token` content-type form. Fine via URLSearchParams from raw body. **CORS?** Not needed for typical usage; skip. **One concern:** stdio backend's `initialize` while proxy `wait`. In proxy.ready(): `await Promise.allSettled(Object.entries(this.backends).map(([a,b]) => b.start()))`. Backends also lazily ensure ready before requests in future — we can await `b.ready` inside proxy methods? The ready promise is set at start. If some backend fails, mark down; when listing tools if down → skip. Add in `McpProxy`: ```js async toolsOf(alias) { const be = this.backends[alias]; await be.ready; // may throw ... } ``` Wrap in try/catch → return []. Good. Also note: for HttpBackend, `ready` property must exist; mirror interface. Both classes: method `start()` sets this.ready; property ready. OK. **PromptsGet namespacing:** prompt names may conflict across servers → same `alias__name` prefix; get routes by prefix. Tools likewise. Prompt arguments pass-through. Now write all files cleanly. Also note the `initialize` response from backend isn't needed by proxy beyond health. Potential issue: `readline` on stdout won't emit until newline; MCP stdio spec indeed newline-delimited JSON — correct. Also handle `tools/list` pagination (cursor)? Some servers paginate; implement loop while nextCursor (limit to e.g. 10 pages). Could add but adds bulk. I'll do simple: single request; mention pagination as extension. Alright, quick loop is small: ```js let cursor; do { resp = await be.request('tools/list', cursor ? { cursor } : {}); tools.push(...resp.result?.tools ?? []); cursor = resp.result?.nextCursor; } while (cursor && ++pages < 10); ``` Include. Now compose final answer. Keep explainer text tight; code complete. Add: - Architecture diagram - Scope model table - Repo layout - All code (package.json, config, oauth, backends, policy+proxy, server) - Setup commands (openssl, mkdir data, npm start) - Test: token, list, call allowed/denied, negative test - Hardening checklist (JWKS/RS256 external IdP, mTLS, rate limiting, per-user-token, audit sink, caching authz decisions, arg hashing, no wildcards in prod, etc.) Length will be long but appropriate. Use headers, lists, tables sparingly. Let me finalize code text now, double-checking bracket balance and API correctness (Node fetch available in 18+, `crypto.randomUUID` ok). One more check — MCP Streamable HTTP requires client sends Accept header; as a proxy server we should accept any. Fine. For the OAuth metadata endpoint name with issuer path: RFC 8414 says `/.well-known/oauth-authorization-server`. OK. PRM RFC 9728: `/.well-known/oauth-protected-resource`. OK. Write it out. In `oauth.mjs` verifyToken, JSON.parse may throw → wrap. Also `handleToken` sets `'cache-control': 'no-store'`. Also add a small helper wording: registering human users → authorization_code flow not implemented (client_credentials only) — note as production extension with PKCE. Alright, also edge: URL form decode of Basic creds: use decodeURIComponent safe with try/catch. Time to write the final response. I'll present it as a complete mini-project. Include `data/` note: the filesystem server restricts to allowed dir. Sanity check the proxy.handle signature and code coherence. Let me draft proxy.mjs fully: ```js // src/proxy.mjs const NS = '__'; export class ScopePolicy { constructor(scopeString = '') { this.scopes = new Set(scopeString.split(/\s+/).filter(Boolean)); } #has = (s) => this.scopes.has(s); canSeeServer(alias) { return this.#has('server:*') || this.#has(`server:${alias}`); } canCallTool(alias, tool) { if (!this.canSeeServer(alias)) return false; if (this.#has('tool:*:*') || this.#has(`tool:${alias}:*`) || this.#has(`tool:${alias}:${tool}`)) return true; return ![...this.scopes].some((s) => s.startsWith('tool:')); } canReadResource(alias) { return this.canSeeServer(alias); } canUsePrompt(alias, prompt) { if (!this.canSeeServer(alias)) return false; if (this.#has('prompt:*:*') || this.#has(`prompt:${alias}:*`) || this.#has(`prompt:${alias}:${prompt}`)) return true; return ![...this.scopes].some((s) => s.startsWith('prompt:')); } } export const audit = (event) => console.log(JSON.stringify({ ts: new Date().toISOString(), kind: 'audit', ...event })); const ok = (id, result) => ({ jsonrpc: '2.0', id, result }); const err = (id, code, message, data) => ({ jsonrpc: '2.0', id, error: { code, message, ...(data !== undefined ? { data } : {}) } }); const CACHE_TTL_MS = 60_000; const FORBIDDEN = -32001; export class McpProxy { constructor(backends) { this.backends = backends; // alias -> StdioBackend | HttpBackend this.cache = new Map(); // `${kind}:${alias}` -> { ts, items } this.resourceIndex = new Map(); // uri -> alias } async ready() { await Promise.allSettled(Object.values(this.backends).map((b) => b.start())); } async #list(alias, kind, params = {}) { const key = `${kind}:${alias}`; const hit = this.cache.get(key); if (hit && Date.now() - hit.ts < CACHE_TTL_MS) return hit.items; const be = this.backends[alias]; const method = kind === 'tools' ? 'tools/list' : kind === 'resources' ? 'resources/list' : 'prompts/list'; const itemsKey = kind === 'resourceTemplates' ? 'resourceTemplates' : kind; // for resources list key 'resources' let cursor; const items = []; let pages = 0; try { await be.ready; do { const resp = await be.request(method, cursor ? { cursor } : params); if (resp.error) throw new Error(resp.error.message); items.push(...(resp.result?.[itemsKey] ?? [])); cursor = resp.result?.nextCursor; } while (cursor && ++pages < 10); } catch (e) { console.error(`[proxy] ${method} on '${alias}' failed: ${e.message}`); return []; } this.cache.set(key, { ts: Date.now(), items }); return items; } ... } ``` Hmm resourceTemplates: kind values 'tools'|'resources'|'prompts' plus separately 'resourceTemplates' with method 'resources/templates/list'. I'll incorporate four kinds. Or leave templates merged into resources/list aggregation fetch of both lists (some servers lack method → error → still return templates []). Let me restructure: `#list(alias, method, resultKey, cacheKey)`. ```js async #list(alias, method, resultKey) { const key = `${alias}:${method}`; const hit = this.cache.get(key); if (hit && Date.now() - hit.ts < CACHE_TTL_MS) return hit.items; const be = this.backends[alias]; let cursor; const items = []; let pages = 0; try { await be.ready; do { const resp = await be.request(method, cursor ? { cursor } : {}); if (resp.error) throw new Error(resp.error.message); items.push(...(resp.result?.[resultKey] ?? [])); cursor = resp.result?.nextCursor; } while (cursor && ++pages < 10); } catch (e) { console.error(`[proxy] ${method} → backend '${alias}' failed: ${e.message}`); return []; } this.cache.set(key, { ts: Date.now(), items }); return items; } ``` Enrich`: for tools/prompts: namespace names; for resources: index uri. handle: ```js async handle(msg, policy, claims) { const { method, params, id } = msg ?? {}; if (id === undefined && (method ?? '').startsWith('notifications/')) return undefined; if (id === undefined) return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid Request' } }; try { switch (method) { case 'initialize': return ok(id, this.#initialize(params)); case 'ping': return ok(id, {}); case 'tools/list': return ok(id, await this.#listTools(policy)); case 'tools/call': return this.#callTool(id, params, policy, claims); case 'resources/list': return ok(id, await this.#listResources(policy)); case 'resources/templates/list': return ok(id, await this.#listTemplates(policy)); case 'resources/read': return this.#readResource(id, params, policy, claims); case 'prompts/list': return ok(id, await this.#listPrompts(policy)); case 'prompts/get': return this.#getPrompt(id, params, policy, claims); case 'logging/setLevel': return ok(id, {}); default: return err(id, -32601, `Method '${method}' not supported by proxy`); } } catch (e) { return err(id, -32603, e.message); } } ``` #listResources indexes uris → alias. #readResource: ```js async #readResource(id, params, policy, claims) { const uri = params?.uri; if (!uri) return err(id, -32602, 'Missing uri'); let candidates = Object.keys(this.backends).filter((a) => policy.canReadResource(a)); const mapped = this.resourceIndex.get(uri); if (mapped && candidates.includes(mapped)) candidates = [mapped, ...candidates.filter(a => a !== mapped)]; let lastError = null; for (const alias of candidates) { audit({ event: 'resources/read', client: claims?.client_id, server: alias, uri, decision: 'attempt' }); const resp = await this.backends[alias].request('resources/read', { uri }).catch(e => ({ error: { message: e.message } })); if (!resp.error && resp.result) { await this.#ensureIndexed(alias); return ok(id, resp.result); } lastError = resp.error; } audit({ event: 'resources/read', client: claims?.client_id, uri, decision: 'deny' }); return err(id, -32602, lastError?.message ?? 'Resource not found on any authorized server'); } ``` ensureIndexed: after a successful read, cache mapping. Also build from resources/list. Fine-ish. Might skip ensureIndexed; keep list-driven indexing. Keep simple: index maintained in #listResources & #readResource success. #callTool: ```js async #callTool(id, params, policy, claims) { const { alias, name } = this.#split(params?.name); if (!alias || !this.backends[alias]) return err(id, -32602, `Unknown tool '${params?.name}' — expected '${NS}'`); if (!policy.canCallTool(alias, name)) { audit({ event: 'tools/call', client: claims?.client_id, server: alias, tool: name, decision: 'deny' }); return err(id, FORBIDDEN, `Forbidden: requires 'server:${alias}' and 'tool:${alias}:${name}' scopes`); } audit({ event: 'tools/call', client: claims?.client_id, server: alias, tool: name, decision: 'allow' }); const resp = await this.backends[alias].request('tools/call', { ...params, name }); return resp.error ? err(id, resp.error.code, resp.error.message, resp.error.data) : ok(id, resp.result); } #split(prefixed = '') { const i = prefixed.indexOf(NS); return i <= 0 ? { alias: null, name: null } : { alias: prefixed.slice(0, i), name: prefixed.slice(i + NS.length) }; } ``` Note: `__` could appear in tool names (rare). Split first occurrence ok. #listTools: ```js async #listTools(policy) { const out = []; await Promise.all(Object.keys(this.backends).map(async (alias) => { if (!policy.canSeeServer(alias)) return; for (const t of await this.#list(alias, 'tools/list', 'tools')) { if (!policy.canCallTool(alias, t.name)) continue; out.push({ ...t, name: `${alias}${NS}${t.name}`, description: t.description ? `[${alias}] ${t.description}` : `[${alias}]` }); } })); return { tools: out }; } ``` listResources: ```js async #listResources(policy) { const out = []; await Promise.all(Object.keys(this.backends).map(async (alias) => { if (!policy.canSeeServer(alias)) return; for (const r of await this.#list(alias, 'resources/list', 'resources')) { this.resourceIndex.set(r.uri, alias); out.push(r); } })); return { resources: out }; } #listTemplates similar with 'resources/templates/list','resourceTemplates'. Templates lack fixed uri; index by uriTemplate prefix? skip index. ``` prompts list/get similar to tools. Now backends: `HttpBackend` uses private methods with `#` — I referenced `this.#rpc`; that's fine (class private). Provide `start()` public like Stdio. I should double check `new URL(req.url, cfg.issuer)` for parse; fine. `server.listen` callback prints issuer. Also handle `SIGTERM` kill children: on exit, `Object.values(backends).forEach(b => b.proc?.kill?.())`. Add. One subtlety: `StdioBackend.start()` when spawn fails (command not found) → proc emits 'error' event → unhandled may crash; add `this.proc.on('error', ...)`. Add rejection: ready promise rejects. Actually request writes to stdin after error → EPIPE. Handle 'error' listener to log. Also for `initialize` we hardcode protocolVersion '2025-06-05' vs '2024-11-05'? For compatibility with typical servers (filesystem server supports 2024-11-05 and beyond...). Servers typically accept whatever client sends if >= min. Use '2025-06-18'. Newer servers fine. OK. Edge: `resources/read` capability advertisement: capabilities.resources — yes we advertise. Now the answer. Also demonstrate the WWW-Authenticate + well-known issuance briefly in test section. Production notes (short list): replace HS256 with IdP (Auth0/Keycloak) via JWKS RS256 verification, enforce audience (`aud`) claim, use `cnf`/DPoP or mTLS to bind tokens, persist per-client policies in DB, restrict wildcard scopes, set TLS 1.2+, limits, timeouts, add refresh/introspection/revocation, structured audit to SIEM, scope granular `resource:` / method scopes, add authorization_code + PKCE for user flows, token binding to server set, rate limit token endpoint, key rotation (kid header), short TTLs. JWKS sketch maybe brief snippet in notes. Keep it brief. Now writing final response. Aim for completeness over brevity but avoid fluff. # MCP Security Proxy — OAuth + Scope-Routed Gateway ## Architecture ``` ┌────────────────────────────────────────────────┐ MCP client (Claude, │ MCP Security Proxy (HTTPS) │ agent, curl) │ │ ──POST /oauth/token──► │ Token endpoint (client_credentials) ──► JWT │ │ │ ──POST /mcp──────────► │ 1. Bearer JWT verify (iss/exp/sig) │ Authorization: │ 2. ScopePolicy from token scopes │ Bearer │ 3. Route/filter JSON-RPC per policy │ │ 4. Audit allow/deny decisions │ └───────┬────────────────────┬──────────────────┘ │ stdio │ Streamable HTTP ▼ ▼ filesystem server upstream MCP server ``` **Scope model** (carried in the JWT `scope` claim): | Scope | Effect | |---|---| | `server:fs` / `server:*` | Server visible (can initialize, list, read resources) | | `tool:fs:read_file` | May call one tool | | `tool:fs:*` / `tool:*:*` | All tools on one/all servers | | *(no `tool:` scopes at all)* | Server scope implies all its tools | | `prompt:[:|*]` | Same logic for prompts | Backend tools are exposed namespaced as `__` (e.g. `fs__read_file`) — that's how the proxy routes a call and enforces the scope for it. ## Project layout ``` mcp-security-proxy/ ├── package.json ├── src/ │ ├── config.mjs # clients, scopes, backend registry │ ├── oauth.mjs # JWT issuer/verifier + discovery metadata │ ├── backends.mjs # stdio + Streamable-HTTP MCP upstream clients │ ├── proxy.mjs # scope policy + JSON-RPC routing/filtering │ └── server.mjs # HTTPS wiring, token endpoint, auth middleware ├── key.pem / cert.pem # generated └── data/ # sandbox dir exposed to the demo fs server ``` ### `package.json` ```json { "name": "mcp-security-proxy", "version": "1.0.0", "type": "module", "private": true, "scripts": { "start": "node src/server.mjs" }, "engines": { "node": ">=18" } } ``` Zero runtime dependencies — backends are spawned via `npx` and upstream HTTP uses built-in `fetch`. ### `src/config.mjs` ```js export default { issuer: process.env.ISSUER ?? 'https://localhost:8443', port: Number(process.env.PORT ?? 8443), jwtSecret: process.env.JWT_SECRET ?? 'dev-only-change-me', tokenTtlSeconds: 3600, tls: { keyFile: process.env.TLS_KEY ?? 'key.pem', certFile: process.env.TLS_CERT ?? 'cert.pem', }, // OAuth client registry (client_credentials grant) clients: { reader: { secret: process.env.READER_SECRET ?? 'reader-secret', scopes: ['server:fs', 'tool:fs:read_file', 'tool:fs:list_directory'], }, ops: { secret: process.env.OPS_SECRET ?? 'ops-secret', scopes: ['server:*', 'tool:*:*'], }, }, // Backend MCP servers (scope routing targets) backends: { fs: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', './data'], timeoutMs: 30_000, }, // Example upstream Streamable-HTTP server: // internal: { type: 'http', url: 'http://127.0.0.1:9000/mcp' }, }, }; ``` ### `src/oauth.mjs` ```js import crypto from 'node:crypto'; export class TokenError extends Error {} const b64url = (v) => Buffer.from(typeof v === 'string' ? v : JSON.stringify(v)).toString('base64url'); export const safeEq = (a, b) => { const ba = Buffer.from(String(a) ?? ''); const bb = Buffer.from(String(b) ?? ''); return ba.length === bb.length && crypto.timingSafeEqual(ba, bb); }; export class OAuthAuthorizationServer { constructor({ issuer, secret, ttlSeconds, clients }) { this.issuer = issuer.replace(/\/$/, ''); this.secret = secret; this.ttl = ttlSeconds; this.clients = clients; } /** Issue an HS256 JWT. Swap in RS256 + JWKS in production (see notes). */ issueToken({ sub, scope }) { const now = Math.floor(Date.now() / 1000); const header = b64url({ alg: 'HS256', typ: 'JWT' }); const body = b64url({ iss: this.issuer, sub, client_id: sub, scope, iat: now, nbf: now, exp: now + this.ttl, jti: crypto.randomUUID(), }); const sig = crypto .createHmac('sha256', this.secret) .update(`${header}.${body}`) .digest('base64url'); return `${header}.${body}.${sig}`; } /** Throws TokenError on any validation failure; returns claims on success. */ verifyToken(token) { try { const parts = String(token ?? '').split('.'); if (parts.length !== 3) throw new TokenError('malformed token'); const [h, p, sig] = parts; const header = JSON.parse(Buffer.from(h, 'base64url').toString()); if (header.alg !== 'HS256') throw new TokenError('unexpected alg'); const expected = crypto .createHmac('sha256', this.secret) .update(`${h}.${p}`) .digest('base64url'); if (!safeEq(expected, sig)) throw new TokenError('bad signature'); const claims = JSON.parse(Buffer.from(p, 'base64url').toString()); const now = Math.floor(Date.now() / 1000); if (claims.iss !== this.issuer) throw new TokenError('wrong issuer'); if (typeof claims.exp !== 'number' || now >= claims.exp) throw new TokenError('token expired'); if (claims.nbf && now < claims.nbf) throw new TokenError('token not yet valid'); return claims; } catch (e) { if (e instanceof TokenError) throw e; throw new TokenError('unparseable token'); } } scopesSupported() { const s = new Set(['server:*', 'tool:*:*', 'prompt:*:*']); for (const c of Object.values(this.clients)) c.scopes.forEach((x) => s.add(x)); return [...s]; } metadata() { // RFC 8414 return { issuer: this.issuer, token_endpoint: `${this.issuer}/oauth/token`, grant_types_supported: ['client_credentials'], token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post'], scopes_supported: this.scopesSupported(), }; } protectedResourceMetadata() { // RFC 9728 return { resource: `${this.issuer}/mcp`, authorization_servers: [this.issuer], bearer_methods_supported: ['header'], scopes_supported: this.scopesSupported(), }; } } ``` ### `src/backends.mjs` Stdio transport is newline-delimited JSON-RPC; Streamable HTTP upstreams return either JSON or SSE. Both expose the same `start() / request() / notify()` interface to the proxy. ```js import { spawn } from 'node:child_process'; import readline from 'node:readline'; import crypto from 'node:crypto'; const CLIENT_INFO = { name: 'mcp-security-proxy', version: '1.0.0' }; const PROTOCOL_VERSION = '2025-06-18'; export class StdioBackend { constructor(alias, cfg) { this.alias = alias; this.cfg = cfg; this.nextId = 1; this.pending = new Map(); this.ready = null; this.timeoutMs = cfg.timeoutMs ?? 30_000; } start() { const { command, args = [], env = {} } = this.cfg; this.proc = spawn(command, args, { env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'inherit'], }); this.proc.on('error', (e) => console.error(`[backend:${this.alias}] spawn error: ${e.message}`)); this.proc.on('exit', (code) => { for (const [, p] of this.pending) p.reject(new Error(`backend '${this.alias}' exited (${code})`)); this.pending.clear(); }); const rl = readline.createInterface({ input: this.proc.stdout }); rl.on('line', (line) => { let msg; try { msg = JSON.parse(line); } catch { return; } if (msg && msg.id != null && this.pending.has(msg.id)) { this.pending.get(msg.id).resolve(msg); this.pending.delete(msg.id); } }); this.ready = (async () => { const res = await this.request('initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {}, resources: {}, prompts: {} }, clientInfo: CLIENT_INFO, }); this.notify('notifications/initialized'); return res; })(); this.ready.catch((e) => console.error(`[backend:${this.alias}] init failed: ${e.message}`)); return this.ready; } request(method, params = {}) { if (!this.proc || this.proc.exitCode !== null) return Promise.reject(new Error(`backend '${this.alias}' is not running`)); const id = this.nextId++; return new Promise((resolve, reject) => { const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`timeout calling ${this.alias}.${method}`)); }, this.timeoutMs); this.pending.set(id, { resolve: (v) => { clearTimeout(timer); resolve(v); }, reject: (e) => { clearTimeout(timer); reject(e); }, }); this.proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n'); }); } notify(method, params = {}) { if (this.proc && this.proc.exitCode === null) this.proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'); } stop() { this.proc?.kill(); } } export class HttpBackend { constructor(alias, cfg) { this.alias = alias; this.url = cfg.url; this.headers = cfg.headers ?? {}; this.sessionId = null; this.timeoutMs = cfg.timeoutMs ?? 30_000; this.ready = null; } start() { this.ready = (async () => { const res = await this.rpc('initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {}, resources: {}, prompts: {} }, clientInfo: CLIENT_INFO, }); await this.notify('notifications/initialized'); return res; })(); this.ready.catch((e) => console.error(`[backend:${this.alias}] init failed: ${e.message}`)); return this.ready; } request(method, params = {}) { return this.rpc(method, params); } async rpc(method, params) { const id = crypto.randomUUID(); const headers = { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...this.headers, }; if (this.sessionId) headers['mcp-session-id'] = this.sessionId; const ctrl = new AbortController(); const timer = setTimeout(() => ctrl.abort(), this.timeoutMs); try { const res = await fetch(this.url, { method: 'POST', headers, body: JSON.stringify({ jsonrpc: '2.0', id, method, params }), signal: ctrl.signal, }); if (res.headers.get('mcp-session-id')) this.sessionId = res.headers.get('mcp-session-id'); if (!res.ok) throw new Error(`upstream ${this.alias} returned ${res.status}`); const ct = res.headers.get('content-type') ?? ''; if (ct.includes('text/event-stream')) { const msgs = parseSse(await res.text()); const hit = msgs.find((m) => m && m.id === id); if (!hit) throw new Error(`no matching response in SSE stream from '${this.alias}'`); return hit; } return await res.json(); } finally { clearTimeout(timer); } } async notify(method, params = {}) { try { const headers = { 'content-type': 'application/json', ...this.headers }; if (this.sessionId) headers['mcp-session-id'] = this.sessionId; await fetch(this.url, { method: 'POST', headers, body: JSON.stringify({ jsonrpc: '2.0', method, params }) }); } catch { /* notifications are best-effort */ } } stop() {} } function parseSse(text) { const msgs = []; for (const event of text.split(/\r?\n\r?\n/)) { const data = event.split(/\r?\n/) .filter((l) => l.startsWith('data:')) .map((l) => l.slice(5).trimStart()) .join('\n'); if (!data) continue; try { msgs.push(JSON.parse(data)); } catch { /* ignore */ } } return msgs; } ``` ### `src/proxy.mjs` This is where authorization becomes routing: ```js const NS = '__'; // namespace separator: __ const CACHE_TTL_MS = 60_000; const FORBIDDEN = -32001; // application-defined JSON-RPC error export class ScopePolicy { constructor(scopeString = '') { this.scopes = new Set(scopeString.split(/\s+/).filter(Boolean)); } has = (s) => this.scopes.has(s); canSeeServer(alias) { return this.has('server:*') || this.has(`server:${alias}`); } canCallTool(alias, tool) { if (!this.canSeeServer(alias)) return false; if (this.has('tool:*:*') || this.has(`tool:${alias}:*`) || this.has(`tool:${alias}:${tool}`)) return true; // Any explicit tool: scope turns the token into an allowlist. return ![...this.scopes].some((s) => s.startsWith('tool:')); } canReadResource(alias) { return this.canSeeServer(alias); // add resource: scopes here if needed } canUsePrompt(alias, prompt) { if (!this.canSeeServer(alias)) return false; if (this.has('prompt:*:*') || this.has(`prompt:${alias}:*`) || this.has(`prompt:${alias}:${prompt}`)) return true; return ![...this.scopes].some((s) => s.startsWith('prompt:')); } } export const audit = (event) => console.log(JSON.stringify({ ts: new Date().toISOString(), kind: 'audit', ...event })); const ok = (id, result) => ({ jsonrpc: '2.0', id, result }); const err = (id, code, message, data) => ({ jsonrpc: '2.0', id, error: { code, message, ...(data !== undefined ? { data } : {}) } }); export class McpProxy { constructor(backends) { this.backends = backends; // alias -> StdioBackend | HttpBackend this.cache = new Map(); // `${alias}:${method}` -> { ts, items } this.resourceIndex = new Map(); // uri -> alias } async ready() { await Promise.allSettled(Object.values(this.backends).map((b) => b.start())); } async handle(msg, policy, claims) { const { method, params, id } = msg ?? {}; if (id === undefined && (method ?? '').startsWith('notifications/')) return undefined; if (id === undefined || msg.jsonrpc !== '2.0') return err(id ?? null, -32600, 'Invalid Request'); try { switch (method) { case 'initialize': return ok(id, { protocolVersion: params?.protocolVersion ?? '2025-06-18', capabilities: { tools: { listChanged: false }, resources: { listChanged: false }, prompts: { listChanged: false }, }, serverInfo: { name: 'mcp-security-proxy', version: '1.0.0' }, instructions: 'Tools/prompts are namespaced __ and scope-gated.', }); case 'ping': return ok(id, {}); case 'tools/list': return ok(id, { tools: await this.listTools(policy) }); case 'tools/call': return this.callTool(id, params, policy, claims); case 'resources/list': return ok(id, { resources: await this.listResources(policy) }); case 'resources/templates/list': return ok(id, { resourceTemplates: await this.list(alias0(policy), 'resources/templates/list', 'resourceTemplates') }); case 'resources/read': return this.readResource(id, params, policy, claims); case 'prompts/list': return ok(id, { prompts: await this.listPrompts(policy) }); case 'prompts/get': return this.getPrompt(id, params, policy, claims); case 'logging/setLevel': return ok(id, {}); default: return err(id, -32601, `Method '${method}' not supported by proxy`); } } catch (e) { return err(id, -32603, e.message); } } // ---- aggregation helpers (cached, paginated, fault-tolerant) ---- async list(alias, method, resultKey) { const key = `${alias}:${method}`; const hit = this.cache.get(key); if (hit && Date.now() - hit.ts < CACHE_TTL_MS) return hit.items; const be = this.backends[alias]; let cursor, items = [], pages = 0; try { await be.ready; // reject if backend failed to initialize do { const resp = await be.request(method, cursor ? { cursor } : {}); if (resp.error) throw new Error(resp.error.message); items.push(...(resp.result?.[resultKey] ?? [])); cursor = resp.result?.nextCursor; } while (cursor && ++pages < 10); } catch (e) { console.error(`[proxy] ${method} -> '${alias}' failed: ${e.message}`); return []; } this.cache.set(key, { ts: Date.now(), items }); return items; } visibleAliases(policy) { return Object.keys(this.backends).filter((a) => policy.canSeeServer(a)); } // ---- tools ---- async listTools(policy) { const out = []; await Promise.all(this.visibleAliases(policy).map(async (alias) => { for (const t of await this.list(alias, 'tools/list', 'tools')) { if (!policy.canCallTool(alias, t.name)) continue; out.push({ ...t, name: `${alias}${NS}${t.name}`, description: t.description ? `[${alias}] ${t.description}` : `[${alias}]`, }); } })); return out; } async callTool(id, params, policy, claims) { const { alias, name } = splitName(params?.name); if (!alias || !this.backends[alias]) return err(id, -32602, `Unknown tool '${params?.name}' — use '${NS}'`); if (!policy.canCallTool(alias, name)) { audit({ event: 'tools/call', client: claims?.client_id, server: alias, tool: name, decision: 'deny' }); return err(id, FORBIDDEN, `Forbidden: needs 'server:${alias}' and 'tool:${alias}:${name}' scopes`); } audit({ event: 'tools/call', client: claims?.client_id, server: alias, tool: name, decision: 'allow' }); const resp = await this.backends[alias].request('tools/call', { ...params, name }); return resp.error ? err(id, resp.error.code, resp.error.message, resp.error.data) : ok(id, resp.result); } // ---- resources ---- async listResources(policy) { const out = []; await Promise.all(this.visibleAliases(policy).map(async (alias) => { for (const r of await this.list(alias, 'resources/list', 'resources')) { this.resourceIndex.set(r.uri, alias); out.push(r); } })); return out; } async readResource(id, params, policy, claims) { const uri = params?.uri; if (!uri) return err(id, -32602, 'Missing uri'); const candidates = this.visibleAliases(policy).filter((a) => policy.canReadResource(a)); const mapped = this.resourceIndex.get(uri); if (mapped && candidates.includes(mapped)) candidates.splice(0, 0, ...candidates.splice(candidates.indexOf(mapped), 1)); let lastError = null; for (const alias of candidates) { const resp = await this.backends[alias] .request('resources/read', { uri }) .catch((e) => ({ error: { message: e.message } })); if (!resp.error && resp.result) { this.resourceIndex.set(uri, alias); audit({ event: 'resources/read', client: claims?.client_id, server: alias, uri, decision: 'allow' }); return ok(id, resp.result); } lastError = resp.error; } audit({ event: 'resources/read', client: claims?.client_id, uri, decision: 'deny' }); return err(id, -32602, lastError?.message ?? 'Resource not found on any authorized server'); } // ---- prompts ---- async listPrompts(policy) { const out = []; await Promise.all(this.visibleAliases(policy).map(async (alias) => { for (const p of await this.list(alias, 'prompts/list', 'prompts')) { if (!policy.canUsePrompt(alias, p.name)) continue; out.push({ ...p, name: `${alias}${NS}${p.name}` }); } })); return out; } async getPrompt(id, params, policy, claims) { const { alias, name } = splitName(params?.name); if (!alias || !this.backends[alias]) return err(id, -32602, `Unknown prompt '${params?.name}'`); if (!policy.canUsePrompt(alias, name)) { audit({ event: 'prompts/get', client: claims?.client_id, server: alias, prompt: name, decision: 'deny' }); return err(id, FORBIDDEN, `Forbidden: needs 'prompt:${alias}:${name}' scope`); } const resp = await this.backends[alias].request('prompts/get', { ...params, name }); return resp.error ? err(id, resp.error.code, resp.error.message, resp.error.data) : ok(id, resp.result); } } // small helper used only for the templates one-liner above function alias0() { return undefined; } function splitName(prefixed = '') { const i = prefixed.indexOf(NS); return i <= 0 ? { alias: null, name: null } : { alias: prefixed.slice(0, i), name: prefixed.slice(i + NS.length) }; } ``` > ⚠️ Fix the `resources/templates/list` line so it aggregates over visible aliases like the other listers (the `alias0` one-liner is a placeholder). Cleanest version: > > ```js > case 'resources/templates/list': { > const all = []; > for (const a of this.visibleAliases(policy)) > all.push(...await this.list(a, 'resources/templates/list', 'resourceTemplates')); > return ok(id, { resourceTemplates: all }); > } > ``` ### `src/server.mjs` ```js import https from 'node:https'; import fs from 'node:fs'; import cfg from './config.mjs'; import { OAuthAuthorizationServer, TokenError, safeEq } from './oauth.mjs'; import { StdioBackend, HttpBackend } from './backends.mjs'; import { McpProxy, ScopePolicy, audit } from './proxy.mjs'; const oauth = new OAuthAuthorizationServer({ issuer: cfg.issuer, secret: cfg.jwtSecret, ttlSeconds: cfg.tokenTtlSeconds, clients: cfg.clients, }); const backends = {}; for (const [alias, bc] of Object.entries(cfg.backends)) { backends[alias] = bc.type === 'stdio' ? new StdioBackend(alias, bc) : new HttpBackend(alias, bc); } const proxy = new McpProxy(backends); // ---------- helpers ---------- const readBody = (req, limit = 1_000_000) => new Promise((resolve, reject) => { let size = 0; const chunks = []; req.on('data', (c) => { size += c.length; if (size > limit) { reject(new Error('payload too large')); req.destroy(); return; } chunks.push(c); }); req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8'))); req.on('error', reject); }); const send = (res, status, obj, headers = {}) => { const body = JSON.stringify(obj); res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body), ...headers, }); res.end(body); }; const wwwAuth = `Bearer resource_metadata="${cfg.issuer}/.well-known/oauth-protected-resource"`; // ---------- OAuth token endpoint (client_credentials) ---------- async function handleToken(req, res) { if (req.method !== 'POST') return send(res, 405, { error: 'method_not_allowed' }); const form = new URLSearchParams(await readBody(req)); let id = form.get('client_id'); let secret = form.get('client_secret'); const auth = req.headers.authorization; if (auth?.startsWith('Basic ')) { try { const decoded = Buffer.from(auth.slice(6), 'base64').toString(); const idx = decoded.indexOf(':'); id = decodeURIComponent(decoded.slice(0, idx)); secret = decodeURIComponent(decoded.slice(idx + 1)); } catch { /* fall through to invalid_client */ } } if (form.get('grant_type') !== 'client_credentials') return send(res, 400, { error: 'unsupported_grant_type' }); const client = id ? cfg.clients[id] : undefined; if (!client || !secret || !safeEq(client.secret, secret)) { audit({ event: 'token', client: id ?? 'unknown', decision: 'deny' }); return send(res, 401, { error: 'invalid_client' }, { 'www-authenticate': 'Basic realm="token"' }); } const requested = (form.get('scope')?.trim() || client.scopes.join(' ')) .split(/\s+/).filter(Boolean); if (!requested.every((s) => client.scopes.includes(s))) return send(res, 400, { error: 'invalid_scope', error_description: 'requested scope exceeds client permissions', }); const token = oauth.issueToken({ sub: id, scope: requested.join(' ') }); audit({ event: 'token', client: id, scope: requested.join(' '), decision: 'issue' }); return send(res, 200, { access_token: token, token_type: 'Bearer', expires_in: cfg.tokenTtlSeconds, scope: requested.join(' '), }, { 'cache-control': 'no-store', pragma: 'no-cache' }); } // ---------- Protected MCP endpoint ---------- async function handleMcp(req, res) { if (req.method !== 'POST') return send(res, 405, { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'POST required' } }, { allow: 'POST' }); const m = (req.headers.authorization ?? '').match(/^Bearer (.+)$/i); if (!m) return send(res, 401, { error: 'missing_token' }, { 'www-authenticate': wwwAuth }); let claims; try { claims = oauth.verifyToken(m[1]); } catch (e) { return send(res, 401, { error: 'invalid_token', error_description: e.message }, { 'www-authenticate': `${wwwAuth}, error="invalid_token"` }); } const policy = new ScopePolicy(claims.scope); audit({ event: 'auth', client: claims.client_id, scopes: claims.scope, decision: 'ok' }); let payload; try { payload = JSON.parse(await readBody(req)); } catch { return send(res, 400, { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); } if (Array.isArray(payload)) { const replies = (await Promise.all(payload.map((p) => proxy.handle(p, policy, claims)))).filter(Boolean); if (replies.length === 0) { res.writeHead(202); return res.end(); } return send(res, 200, replies); } const reply = await proxy.handle(payload, policy, claims); if (!reply) { res.writeHead(202); return res.end(); } // notification return send(res, 200, reply); } // ---------- HTTPS wiring ---------- const server = https.createServer( { key: fs.readFileSync(cfg.tls.keyFile), cert: fs.readFileSync(cfg.tls.certFile) }, async (req, res) => { try { const { pathname } = new URL(req.url, cfg.issuer); if (pathname === '/health') return send(res, 200, { ok: true }); if (pathname === '/oauth/token') return await handleToken(req, res); if (pathname === '/.well-known/oauth-authorization-server') return send(res, 200, oauth.metadata()); if (pathname === '/.well-known/oauth-protected-resource') return send(res, 200, oauth.protectedResourceMetadata()); if (pathname === '/mcp') return await handleMcp(req, res); return send(res, 404, { error: 'not_found' }); } catch (e) { console.error(e); return send(res, 500, { error: 'internal_error' }); } }, ); process.on('SIGTERM', () => Object.values(backends).forEach((b) => b.stop?.())); process.on('SIGINT', () => { Object.values(backends).forEach((b) => b.stop?.()); process.exit(0); }); await proxy.ready(); server.listen(cfg.port, () => { console.log(`MCP security proxy listening on ${cfg.issuer}`); }); ``` ## Run it ```bash # 1. TLS (dev self-signed) openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \ -days 365 -nodes -subj "/CN=localhost" mkdir -p data npm start ``` ### End-to-end test ```bash # 1. Get a scoped token (reader only gets fs.read_file + fs.list_directory) TOKEN=$(curl -sk https://localhost:8443/oauth/token \ -d 'grant_type=client_credentials&client_id=reader&client_secret=reader-secret' \ | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])') # 2. initialize curl -sk https://localhost:8443/mcp -H "Authorization: Bearer $TOKEN" \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' # 3. tools/list — only shows fs__read_file and fs__list_directory curl -sk https://localhost:8443/mcp -H "Authorization: Bearer $TOKEN" \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' # 4. allowed call ✓ curl -sk https://localhost:8443/mcp -H "Authorization: Bearer $TOKEN" \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fs__list_directory","arguments":{"path":"./data"}}}' # 5. denied call ✗ → -32001 Forbidden, audit logged curl -sk https://localhost:8443/mcp -H "Authorization: Bearer $TOKEN" \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"fs__write_file","arguments":{"path":"./data/x","content":"nope"}}}' # 6. no token → 401 + WWW-Authenticate with resource_metadata pointer curl -sk -i https://localhost:8443/mcp -d '{}' ``` ## Production hardening notes 1. **External IdP instead of self-issued HS256.** Point `verifyToken` at a JWKS endpoint (Auth0, Keycloak, Entra) and validate RS256/ES256 with `kid` rotation — Node can import JWKs natively via `crypto.createPublicKey({ key: jwk, format: 'jwk' })`. Validate `aud` so tokens for other APIs get rejected. 2. **Human users → authorization_code + PKCE.** The built-in grant is machine-to-machine; add `/authorize` and create authorization codes if interactive clients connect. 3. **Token binding.** Short TTLs help; consider DPoP or mTLS sender-constrained tokens so a leaked JWT is useless. 4. **Caching & rate limits.** Throttle `/oauth/token`, cache `tools/list` decisions per `(jti, method)` if backends are chatty, and bound pagination. 5. **Policy as data.** Move `clients`/`scopes` to a DB or OPA/Cedar engine if rules get complex; keep wildcard scopes out of production tokens. 6. **Audit sink.** Ship the JSON audit lines to your SIEM — every allow/deny decision is emitted with client, server, tool, and URI.

Create a HTTPS server that's a MCP security proxy which has ...