MCP SDK
Use the Python SDK when an agent runtime or backend calls CortexHub programmatically. It connects your runtime to two governed capabilities:
- the AI gateway for OpenAI-compatible model requests;
- the MCP gateway for governed tools, brain, and files.
The primary credential is an API key bound to one registered external agent. The key begins with cxh_key_ and is created after the agent has been given the capabilities and toolkit access it needs.
Quick start
- Register an external agent in CortexHub.
- Grant its capabilities and toolkit access.
- Create an API key for that agent and select the AI gateway, MCP gateway, or both scopes.
- Copy the key once and store it in your secret manager.
- Set CORTEXHUB_API_KEY in the runtime that runs your agent.
pip install "cortexhub[all]"
export CORTEXHUB_API_KEY="cxh_key_..."
Use one SDK session for each conversation or autonomous run:
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.",
)
print(reply.output_text)
mcp_session_id is your stable conversation or run identifier. end_user_subject is the stable opaque identifier for the person the agent is acting for. Reuse both for every turn in that conversation.
Other authentication
A server-side process can use a programmatic member credential with client_id and client_secret for MCP access. Browser-based Claude, ChatGPT, and Cursor connections use interactive OAuth and do not use this SDK.
Documentation
| Page | Contents |
|---|---|
| Quickstart | Register an agent, mint a key, run inference, and connect MCP |
| Installation | Requirements, extras, and environment variables |
| Authentication | Agent API keys, scopes, and programmatic OAuth |
| Connect | MCP connection objects and transports |
| Sessions & attribution | Conversation IDs, end-user subjects, objectives, and grouping |
| LLM router | OpenAI-compatible inference |
| Meta-tools | Search, schema, invoke, and approval/task polling |
| Outcomes | Invoke statuses and MCP errors |
| Framework examples | OpenAI Agents, LangChain, and other runtimes |
| Python API reference | Client, sessions, and connection objects |
| Errors | Exception types |
TypeScript
TypeScript is planned. Until it ships, use the Python SDK or connect with the MCP protocol described in Connect.