cortex-gateway — Claude Code MCP server: setup
Combines plain HTTP backends behind one OAuth 2.1 MCP endpoint with per-user permissions. Use it when separate connectors would create a fragmented tool surface.
claude mcp add --transport http cortex-gateway https://mcp.cortex-gateway.dev/mcpWhat cortex-gateway does
cortex-gateway is a self-hosted MCP gateway for several HTTP backends. It discovers their tools, builds one catalog, routes tools/call requests to the owning backend, and records a pseudonymized audit trail. OAuth 2.1 scopes and JWTs carry the caller’s identity through the gateway.
A backend can use a small HTTP JSON-RPC contract with POST /api/cortex/backend; it does not need an MCP library or stdio for that contract. Each backend keeps responsibility for authorization. A built-in MCP-to-backend adapter can place native MCP servers behind the gateway, though that adapter is marked beta.
An unreachable backend is removed from tools/list while the remaining services continue to work. The setup command connects to https://mcp.cortex-gateway.dev/mcp; a self-hosted deployment also needs OAuth and HTTP backends configured.
What it helps with
- combine several HTTP backends into one MCP catalog
- carry each user’s permissions to backend services
- protect agent tool calls with OAuth 2.1 scopes
- keep a shared pseudonymized call audit
- proxy a native MCP server through the adapter
Example prompts for the agent
- Show me the tools available through cortex-gateway.
- Find the right tool in the federated catalog and call it with my permissions.
- File a missing-capability report using
report_missing_capability.
How to install cortex-gateway
Platform CLI: remote server
claude mcp add --transport http cortex-gateway https://mcp.cortex-gateway.dev/mcpPlatform CLI: remote server
codex mcp add cortex-gateway --url https://mcp.cortex-gateway.dev/mcpConfig file
{
"mcpServers": {
"cortex-gateway": {
"url": "https://mcp.cortex-gateway.dev/mcp"
}
}
}Config file
{
"servers": {
"cortex-gateway": {
"type": "http",
"url": "https://mcp.cortex-gateway.dev/mcp"
}
}
}Platform CLI: remote server
gemini mcp add -t http cortex-gateway https://mcp.cortex-gateway.dev/mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about cortex-gateway
How do I install cortex-gateway in Claude Code?
Run claude mcp add --transport http cortex-gateway https://mcp.cortex-gateway.dev/mcp.
What does cortex-gateway do?
It presents tools from multiple HTTP backends through one MCP server, applies OAuth 2.1 access scopes, and routes each call to its owning backend.
What does a backend need to provide?
A backend must expose POST /api/cortex/backend. OAuth 2.1, JWTs, and scopes are used when access must follow the individual user.
