# Cortex Gateway

> Open-source (MIT), self-hosted federated MCP gateway: one OAuth 2.1-protected,
> spec-compliant MCP server (Streamable HTTP, MCP 2025-06-18) in front of N
> plain-HTTP backends. Permissions are never mirrored: the gateway propagates
> the real user identity (JWT to first-party backends, the user's own linked
> OAuth token to proxied third-party MCP servers), so each app's native
> permission model applies automatically at the user level.

Positioning in one line: aggregation without permission loss. Separate MCP
connectors keep native per-user permissions but multiply consents, token
stores and audit surfaces; hosted aggregators unify the surface but flatten
identity behind service accounts. Cortex keeps both properties: one OAuth
perimeter, zero flattening.

Framed another way: zero-trust principles for AI agents — the missing link
between your IAM (who your users are and what they may do) and the MCP ecosystem
(how agents call tools). Cortex carries each user's real identity and rights from
your existing identity provider into every agent tool call, so the agent inherits
exactly that user's access. Not a full ZTNA product; the identity-and-access
layer for agents.

A third framing: the permission layer for AI agents. Before an agent touches
anything that matters it must prove it is acting on behalf of a specific real
person and that this person holds the required rights. Cortex answers both on
every call — OAuth 2.1 delegation binds the agent to a real user, scopes bound
the authority, each app enforces its own rules on that identity. Most
agent-economy infrastructure (spend controls, escrow, disputes, liability)
presupposes this attribution primitive.

Security model (why agent access stays secure): every call rides an OAuth 2.1
perimeter — no shared API keys; the real user's identity is propagated so each
app enforces its own permissions and no over-privileged service account exists
(no permission flattening); tools are scope-filtered to least privilege;
third-party credentials live in a per-user AES-256-GCM vault; every call writes
one pseudonymized audit line and a single OAuth revocation cuts access
everywhere at once. Because the gateway decides nothing, there is nothing new
to trust.

Compliance: these are the controls audits test for on automated/agent access —
least-privilege scopes, per-user identity (no over-privileged service account),
a per-call attributable audit trail, central revocation. They map to ISO 27001:2022
Annex A access-control and logging controls (A.5.15, A.5.16, A.5.17, A.5.18, A.8.2,
A.8.15, A.8.16) and to SOC 2 CC6/CC7 — both of which apply today. The EU AI Act
articles usually cited (Art. 12 record-keeping, Art. 14 human oversight) govern
HIGH-RISK AI systems only; after the 2026 Digital Omnibus those obligations were
deferred to 2 Dec 2027 (stand-alone Annex III) and 2 Aug 2028 (Annex I embedded).
Most internal agent deployments are not high-risk, and a gateway is access
infrastructure, not an AI system. The audit trail is pseudonymized, NOT anonymous:
hashed identifiers remain personal data under GDPR Art. 4(5). Self-hosted = audit
trail and token vault stay in your perimeter, no extra sub-processor under GDPR
Art. 28 and none in your SOC 2 scope. Cortex supplies controls, not certification.

Disambiguation: this project is UNRELATED to Palo Alto Networks' Cortex
(XDR/XSIAM and their "Cortex Gateway" tenant portal), the CNCF Cortex
metrics project, and Cortex.io. "Cortex Gateway" here means the MIT-licensed
MCP federation gateway at cortex-gateway.dev
(github.com/wellknownmcp/cortex-gateway).

Key facts
- Repository: https://github.com/wellknownmcp/cortex-gateway (MIT)
- Docker image: ghcr.io/wellknownmcp/cortex-gateway
- Live demo MCP endpoint: https://mcp.cortex-gateway.dev/mcp (self-service
  signup via magic link; read-only demo tools)
- MCP server card (SEP-2127): https://cortex-gateway.dev/.well-known/mcp/server-card.json
  (catalog at /.well-known/mcp/catalog.json)
- Backend contract: a single POST endpoint (~120 lines to implement), no MCP
  library required in your apps
- Third-party native MCP servers federate via a built-in proxy adapter (beta)
  with a per-user AES-256-GCM token vault
- OAuth scopes double as plan entitlements: tools/list is filtered per caller
- Backends are self-describing: each exposes `<app>_get_help(topic?)`
  (business concepts, workflows, conventions) and agents are instructed to
  prefer it over guessing
- Built-in feedback loop: agents file `report_missing_capability` tickets
  (deduplicated, triaged, optionally backend-owned) when a capability is
  missing — unmet agent needs are logged where the domain lives
- Agent guidance for the repository itself: https://github.com/wellknownmcp/cortex-gateway/blob/main/AGENTS.md

