Authentication
| Credential | Use | SDK entry point |
|---|---|---|
| Agent API key cxh_key_ with ai scope | Model requests for one registered external agent | session.llm |
| Agent API key cxh_key_ with mcp scope | Governed tools, brain, and files | session.mcp or cx.mcp |
| Agent API key with both scopes | Inference and MCP tools in one run | cx.session |
| Programmatic member credential | Server-side MCP access as a CortexHub member | client_id + client_secret |
| Interactive member OAuth | Claude, ChatGPT, Cursor, and browser MCP clients | Separate browser flow |
Agent API key
This is the recommended path for an agent runtime that you operate.
In CortexHub:
- Register an external agent.
- Grant its capabilities.
- Grant the toolkits it may use.
- Create an API key for that agent.
- Select the AI gateway and/or MCP gateway scope.
- Save the plaintext key when it is shown.
The key begins with cxh_key_ and is bound to one registered agent. The selected scopes cannot exceed the capabilities granted to that agent.
export CORTEXHUB_API_KEY="cxh_key_..."
from cortexhub import Cortexhub
cx = Cortexhub()
session = cx.session(
agent="your-registered-agent-reference",
mcp_session_id="conversation-8472",
end_user_subject="user-193",
)
reply = session.llm.responses.create(
model="cortexhub/auto",
input="Summarize the latest project updates.",
)
For MCP, the SDK requires agent and sends the registered agent reference with the connection:
connection = cx.mcp(
agent="your-registered-agent-reference",
end_user_subject="user-193",
)
end_user_subject is required for API-key requests. Use a stable opaque identifier from your own user system. It identifies the person the agent acts for and does not need to be an email address.
end_user_display_hint is optional presentation text for consent surfaces. It is not an identity or authorization input.
Programmatic member credential
Use this when a server-side process should act as a CortexHub member over MCP.
export CORTEXHUB_CLIENT_ID="your-client-id"
export CORTEXHUB_CLIENT_SECRET="your-client-secret"
The SDK obtains an access token with the OAuth client_credentials grant:
from cortexhub import Cortexhub
cx = Cortexhub()
session = cx.session(
agent="your-agent-reference",
mcp_session_id="conversation-8472",
)
This path is for MCP access. It does not provide cx.ai or cx.llm.
Interactive member OAuth
Claude, ChatGPT, Cursor, and other browser-based MCP clients use interactive Authorization Code + PKCE. That flow is documented separately in Authentication concepts. It is not the client_credentials flow used by the Python SDK.
Choosing between credentials
Use an agent API key when your runtime owns the agent identity and you want model requests, MCP calls, or both. Use a programmatic member credential when the runtime should act as a CortexHub member over MCP.