Metadata-Version: 2.4
Name: cortexhub
Version: 2.0.5
Summary: MCP gateway client for CortexHub programmatic agent access.
Project-URL: Homepage, https://cortexhub.ai
Project-URL: Documentation, https://docs.cortexhub.ai
Author-email: CortexHub <hello@cortexhub.ai>
License: MIT
License-File: LICENSE
Keywords: agents,ai,governance,mcp,programmatic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# cortexhub

Official Python client for the **CortexHub MCP gateway**.

This package builds the URL and headers your MCP transport needs to call
`https://mcp.cortexhub.ai/v1/mcp`. It does not call the CortexHub
Platform API; for organisation and workspace management, see the
[Platform API reference](https://docs.cortexhub.ai/docs/rest-api/overview).

[Documentation](https://docs.cortexhub.ai/docs/sdks/overview)

## Install

```bash
pip install cortexhub
```

## Two ways to authenticate

The SDK supports both gateway authentication paths through one entry
point. Pick the one that matches how your application identifies users.

### Workspace MCP API key (recommended for backends)

Use this when your application has its own users who do not have
CortexHub accounts. The workspace key authenticates the gateway; the
end-user identity is attested per call.

Mint the key from **Workspace settings → MCP API keys** in the
CortexHub dashboard, or programmatically via the Platform API.

```python
from cortexhub import Cortexhub

cx = Cortexhub(api_key="cxh_mcpk_<id>_<secret>")
session = cx.session(
    agent="invoice-bot",
    end_user_subject="user_42",          # required for end-user accountability policies
    end_user_display_hint="Alice",       # optional, render-only, never persisted
    invocation_mode="autonomous",        # default; pass "interactive" if a human is present
)
# session.mcp.url and session.mcp.headers → pass to your MCP transport
```

### MCP OAuth client

Use this when your application signs in CortexHub users interactively.
Create the OAuth client from **Account settings → MCP OAuth clients** and
copy the `client_id` and `client_secret`.

```python
from cortexhub import Cortexhub

cx = Cortexhub(client_id="...", client_secret="...")
session = cx.session(
    agent="helpdesk-bot",
    mcp_session_id="chat-42",                    # optional: groups activity per session
    conversation_title="Engineering standup",    # optional: context shown in audit
    last_user_message="Create a standup page",   # optional: context shown in audit
)
```

## Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `CORTEXHUB_URL` | `https://mcp.cortexhub.ai` | MCP gateway base URL |
| `CORTEXHUB_API_KEY` | — | Workspace MCP API key (`cxh_mcpk_*`) |
| `CORTEXHUB_CLIENT_ID` | — | MCP OAuth client id |
| `CORTEXHUB_CLIENT_SECRET` | — | MCP OAuth client secret |

If both `CORTEXHUB_API_KEY` and OAuth credentials are configured, the
API key wins.

## What the SDK returns

In both modes, `session.mcp.url` and `session.mcp.headers` are ready to
wire into the MCP transport of your choice (the official MCP Python SDK,
a custom HTTP client, anything that accepts URL + headers).

## License

MIT.
