Skip to main content

Framework examples

OpenAI Agents SDKLangChainLangGraphAnthropic APIVercel AI SDKCrewAIMastraPython SDK

All examples build the session through the same SDK entry point. Use whichever credential path fits your application:

from cortexhub import Cortexhub

# Agent API key (bound to a registered external agent)
session = Cortexhub(api_key="cxh_key_…").session(
    agent="your-registered-agent-reference",
    mcp_session_id="conversation-8472",
    end_user_subject="user-193",
)

# or programmatic Member Credential (your server acts as the member bound to the client)
session = Cortexhub(client_id="…", client_secret="…").session(agent="helpdesk-bot")

# session.mcp.url  → https://mcp.cortexhub.ai/v1/mcp
# session.mcp.headers → the credential, agent, and any attribution headers

For the OAuth path, create a programmatic member credential in CortexHub and set CORTEXHUB_CLIENT_ID and CORTEXHUB_CLIENT_SECRET. For the agent-key path, set CORTEXHUB_API_KEY. See Authentication for both. The examples below read credentials from the environment.

For per-chat attribution in Cloud, merge Mcp-Session-Id into headers (see Sessions & attribution).

Agent instructions (all frameworks):

Use CortexHub for external actions: search_tools → get_tool_schemas → invoke_tools.
Use tool_name from search results; put required fields inside calls[].arguments.
Never call downstream tool names on tools/call directly.

OpenAI Agents SDK​

import os
from cortexhub import Cortexhub
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

session = Cortexhub().session(agent=os.environ["CORTEXHUB_AGENT_REF"], end_user_subject=os.environ["CORTEXHUB_END_USER_SUBJECT"])

mcp = MCPServerStreamableHttp(
    name="cortexhub",
    url=session.mcp.url,
    headers=session.mcp.headers,
)

agent = Agent(
    name="assistant",
    instructions=(
        "External actions go through CortexHub meta-tools only. "
        "Handle policy_denied, awaiting_user_consent, and awaiting_operator_approval as normal outcomes."
    ),
    mcp_servers=[mcp],
)

result = Runner.run_sync(agent, "Summarize open approvals for my team")
print(result.final_output)

Adjust imports to match your installed openai-agents / agents package version.

LangChain​

Wrap meta-tool RPCs or use an MCP adapter when your LangChain version supports streamable HTTP MCP. Minimal pattern with httpx:

import httpx
from cortexhub import Cortexhub

session = Cortexhub().session(agent="your-registered-agent-reference", end_user_subject="user-193")
headers = {
    **session.mcp.headers,
    "Accept": "application/json, text/event-stream",
}


def mcp_call(name: str, arguments: dict) -> dict:
    r = httpx.post(
        session.mcp.url,
        headers=headers,
        json={
            "jsonrpc": "2.0",
            "id": name,
            "method": "tools/call",
            "params": {"name": name, "arguments": arguments},
        },
        timeout=120,
    )
    r.raise_for_status()
    body = r.json()
    if "error" in body:
        raise RuntimeError(body["error"])
    return body.get("result") or {}


# Example: search → schemas → invoke (see meta-tools.md).
# objective is the member's overall goal, required on every cortexhub_* call and
# kept identical for the whole task (it groups the task into one trace).
objective = "Post the launch update to the team Slack channel"
search = mcp_call(
    "cortexhub_search_tools",
    {"objective": objective, "query": "post slack message", "limit": 5},
)
names = [r["tool_name"] for r in search["results"]]
schemas = mcp_call("cortexhub_get_tool_schemas", {"objective": objective, "names": names})

Register StructuredTool wrappers around mcp_call if you are not using native MCP tool discovery.

Anthropic / Claude API (MCP connector)​

When your runtime supports remote MCP with custom headers, pass session.mcp into the connector config your SDK expects. The interactive path for Claude.ai in the browser uses end-user OAuth instead; this section is for your Python backend calling Claude with CortexHub as a remote MCP server.

from cortexhub import Cortexhub

session = Cortexhub().session(agent="your-registered-agent-reference", end_user_subject="user-193")
mcp_server = {
    "type": "url",
    "url": session.mcp.url,
    "name": "cortexhub",
    "headers": session.mcp.headers,
}
# Attach mcp_server to the Messages API tools/mcp field per Anthropic docs for your SDK version.

Vercel AI SDK (TypeScript)​

Use the same MCP URL and headers from a server action or route. Obtain the Bearer token with client_credentials at https://mcp.cortexhub.ai/v1/mcp/oauth/token, or call a small Python helper that returns session.mcp.headers. This is the programmatic member path; browser clients use Authorization Code + PKCE.

const MCP_URL = "https://mcp.cortexhub.ai/v1/mcp";

function mcpHeaders(accessToken: string, agentRef: string): Record<string, string> {
  return {
    Authorization: `Bearer ${accessToken}`,
    "X-CortexHub-Agent": agentRef,
    "Content-Type": "application/json",
    Accept: "application/json, text/event-stream",
  };
}

async function cortexhubRpc(
  accessToken: string,
  agentRef: string,
  toolName: string,
  args: Record<string, unknown>,
) {
  const res = await fetch(MCP_URL, {
    method: "POST",
    headers: mcpHeaders(accessToken, agentRef),
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: toolName,
      method: "tools/call",
      params: { name: toolName, arguments: args },
    }),
  });
  if (!res.ok) throw new Error(`MCP ${res.status}`);
  return res.json();
}

LangGraph / CrewAI / Mastra​

Same pattern: configure the framework remote MCP client with session.mcp.url and session.mcp.headers. Prefer the framework native MCP integration when available; otherwise POST JSON-RPC tools/call as in the LangChain example.

FrameworkTypical integration
LangGraphRemote MCP server config on the graph agent node
CrewAIMCP tool source URL + headers on the crew agent
MastraMCPServer with url + headers from session.mcp

See also​