Skip to main content

Quickstart

This guide takes you from a registered external agent to a governed model request and MCP connection.

1. Prepare an agent and key​

In CortexHub:

  1. Register an external agent.
  2. Grant the capabilities it needs.
  3. Grant the agent access to the toolkits it should use.
  4. Open the agent's API keys page.
  5. Create a key and select the AI gateway and/or MCP gateway scope.
  6. Copy the key. The plaintext is shown once.

The key begins with cxh_key_. Store it in an environment variable or secret manager.

2. Install​

pip install "cortexhub[all]"

Use cortexhub[ai] for inference only or cortexhub[mcp] for MCP transport only.

3. Configure the key​

export CORTEXHUB_API_KEY="cxh_key_..."
from cortexhub import Cortexhub

cx = Cortexhub()

4. Create one session for a conversation​

Create one session for each conversation or autonomous run. Reuse that handle for all model and tool calls in the run.

conversation_id = "conversation-8472"
user_id = "user-193"

session = cx.session(
    agent="your-registered-agent-reference",
    mcp_session_id=conversation_id,
    end_user_subject=user_id,
)

The SDK requires agent for MCP connections. Use the reference or cxh_agent_* identifier for the registered agent.

mcp_session_id is your stable conversation or run identifier. end_user_subject is your stable opaque identifier for the person the agent is acting for. API-key requests must include an end-user subject.

5. Send a governed model request​

response = session.llm.responses.create(
    model="cortexhub/auto",
    input="Summarize the latest project updates in three bullets.",
)

print(response.output_text)

The API key must include the AI gateway scope.

6. Connect to governed MCP tools​

connection = session.mcp

print(connection.url)
print(connection.headers)

Pass connection.url and connection.headers to your MCP client or framework. Discover downstream tools with cortexhub_search_tools, load schemas with cortexhub_get_tool_schemas, and invoke them with cortexhub_invoke_tools.

The key must include the MCP gateway scope.

7. Use the official MCP client​

import asyncio

from cortexhub import Cortexhub
from mcp import ClientSession

cx = Cortexhub()

async def main() -> None:
    session = cx.session(
        agent="your-registered-agent-reference",
        mcp_session_id="conversation-8472",
        end_user_subject="user-193",
    )

    async with session.mcp.open() as (read, write):
        async with ClientSession(read, write) as mcp:
            await mcp.initialize()
            tools = await mcp.list_tools()
            for tool in tools.tools:
                print(tool.name)

asyncio.run(main())

The SDK supplies the authenticated connection. Your agent loop or framework decides when to call the exposed CortexHub tools.

Sessions and tasks​

Use the same mcp_session_id for every turn in one conversation. Use a different ID for each independent conversation or run.

Within a session, keep the same objective on every meta-tool call for one task:

cortexhub_search_tools(objective)
cortexhub_get_tool_schemas(objective, names)
cortexhub_invoke_tools(objective, calls)

If an invoke is held for approval, poll cortexhub_get_task with the returned task ID. The approval, tool call, and final result remain associated with the same session and objective.

Next steps​

:::tip Browser clients Claude, ChatGPT, and Cursor users connect through the interactive MCP flow. They do not need the Python SDK. :::