cortexhub 1.1.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

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://mcp.cortexhub.ai/v1/mcp
print(session.mcp.headers)    # {"X-API-Key": "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)

Add just the gateway URL — these clients bootstrap OAuth automatically. See docs.cortexhub.ai/frameworks/desktop-cursor.

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://mcp.cortexhub.ai/v1/mcp. There is no self-hosted mode and no base-URL override.

Attributing tool calls to a user

Every MCP request the gateway sees is attributed to one end-user — the person on whose behalf the agent is acting. Two ways to do this:

From this SDK

cortexhub.create(user_id="…") puts the value into the X-Cortexhub-End-User-Subject header automatically. That's it — every tool call from the resulting session is now attributed to that user in the audit log and uses their per-end-user OAuth tokens for any toolkit that needs them.

session = cortexhub.create(user_id="user_123")
# session.mcp.headers ==
#   {"X-API-Key": "ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}

From any other MCP client (no SDK)

Add the header directly on every MCP request:

X-Cortexhub-End-User-Subject: user_123

E.g. with curl:

curl -N "https://mcp.cortexhub.ai/v1/mcp" \
  -H "x-api-key: $CORTEXHUB_API_KEY" \
  -H "X-Cortexhub-End-User-Subject: user_123" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

When you omit the header, the gateway falls back to mcp_session:<session_id> — every distinct MCP connection becomes its own anonymous "user". Fine for personal Claude Desktop / Cursor use; not what you want for a multi-tenant app.

What user_id is for

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
• Scope per-end-user rate limits

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

What runs where

Concern	Where it runs
Authentication, session construction	This SDK (local, fully offline)
Tool discovery, tool execution	cortexhub MCP gateway → toolkits you've attached
Per-end-user OAuth resolution	cortexhub MCP gateway
Per-tool policies + HITL approvals	cortexhub MCP gateway
Audit log of every tool call	cortexhub MCP gateway

The SDK itself is a thin wrapper around two strings (URL + headers). Everything else is server-side.

License

MIT.