Skip to main content

Agent API key

An agent API key lets an external agent connect to CortexHub's governed MCP gateway. The key is bound to one registered external agent. Its capabilities, toolkit grants, policies, and selected scopes determine what the agent can do.

Use this path when your agent runs in your own application and you want CortexHub to govern its tool calls.

Create a key​

In CortexHub:

  1. Register an external agent.
  2. Grant its capabilities.
  3. Grant access to the toolkits it should use.
  4. Open the agent's API keys page.
  5. Create a key and select the MCP gateway scope.
  6. Copy the plaintext key when it is shown.

The key begins with cxh_key_ and is shown only once. Store it in an environment variable or secret manager.

Request headers​

Every MCP request from an API-key client includes:

| Header | Required | Value | |---|---|---|---| | X-CortexHub-Key | Yes | The full agent API key | | X-CortexHub-Agent | Yes in the SDK | The registered agent reference | | X-CortexHub-End-User-Subject | Yes | A stable opaque identifier for the person the agent acts for | | X-CortexHub-End-User-Display-Hint | Optional | Short text shown on consent surfaces |

The end-user subject is not a CortexHub login. Use an identifier from your own user system and keep it stable for that user. Do not put unnecessary personal data in it.

The display hint is presentation metadata only. It is not used for identity or authorization.

Raw request​

curl -sS https://mcp.cortexhub.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-CortexHub-Key: $CORTEXHUB_API_KEY" \
  -H "X-CortexHub-Agent: your-agent-reference" \
  -H "X-CortexHub-End-User-Subject: user-193" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "cortexhub_search_tools",
      "arguments": {
        "objective": "Resolve the customer billing issue",
        "query": "billing invoice",
        "limit": 5
      }
    }
  }'

Discover tools with cortexhub_search_tools, load schemas with cortexhub_get_tool_schemas, and invoke them with cortexhub_invoke_tools. Do not call provider tool names directly.

Python SDK​

from cortexhub import Cortexhub

cx = Cortexhub(api_key="cxh_key_...")
session = cx.session(
    agent="your-registered-agent-reference",
    mcp_session_id="conversation-8472",
    end_user_subject="user-193",
)

connection = session.mcp
# connection.url
# connection.headers

Pass connection.url and connection.headers to your MCP client. See the Python SDK quickstart.

Approvals​

A governed invoke can return an MCP task when approval is required. Poll cortexhub_get_task with the task ID until it is terminal. Keep the same connection, session ID, and objective while waiting.

Key lifecycle​

Create and rotate keys through the CortexHub interface or supported API. Store the plaintext secret when it is returned; it is not shown again. Revoke a key to stop it immediately.

See also​