[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_123":124},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":-5,"_57":49,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":77,"_78":79,"_80":-5,"_81":-5,"_82":-5,"_83":49,"_84":-5,"_85":86,"_87":88,"_89":90,"_91":92,"_93":94,"_95":96,"_97":98},"apiUrl","https://odel.app/api","creator","wellknownmcp","moduleId","cortex-gateway","@wellknownmcp/cortex-gateway","displayName","cortex gateway","tagline","Self-hosted federated MCP gateway: one OAuth 2.1 MCP server in front of N apps, user-level scopes.","iconKey","https://avatars.githubusercontent.com/u/208590588?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://mcp.cortex-gateway.dev/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1783399128000,"updatedAt",1788069798000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.wellknownmcp%2Fcortex-gateway","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",12,"upstreamUpdatedAt",1787420947000,"detectedTransport","streamable-http","detectedAuthType","oauth","probeStatus","ok","lastProbedAt",1787291664000,"githubRepoUrl","https://github.com/wellknownmcp/cortex-gateway","githubRepoFullName","wellknownmcp/cortex-gateway","releaseId","ext-wellknownmcp-cortex-gateway","version","0.2.0","descriptionMarkdown","# Cortex Gateway\n\n[![CI](https://github.com/wellknownmcp/cortex-gateway/actions/workflows/ci.yml/badge.svg)](https://github.com/wellknownmcp/cortex-gateway/actions/workflows/ci.yml)\n[![Docker](https://github.com/wellknownmcp/cortex-gateway/actions/workflows/docker.yml/badge.svg)](https://github.com/wellknownmcp/cortex-gateway/actions/workflows/docker.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Glama score](https://glama.ai/mcp/servers/wellknownmcp/cortex-gateway/badges/score.svg)](https://glama.ai/mcp/servers/wellknownmcp/cortex-gateway)\n\n**A federated MCP gateway: one spec-compliant, OAuth-protected MCP server in\nfront of N plain-HTTP backends.**\n\nYour business apps stay ordinary web services. Each one exposes a single\n`POST /api/cortex/backend` endpoint (a ~120-line contract, no MCP library, no\nstdio). The gateway discovers their tools, merges them into one MCP catalog,\nenforces OAuth 2.1 + scopes, routes `tools/call` to the owning backend, and\nkeeps a pseudonymized audit trail.\n\nBuilt for one requirement: everyone in a company should be able to hand\ntheir own agent the keys — with exactly that person's rights, nothing\nmore, nothing less. And when agents become autonomous assistants, the\nanswer stays the same: the agent borrows the person's identity, the apps\nkeep enforcing that person's rights. The gateway decides nothing, so there\nis nothing new to trust.\n\nPut another way: **zero-trust principles for AI agents** — the missing link\nbetween your IAM (who your users are, what they may do) and the MCP ecosystem\n(how agents call tools). Not a full ZTNA product; the identity-and-access layer\nfor agents.\n\nA **backend** is a dedicated MCP reduced to its essence: a tool catalog plus\ntool invocation (and optional prompts/resources) over bare HTTP JSON-RPC —\nthe transport and lifecycle machinery (initialize, sessions, SSE, version\nnegotiation) lives once, in the gateway. Because the contract is a semantic\nsubset of MCP, a native MCP server can also be federated through the\nbuilt-in MCP→backend proxy adapter ([docs/mcp-adapter.md](https://github.com/wellknownmcp/cortex-gateway/blob/main/docs/mcp-adapter.md)).\n\n```\n[MCP agent: Claude Desktop / claude.ai Custom Connector / any MCP client]\n │ HTTPS + OAuth 2.1 JWT (Bearer)\n ▼\n[cortex-gateway] ←— thin gateway, no business logic\n │ HTTPS + the same JWT propagated (RFC 8707)\n ▼\n[your backends] ←— domain owners, plain HTTP, own their ACLs\n```\n\n## Why\n\n- **Permissions match the underlying app, automatically, at the user\n level.** The gateway never copies or mirrors permissions — it propagates\n the real user identity (your JWT to first-party backends, the user's own\n linked token to proxied third-party MCP servers), so each app's native\n permission model applies per user, with nothing to sync and no\n service-account flattening. Unlike hosted tool aggregators, the token\n vault and the audit trail stay on your infrastructure.\n- **One perimeter, not N connectors.** Wiring each app as its own MCP\n connector also keeps native permissions — and leaves you with N consents,\n N token stores, no shared audit, no cross-app entitlements, and a flooded\n tool list. The gateway collapses that to one OAuth surface without giving\n up the per-user model: aggregation without permission loss.\n- **Zero MCP lock-in in your apps.** Backends speak a minimal JSON-RPC\n contract over plain HTTP. Remove the gateway and you can still call them\n directly (tests, batch jobs, other integrations).\n- **One JWT, N backends.** The agent authenticates once; the gateway\n propagates the token; every backend re-validates it and applies its own\n permissions. Revocation at the authorization server cuts everything.\n- **Failure isolation.** An unreachable backend just disappears from\n `tools/list`; the rest keeps working.\n- **Context-aware federation.** Backend filtering and a compact \"search\"\n mode keep the tool catalog from flooding the agent's context\n ([docs/tool-search-mode.md](https://github.com/wellknownmcp/cortex-gateway/blob/main/docs/tool-search-mode.md)).\n- **Agent feedback loop.** Agents can file `report_missing_capability`\n tickets when a tool is missing or insufficient — deduplicated, triaged,\n optionally pushed to a webhook when blocking.\n\n## Use cases\n\n**Company-wide agent surface.** An organization runs N internal apps (CRM,\nquality docs, billing, analytics...). Each app adds the ~120-line backend\nendpoint; the gateway exposes them as ONE MCP connector protected by the\ncompany's SSO. Employees plug a single URL into Claude Desktop / claude.ai\nand get exactly the tools their token scopes allow, with a central audit\ntrail. This is the setup the gateway was born in.\n\n**Product builder.** You ship several products and want agents (yours or your\ncustomers') to operate them. Instead of maintaining one MCP server per\nproduct, every product implements the backend contract and the gateway is\nyour single, versioned, OAuth-protected agent API. Adding a product to the\nagent surface is one env var.\n\n**Thematic hub / curated registry.** Run a gateway as a *topic* endpoint —\ne.g. \"all open-data tools for domain X\" — that federates several providers\nbehind one URL with one token. The scope model gives you per-provider\nopt-in, `get_help`/`get_snapshot` give agents self-describing discovery, and\nthe audit trail tells you what is actually used. Providers either speak the\n(deliberately tiny) backend contract natively, or — for off-the-shelf MCP\nservers — get fronted by the built-in MCP→backend proxy adapter\n([docs/mcp-adapter.md](https://github.com/wellknownmcp/cortex-gateway/blob/main/docs/mcp-adapter.md)).\n\n**Free / paid tool tiers.** Scopes are entitlements. Let your authorization\nserver grant `mcp:yourapp:basic` to free users and `mcp:yourapp:pro` to\npaying ones (your billing webhook updates the grant): the gateway then shows\nand allows each caller exactly the tools of their plan — no paywall logic in\nthe gateway or the backends, tools just declare their scope. Revocation and\ndowngrades propagate through the normal OAuth chain.\n\n## Federating native MCP servers (adapter, beta)\n\nThe built-in **MCP→backend proxy adapter** lets a bundle mix contract\nbackends and off-the-shelf native MCP servers (Canva, Figma, ...): the\nadapter is an MCP client downstream (initialize, sessions, SSE framing) and\na plain backend upstream, so the gateway core does not change. Per-user\ndownstream OAuth is handled by a **token vault** (AES-256-GCM at rest) and a\n**linking flow** (RFC 9728 discovery, Dynamic Client Registration, PKCE):\neach user consents once per provider, then agents are identified on the\nwhole bundle with a single Cortex token. See\n[docs/mcp-adapter.md](https://github.com/wellknownmcp/cortex-gateway/blob/main/docs/mcp-adapter.md) for a worked \"design bundle\"\nexample (Canva + Figma + your own backend).\n\n## Roadmap\n- **Machine identity for discovery** — replace the static technical token\n with a `client_credentials` flow once your AS supports it.\n- **Shared event bus / rate-limit store** — for multi-instance deployments.\n\n## Features\n\n- MCP spec **2025-06-18** (Streamable HTTP transport: POST JSON-RPC, GET SSE\n for `listChanged` notifications, DELETE session termination)\n- Primitives: **tools**, **resources** (incl. URI templates), **prompts**\n- **OAuth 2.1 resource server**: JWKS verification, audience per resource\n (RFC 8707), protected-resource metadata (RFC 9728), optional RFC 7662\n introspection for revocation\n- **Scope-based visibility**: agents only see (and can call) the tools their\n token scopes allow; `scopes_supported` in discovery is derived live from\n the federated catalog\n- **Dynamic discovery**: backends are polled every 60s; new tools appear\n without redeploying the gateway, with SSE `tools/list_changed` push\n- **Builtins**: `whoami` (aggregated identity across backends),\n `find_tools`, `report_missing_capability`, `list_cortex_tickets`,\n `list_cortex_resources`, `read_cortex_resource`, plus a self-describing\n `cortex://architecture` resource generated live\n- **Audit trail**: one JSON line per call on stdout (hashed email, hashed\n params) + optional PostgreSQL persistence with retention cron\n- Origin allow-list (anti DNS-rebinding), per-token rate limiting, optional\n pool sandbox\n\n## Quickstart (no OAuth server needed)\n\n```bash\ngit clone https://github.com/wellknownmcp/cortex-gateway\ncd cortex-gateway\nnpm install\n\n# 1. Start the demo backend (dependency-free)\nnode examples/demo-backend/server.mjs &\n\n# 2. Configure the gateway\ncat > .env.local <<'EOF'\nOAUTH_ISSUER=https://auth.example.com\nCORTEX_BACKENDS=demo\nCORTEX_BACKEND_DEMO_URL=http://127.0.0.1:4820\nCORTEX_TECHNICAL_TOKEN=demo-technical-token\nCORTEX_DEV_BYPASS_TOKEN=dev-secret\nCORTEX_DEV_BYPASS_SCOPES=mcp:demo:read\nEOF\n\n# 3. Run it\nnpm run dev\n\n# 4. Talk MCP (dev bypass replaces the Bearer JWT locally)\ncurl -s http://localhost:3213/mcp \\\n -H 'Content-Type: application/json' \\\n -H 'X-Dev-Mode: dev-secret' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | jq '.result.tools[].name'\n# → whoami, ..., demo_get_help, demo_echo, demo_get_time\n\ncurl -s http://localhost:3213/mcp \\\n -H 'Content-Type: application/json' \\\n -H 'X-Dev-Mode: dev-secret' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"demo_echo\",\"arguments\":{\"message\":\"hello\"}}}' | jq\n```\n\nIn production you point `OAUTH_ISSUER` at your OAuth 2.1 authorization\nserver (any server that issues RS256 JWTs with a JWKS endpoint and supports\nthe `scope` claim), and MCP clients connect to `https://your-host/mcp` with\na Bearer token whose `aud` is the gateway's canonical URI.\n\n### stdio bridge (for stdio-only clients and directory sandboxes)\n\nThe gateway is a remote Streamable HTTP server, but some MCP clients — and\nthe Docker inspection harnesses of directories like Glama — only speak the\nstdio transport. `scripts/stdio-bridge.mjs` bridges the two: it boots the\nproduction build against an ephemeral local OAuth issuer (the real JWT\nverification path, no bypass), mints itself a short-lived token, and relays\nnewline-delimited JSON-RPC between stdin/stdout and `POST /mcp`.\n\n```bash\nnpm run build\nnpm run start:stdio # stdio MCP server on stdin/stdout\n```\n\nSelf-granted scopes come from `BRIDGE_SCOPES` (gateway builtins need none);\nthe gateway port from `BRIDGE_GATEWAY_PORT` (default 3213). Design notes and\nthe gotchas (stdout purity, protocol-version negotiation, session echo):\n.\n\n## Adding a backend\n\n1. Implement the contract in your app — one POST endpoint, `list_tools` +\n your tools ([docs/backend-contract.md](https://github.com/wellknownmcp/cortex-gateway/blob/main/docs/backend-contract.md), reference\n implementation in `examples/demo-backend/`).\n2. Declare it:\n ```bash\n CORTEX_BACKENDS=demo,docs\n CORTEX_BACKEND_DOCS_URL=http://127.0.0.1:4001\n ```\n3. Done. The gateway discovers `docs_*` tools within 60s and pushes\n `tools/list_changed` to connected clients.\n\n## Configuration\n\nEverything is env-driven — see [.env.example](https://github.com/wellknownmcp/cortex-gateway/blob/main/.env.example) for the full\nannotated list. The essentials:\n\n| Variable | Required | Purpose |\n|---|---|---|\n| `CORTEX_CANONICAL_URI` | prod | Canonical MCP resource URI (RFC 9728), default JWT audience |\n| `OAUTH_ISSUER` | yes | Your OAuth 2.1 authorization server |\n| `CORTEX_BACKENDS` + `CORTEX_BACKEND__URL` | yes | Federated backends |\n| `CORTEX_TECHNICAL_TOKEN` | yes | Static token for catalog discovery (catalog methods only) |\n| `CORTEX_ALLOWED_ORIGINS` | prod | Web origins allowed (exact or `*.suffix`) |\n| `CORTEX_TOOL_INTEGRITY_MODE` | no | `warn` (default) or `block` — rug-pull detection on tool definitions |\n| `CORTEX_ADMIN_SECRET` | with `block` | Secret for `/api/admin/tool-integrity`, the operator endpoint that reviews and clears quarantines |\n| `CORTEX_TOOL_BASELINE_FILE` | with `block` | Where approved tool definitions persist; without it a restart re-approves the current state |\n| `CORTEX_BASELINE_PRIVATE_KEY` / `_PUBLIC_KEY` | no | Ed25519 signing of that store. Public key alone = the gateway verifies approvals but cannot mint them |\n| `OAUTH_REQUIRED_SCOPES` | no | Baseline scope demanded before any dispatch |\n| `CORTEX_DATABASE_URL` | no | PostgreSQL for audit persistence + gateway tickets |\n| `CORTEX_TICKET_WEBHOOK_URL` | no | Webhook for blocking missing-capability tickets |\n| `CORTEX_WEBSITE_URL` | no | `websiteUrl` shown by MCP clients (default: the gateway origin). Server icons: replace `public/icon-{light,dark}.png` |\n\n## Security model\n\nTwo paths, and the difference between them is the whole design: the **catalog**\nis discovered in the background with a technical token that can only list, and\na **call** carries the user's own token all the way to the backend.\n\n```mermaid\nsequenceDiagram\n autonumber\n participant Agent as AI agent\n participant GW as Cortex Gateway\n participant AS as Authorization server\n participant App as Backend app\n\n rect rgba(128,128,128,0.10)\n note over GW,App: Catalog refresh — every 60s, no user involved\n GW->>App: tools/list (CORTEX_TECHNICAL_TOKEN)\n App-->>GW: full tool catalog\n note over GW: Fingerprint each definition
(rug-pull detection)\n end\n\n note over GW,AS: JWKS fetched once and cached —
tokens are verified locally, not per call\n\n Agent->>GW: tools/list (user JWT)\n note over GW: Verify signature, issuer, audience
Filter the cached catalog by the token's scopes\n GW-->>Agent: only the tools this user may call\n\n Agent->>GW: tools/call demo_echo (user JWT)\n note over GW: Check the scope declared by that tool\n GW->>App: tools/call — the user's JWT, forwarded\n note over App: Applies its own roles and ACLs
to that user\n App-->>GW: result, under the user's own rights\n GW-->>Agent: result\n note over GW: One audit line: who, which tool,
which backend, which scope\n```\n\nThe agent never holds a credential the user does not have, and no\nover-privileged service account exists anywhere on the path.\n\nAgent access is secured by construction, not by gateway policy. The properties\nbelow are what to demand from any MCP tooling you wire into an AI app:\n\n- **OAuth 2.1, not shared API keys** — every caller authenticates as themselves;\n tokens are per-user, scoped and revocable.\n- **No permission flattening** — the real user's identity is propagated to each\n backend, so no over-privileged service account exists and the agent gets\n exactly the user's own rights.\n- **Least privilege** — the tool catalog is scope-filtered per caller; agents\n only see the tools their token allows.\n- **Verifiable** — the whole OAuth discovery chain is walkable without a token,\n so you (or a third-party scanner) can confirm the posture before connecting.\n\nUnder the hood:\n\n- The gateway **decides nothing** about business permissions. OAuth scope is\n the front door (checked twice: gateway + backend); application roles and\n ACLs live in each backend.\n- The static technical token can only reach catalog methods\n ([src/contract/static-token.ts](https://github.com/wellknownmcp/cortex-gateway/blob/main/src/contract/static-token.ts)); every data\n method requires the end user's JWT.\n- Audit is pseudonymized by design (hashed email, hashed params). Pseudonymized\n is **not** anonymous: hashed identifiers remain personal data under GDPR\n Art. 4(5), so the audit trail stays in your record of processing and needs a\n retention period.\n- Sessions are bound to the token's `sub`; foreign session ids get 404.\n\n**Controls a federating gateway can enforce that a single server cannot.**\nBecause it sees every backend's tool definitions and every hop to them, the\ngateway is the place to catch what the ecosystem's incident reports keep\nfinding — full details in [docs/security.md](https://github.com/wellknownmcp/cortex-gateway/blob/main/docs/security.md):\n\n- **Rug-pull detection.** Tool definitions are fingerprinted (`description`,\n `inputSchema`, `scope`, `version`) at first sight and re-checked at every\n refresh. A backend that rewrites what a tool claims to do while keeping its\n name is reported, and with `CORTEX_TOOL_INTEGRITY_MODE=block` the tool is\n quarantined until an operator reviews it over `/api/admin/tool-integrity` —\n an HTTP endpoint, not an MCP tool, so a model cannot clear a rug pull on its\n own. Name-level change detection — what most implementations do — misses\n exactly this attack.\n- **No plaintext to remote hosts.** Every federated call forwards the caller's\n token, so an `http://` backend URL pointing anywhere but loopback is refused\n at load. Same validation on the OAuth endpoints the adapter *discovers* from\n a third-party server's metadata, which is the class of bug behind\n CVE-2025-6514.\n- **Attributable audit.** Each line records which backend served the call and\n under which scope — not just the tool name.\n\nHonest scope: approvals persist across restarts (`CORTEX_TOOL_BASELINE_FILE`)\nbut the store is not signed, so this proves \"this definition changed since you\napproved it here\", not \"this is the definition the vendor published\".\nOperator-signed baselines are the next step, not a claim being made today.\n\n**Compliance.** These are the controls audits test for on automated access:\nleast-privilege scopes, per-user identity (no over-privileged service account),\na per-call attributable audit trail, and central revocation. They map to\nISO 27001:2022 Annex A access-control and logging controls (A.5.15, A.5.16,\nA.5.17, A.5.18, A.8.2, A.8.15, A.8.16) and to SOC 2 CC6/CC7 — both of which\napply today. The EU AI Act articles usually cited (Art. 12 record-keeping,\nArt. 14 human oversight) govern **high-risk** AI systems only, and after the\n2026 Digital Omnibus those obligations were deferred to 2 Dec 2027 (stand-alone\nAnnex III) and 2 Aug 2028 (Annex I embedded); most internal agent deployments\nare not high-risk, and a gateway is access infrastructure rather than an AI\nsystem. Self-hosted means the audit trail and token vault stay in your\nperimeter — no extra sub-processor under GDPR Art. 28, none in your SOC 2\nscope. Cortex supplies the controls, not a certification. Full mapping:\n\n\n## Development\n\n```bash\nnpm run typecheck # tsc --noEmit\nnpm test # vitest\nnpm run build # prisma generate + next build\n```\n\nThe database is optional in every environment: without `CORTEX_DATABASE_URL`\nthe audit stays on stdout and gateway-local tickets are disabled.\n\n## License\n\n[MIT](https://github.com/wellknownmcp/cortex-gateway/blob/main/LICENSE)\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_105":106,"_107":108,"_109":110,"_111":112,"_113":-5,"_114":115},"requiredSecrets",[],"tags",[101,102,103,104],"assets",[],"stats",{"_99":86,"_100":86},"ratingAvg","reviewCount","ai-agents","federation","gateway","oauth2","topics",[101,102,103,121,122,104],"license","MIT","language","HTML","registryName","io.github.wellknownmcp/cortex-gateway","homepage","packages",[116],{"_117":118,"_119":120,"_76":-5},"registryType","oci","identifier","ghcr.io/wellknownmcp/cortex-gateway:v0.2.0","mcp","model-context-protocol","ENV",{"_125":126,"_127":128,"_129":130},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]