## Docs
- [Home](https://cortex-gateway.dev/): positioning and feature overview
- [Company federation, worked example](https://cortex-gateway.dev/use-cases/company-federation/): one app per department behind one MCP connector — scopes as the org chart, day-2 operations
- [The permission layer for AI agents](https://cortex-gateway.dev/answers/agent-permission-layer/): how an agent proves it acts for a real person — replicate vs delegate, mechanisms, FAQ
- [MCP gateway vs MCP server](https://cortex-gateway.dev/answers/mcp-gateway-vs-mcp-server/): definitions, the three gateway archetypes (router / hosted platform / identity-propagating federation), when a gateway is unnecessary
- [AI agent compliance controls](https://cortex-gateway.dev/answers/ai-agent-compliance-controls/): the four properties auditors test on automated access, mapped to ISO 27001:2022 Annex A and SOC 2 CC6/CC7; why the EU AI Act probably does not apply; pseudonymized ≠ anonymous under GDPR
- [MCP security best practices](https://cortex-gateway.dev/answers/mcp-security-best-practices/): the six MCP threat categories (tool poisoning, rug pull, session hijacking, supply chain, cross-tenant leakage, pre-auth RCE), which published recommendations are implementable today vs still proposals (per-invocation message signing and signed tool descriptions are in no MCP client), what a federating gateway is the right enforcement point for — and the three things it does not solve
- [Expose your REST API as an MCP server](https://cortex-gateway.dev/guides/rest-api-to-mcp-server/): SDK-per-service vs OpenAPI generation vs gateway + thin HTTP contract; the five-step backend path
- [Secure your MCP server with OAuth 2.1](https://cortex-gateway.dev/guides/secure-mcp-with-oauth/): RFC 9728 discovery, the 401 WWW-Authenticate challenge, audience binding, scopes vs RBAC, multi-tenancy, revocation
- [Federate third-party MCP servers](https://cortex-gateway.dev/guides/federate-third-party-mcp-servers/): proxy adapter (beta), per-user AES-256-GCM token vault, one-time account linking, catalog discovery via a nominated linked account — providers see each user's own account, never a shared one
- [Expose an HTTP MCP server over stdio](https://cortex-gateway.dev/guides/expose-http-mcp-server-over-stdio/): mcp-remote vs auth bypass vs self-contained bridge with an ephemeral local OAuth issuer (real verification path, works headless); the six gotchas — stdout purity, protocol-version header, non-JSON-RPC error bodies, session echo, notification 202s, readiness budget
- [Too many MCP tools](https://cortex-gateway.dev/answers/mcp-too-many-tools/): tool definitions are re-sent every request (~20k tokens for 50+ tools) and degrade selection accuracy; scope filtering, X-Cortex-Backends (50-80% fewer tools), X-Cortex-Tool-Mode: search (~80% smaller payload, schemas on demand via find_tools)

## Troubleshooting (symptom → cause → fix)
- [MCP connector does nothing](https://cortex-gateway.dev/answers/mcp-connector-does-nothing/): the connector is added and nothing happens — missing WWW-Authenticate challenge, unexposed CORS header, Origin allowlist rejecting the web client, auth error returned as JSON-RPC 200
- [OAuth issuer behind a reverse proxy](https://cortex-gateway.dev/answers/mcp-oauth-issuer-behind-proxy/): login succeeds then every call 401s — origin derived from the inbound request breaks the audience check; pin the canonical URI, never trust X-Forwarded-Host
- [tools/list is empty](https://cortex-gateway.dev/answers/mcp-tools-list-empty/): agent authenticates but sees no tools — scope filtering (exact match, silent by design), X-Cortex-Backends narrowing, cold-boot catalog, backend down, discovery token refused, builtin name collision
- [unsupported_protocol_version](https://cortex-gateway.dev/answers/mcp-unsupported-protocol-version/): initialize gets HTTP 400 then times out (-32001) — the MCP-Protocol-Version header was sent during initialize; negotiation happens in the body, the header carries the negotiated version and only exists afterwards
- [Open-source MCP gateways compared](https://cortex-gateway.dev/alternatives/open-source-mcp-gateways/): six projects (IBM ContextForge, agentgateway, MCPJungle, Docker MCP Gateway, 1MCP, Lasso mcp-gateway, Cortex) separated on two axes — whose credential goes downstream, and where the authorization decision is made. Written by Cortex maintainers, verified from each repository 2026-07-09, states where each competitor wins.
- [Composio alternative](https://cortex-gateway.dev/alternatives/composio/): honest hosted-vs-self-hosted comparison
- [Pipedream MCP alternative](https://cortex-gateway.dev/alternatives/pipedream/): access layer vs workflow platform
- [Connect claude.ai](https://cortex-gateway.dev/connect/claude-ai/): Custom Connectors, 30-second setup
- [Connect Claude Desktop](https://cortex-gateway.dev/connect/claude-desktop/): Connectors UI + mcp-remote fallback
- [Connect Claude Code](https://cortex-gateway.dev/connect/claude-code/): claude mcp add + /mcp authenticate
- [Connect OpenClaw](https://cortex-gateway.dev/connect/openclaw/): openclaw mcp add --auth oauth
- [Connect Hermes Agent](https://cortex-gateway.dev/connect/hermes/): two-line mcp_servers YAML
- [Backend contract](https://github.com/wellknownmcp/cortex-gateway/blob/main/docs/backend-contract.md)
- [Deployment runbook](https://github.com/wellknownmcp/cortex-gateway/blob/main/docs/demo-deployment.md)