cortexhub 1.0.1

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 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
Policies, budget caps, approvals	cortexhub MCP gateway
Per-end-user OAuth resolution	cortexhub MCP gateway
Audit log, telemetry	cortexhub MCP gateway
Safety guardrails (PII, secrets, prompt injection)	cortexhub MCP gateway

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

License

MIT.