Skip to main content

MCP Gateway API Reference

Base URL: https://mcp.cortexhub.ai

The MCP gateway is the runtime data plane. It exposes:

  • Tool invocation over the Model Context Protocol (POST /v1/mcp).
  • Authentication endpoints for OAuth and for org MCP gateway key validation.
  • Discovery documents for OAuth client integrations.

Organization management lives on a separate surface, the Platform API.

Choosing how to authenticate​

The gateway accepts two credential types. They suit different integrations:

CredentialWhen to useHeader
Org MCP gateway keyYour backend acts on behalf of users who do not have CortexHub accounts. You attest the end-user identity on every call.X-CortexHub-Key: cxh_mcpk_…
MCP OAuth bearerAn MCP client (Claude, Cursor, ChatGPT, a custom client) authenticates an interactive user who completes a browser OAuth flow.Authorization: Bearer <access_token>

Pick one path per integration. Both routes hit the same gateway and the same governance pipeline.

Org MCP gateway key (programmatic)​

Create the key from the organization settings in the dashboard or via the Platform API. On every gateway call, send:

X-CortexHub-Key: cxh_mcpk_<id>_<secret>
X-CortexHub-Agent: <agent ref or cxh_agent_* id>
X-CortexHub-End-User-Subject: <opaque caller-side user id>   # required on every org-key call

Full guide and lifecycle details: Org MCP gateway key.

MCP OAuth bearer (interactive clients)​

Interactive MCP clients use the OAuth Authorization Code grant with PKCE (RFC 6749 and RFC 7636). The discovery and token-exchange endpoints documented in this reference let an MCP client register, send the user through an authorisation flow, and exchange the resulting code for an access token. From then on:

Authorization: Bearer <access_token>

This is the path used by Claude, Cursor, ChatGPT, and other interactive MCP clients. The Python SDK's programmatic member path uses client_credentials instead; see Choose your authentication model.

Dynamic client registration accepts:

  • https:// callbacks for web MCP hosts (for example https://claude.ai/api/mcp/auth_callback)
  • http://127.0.0.1 / http://localhost loopback callbacks for native CLI clients (RFC 8252)
  • cursor://anysphere.cursor-mcp/oauth/callback for the Cursor desktop MCP OAuth flow

Tool invocation: POST /v1/mcp​

Tool invocation uses JSON-RPC over POST /v1/mcp, not REST, because it follows the Model Context Protocol.

MethodPurpose
initializeProtocol handshake. Advertises tools, prompts, resources, and MCP Tasks capabilities.
tools/listLists the cortexhub_* meta-tools exposed by the gateway.
tools/callInvokes a meta-tool. Calls that need end-user consent surface it via cortexhub_request_consent; calls that require a toolkit connect surface a connect_required.portal_url.
tasks/get, tasks/result, tasks/list, tasks/cancel, tasks/updateMCP Tasks. A call held for approval parks as a task; task-capable hosts drive it at the transport layer, while every agent can poll the same gate through cortexhub_get_task.
resources/readReads the CortexHub consent card resource (ui://cortexhub/consent) when the host MCP client renders it.
pingLiveness check.

Downstream tool names are discovered at runtime via the meta-tool cortexhub_search_tools, then invoked through cortexhub_invoke_tools; real downstream tools are never listed by tools/list. The MCP JSON-RPC surface is not in this OpenAPI document because JSON-RPC is not REST; the methods above are the protocol contract.

What this reference covers​

  • OAuth endpoints: client registration, authorise, token, introspect, revoke.
  • Discovery documents: /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource, and the JWKS used to verify access tokens.

See also​