cortexhub 1.0.0

MCP gateway client for cortexhub agents — authenticate, hand the MCP URL to your framework of choice, done.

cortexhub

MCP gateway client for cortexhub agents. Authenticate, hand the MCP URL to your framework of choice, done.

Documentation · Examples

Install

pip install cortexhub

Quickstart

from cortexhub import Cortexhub

cortexhub = Cortexhub()                       # reads CORTEXHUB_API_KEY
session = cortexhub.create(user_id="user_123")

print(session.mcp.url)        # https://api.cortexhub.ai/v1/mcp-http
print(session.mcp.headers)    # {"Authorization": "Bearer ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}

Get an API key by registering an agent at app.cortexhub.ai.

Use it with your framework

The SDK only hands you an MCP URL + headers. Plug them into whichever framework you use.

Claude Agent SDK

from cortexhub import Cortexhub
from claude_agent_sdk import ClaudeAgentOptions

cortexhub = Cortexhub()
session = cortexhub.create(user_id="user_123")

options = ClaudeAgentOptions(
    mcp_servers={
        "cortexhub": {
            "type": "http",
            "url": session.mcp.url,
            "headers": session.mcp.headers,
        },
    },
)

OpenAI Agents SDK

from cortexhub import Cortexhub
from agents import Agent, HostedMCPTool

cortexhub = Cortexhub()
session = cortexhub.create(user_id="user_123")

agent = Agent(
    name="Assistant",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "cortexhub",
                "server_url": session.mcp.url,
                "headers": session.mcp.headers,
                "require_approval": "never",
            }
        )
    ],
)

Vercel AI SDK (TypeScript)

import { Cortexhub } from "@cortexhub/core";          // see @cortexhub/core (TS)
import { createMCPClient } from "@ai-sdk/mcp";

const cortexhub = new Cortexhub();
const session = await cortexhub.create("user_123");

const client = await createMCPClient({
  transport: {
    type: "http",
    url: session.mcp.url,
    headers: session.mcp.headers,
  },
});
const tools = await client.tools();

LangGraph (raw MCP)

Use the standard MCP client; pass the URL + headers from the session.

from cortexhub import Cortexhub
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

cortexhub = Cortexhub()
session = cortexhub.create(user_id="user_123")

async with streamablehttp_client(session.mcp.url, headers=session.mcp.headers) as (read, write, _):
    async with ClientSession(read, write) as mcp:
        await mcp.initialize()
        tools = await mcp.list_tools()

Claude Desktop / Cursor / ChatGPT (no SDK)

Drop the URL + headers into the client's MCP server config — see docs.cortexhub.ai/mcp-gateway/clients.

Configuration

The SDK reads exactly one environment variable:

Variable	Purpose
CORTEXHUB_API_KEY	Per-agent API key (ch_live_…)

Or pass it explicitly:

cortexhub = Cortexhub(api_key="ch_live_…")

The MCP gateway URL is fixed — https://api.cortexhub.ai/v1/mcp-http. There is no self-hosted mode and no base-URL override.

How user_id works

user_id is opaque to cortexhub — pass whatever stable identifier your application uses for the human (DB id, email hash, Auth0 sub, …). Cortexhub uses it to:

• Route per-end-user OAuth tokens (when the toolkit needs them)
• Attribute every tool call to that user in the audit log
• Evaluate per-user budget caps and rate limits

Calling create() with the same user_id twice is a no-op — the session is fully local and cheap to construct.

What this SDK doesn't do

The cortexhub MCP gateway is the source of truth for governance. The SDK has no:

• Decorators (no @cx.tool — the gateway discovers tools from your registered toolkits)
• Local Policy evaluation
• Local PII / secret / prompt-injection scanning
• Local span recording / OTLP export

All of that runs server-side at the gateway when the agent calls a tool through the URL above. The SDK is a thin wrapper around two strings (URL + headers).

Migrating from cortexhub 0.5.x

The v1 SDK is a complete rewrite. The decorator surface (@cx.tool, cx.session, cx.run, cx.llm_call, cx.enforce, …) is gone. If you used 0.5.x:

1. Remove cortexhub.init() calls.
2. Remove @cx.tool decorators — your tools come from cortexhub toolkits configured in the dashboard.
3. Replace the function-call orchestration with an MCP-aware framework (Claude Agent SDK, OpenAI Agents, Vercel AI SDK, LangGraph, …).
4. Use the snippets above to wire the MCP gateway into the framework.

License

MIT.