cortexhub 2.0.5

MCP gateway client for CortexHub programmatic agent access.

cortexhub

Official Python client for the CortexHub MCP gateway.

This package builds the URL and headers your MCP transport needs to call https://mcp.cortexhub.ai/v1/mcp. It does not call the CortexHub Platform API; for organisation and workspace management, see the Platform API reference.

Documentation

Install

pip install cortexhub

Two ways to authenticate

The SDK supports both gateway authentication paths through one entry point. Pick the one that matches how your application identifies users.

Workspace MCP API key (recommended for backends)

Use this when your application has its own users who do not have CortexHub accounts. The workspace key authenticates the gateway; the end-user identity is attested per call.

Mint the key from Workspace settings → MCP API keys in the CortexHub dashboard, or programmatically via the Platform API.

from cortexhub import Cortexhub

cx = Cortexhub(api_key="cxh_mcpk_<id>_<secret>")
session = cx.session(
    agent="invoice-bot",
    end_user_subject="user_42",          # required for end-user accountability policies
    end_user_display_hint="Alice",       # optional, render-only, never persisted
    invocation_mode="autonomous",        # default; pass "interactive" if a human is present
)
# session.mcp.url and session.mcp.headers → pass to your MCP transport

MCP OAuth client

Use this when your application signs in CortexHub users interactively. Create the OAuth client from Account settings → MCP OAuth clients and copy the client_id and client_secret.

from cortexhub import Cortexhub

cx = Cortexhub(client_id="...", client_secret="...")
session = cx.session(
    agent="helpdesk-bot",
    mcp_session_id="chat-42",                    # optional: groups activity per session
    conversation_title="Engineering standup",    # optional: context shown in audit
    last_user_message="Create a standup page",   # optional: context shown in audit
)

Environment variables

Variable	Default	Purpose
CORTEXHUB_URL	https://mcp.cortexhub.ai	MCP gateway base URL
CORTEXHUB_API_KEY	—	Workspace MCP API key (cxh_mcpk_*)
CORTEXHUB_CLIENT_ID	—	MCP OAuth client id
CORTEXHUB_CLIENT_SECRET	—	MCP OAuth client secret

If both CORTEXHUB_API_KEY and OAuth credentials are configured, the API key wins.

What the SDK returns

In both modes, session.mcp.url and session.mcp.headers are ready to wire into the MCP transport of your choice (the official MCP Python SDK, a custom HTTP client, anything that accepts URL + headers).

License

MIT.