cortexhub 1.0.2__tar.gz → 1.0.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cortexhub
3
- Version: 1.0.2
3
+ Version: 1.0.3
4
4
  Summary: MCP gateway client for cortexhub agents — authenticate, hand the MCP URL to your framework of choice, done.
5
5
  Project-URL: Homepage, https://cortexhub.ai
6
6
  Project-URL: Documentation, https://docs.cortexhub.ai
@@ -25,8 +25,7 @@ Description-Content-Type: text/markdown
25
25
 
26
26
  MCP gateway client for cortexhub agents. Authenticate, hand the MCP URL to your framework of choice, done.
27
27
 
28
- [Documentation](https://docs.cortexhub.ai) · [Examples](https://github.com/CortexHub-AI/examples)
29
-
28
+ [Documentation](https://docs.cortexhub.ai)
30
29
  ## Install
31
30
 
32
31
  ```bash
@@ -41,8 +40,8 @@ from cortexhub import Cortexhub
41
40
  cortexhub = Cortexhub() # reads CORTEXHUB_API_KEY
42
41
  session = cortexhub.create(user_id="user_123")
43
42
 
44
- print(session.mcp.url) # https://api.cortexhub.ai/v1/mcp-http
45
- print(session.mcp.headers) # {"Authorization": "Bearer ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}
43
+ print(session.mcp.url) # https://api.cortexhub.ai/v1/mcp
44
+ print(session.mcp.headers) # {"X-API-Key": "ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}
46
45
  ```
47
46
 
48
47
  Get an API key by registering an agent at [app.cortexhub.ai](https://app.cortexhub.ai).
@@ -135,7 +134,7 @@ async with streamablehttp_client(session.mcp.url, headers=session.mcp.headers) a
135
134
 
136
135
  ### Claude Desktop / Cursor / ChatGPT (no SDK)
137
136
 
138
- Drop the URL + headers into the client's MCP server config — see [docs.cortexhub.ai/mcp-gateway/clients](https://docs.cortexhub.ai/mcp-gateway/clients).
137
+ Add just the gateway URL — these clients bootstrap OAuth automatically. See [docs.cortexhub.ai/frameworks/desktop-cursor](https://docs.cortexhub.ai/frameworks/desktop-cursor).
139
138
 
140
139
  ## Configuration
141
140
 
@@ -151,14 +150,49 @@ Or pass it explicitly:
151
150
  cortexhub = Cortexhub(api_key="ch_live_…")
152
151
  ```
153
152
 
154
- The MCP gateway URL is fixed — `https://api.cortexhub.ai/v1/mcp-http`. There is no self-hosted mode and no base-URL override.
153
+ The MCP gateway URL is fixed — `https://api.cortexhub.ai/v1/mcp`. There is no self-hosted mode and no base-URL override.
154
+
155
+ ## Attributing tool calls to a user
156
+
157
+ 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:
158
+
159
+ ### From this SDK
160
+
161
+ `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.
162
+
163
+ ```python
164
+ session = cortexhub.create(user_id="user_123")
165
+ # session.mcp.headers ==
166
+ # {"X-API-Key": "ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}
167
+ ```
168
+
169
+ ### From any other MCP client (no SDK)
170
+
171
+ Add the header directly on every MCP request:
172
+
173
+ ```
174
+ X-Cortexhub-End-User-Subject: user_123
175
+ ```
176
+
177
+ E.g. with curl:
178
+
179
+ ```bash
180
+ curl -N "https://api.cortexhub.ai/v1/mcp" \
181
+ -H "x-api-key: $CORTEXHUB_API_KEY" \
182
+ -H "X-Cortexhub-End-User-Subject: user_123" \
183
+ -H "Content-Type: application/json" \
184
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
185
+ ```
186
+
187
+ 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.
155
188
 
156
- ## How `user_id` works
189
+ ### What `user_id` is for
157
190
 
158
191
  `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:
159
192
 
160
193
  - Route per-end-user OAuth tokens (when the toolkit needs them)
161
194
  - Attribute every tool call to that user in the audit log
195
+ - Scope per-end-user rate limits
162
196
 
163
197
  Calling `create()` with the same `user_id` twice is a no-op — the session is fully local and cheap to construct.
164
198
 
@@ -2,8 +2,7 @@
2
2
 
3
3
  MCP gateway client for cortexhub agents. Authenticate, hand the MCP URL to your framework of choice, done.
4
4
 
5
- [Documentation](https://docs.cortexhub.ai) · [Examples](https://github.com/CortexHub-AI/examples)
6
-
5
+ [Documentation](https://docs.cortexhub.ai)
7
6
  ## Install
8
7
 
9
8
  ```bash
@@ -18,8 +17,8 @@ from cortexhub import Cortexhub
18
17
  cortexhub = Cortexhub() # reads CORTEXHUB_API_KEY
19
18
  session = cortexhub.create(user_id="user_123")
20
19
 
21
- print(session.mcp.url) # https://api.cortexhub.ai/v1/mcp-http
22
- print(session.mcp.headers) # {"Authorization": "Bearer ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}
20
+ print(session.mcp.url) # https://api.cortexhub.ai/v1/mcp
21
+ print(session.mcp.headers) # {"X-API-Key": "ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}
23
22
  ```
24
23
 
25
24
  Get an API key by registering an agent at [app.cortexhub.ai](https://app.cortexhub.ai).
@@ -112,7 +111,7 @@ async with streamablehttp_client(session.mcp.url, headers=session.mcp.headers) a
112
111
 
113
112
  ### Claude Desktop / Cursor / ChatGPT (no SDK)
114
113
 
115
- Drop the URL + headers into the client's MCP server config — see [docs.cortexhub.ai/mcp-gateway/clients](https://docs.cortexhub.ai/mcp-gateway/clients).
114
+ Add just the gateway URL — these clients bootstrap OAuth automatically. See [docs.cortexhub.ai/frameworks/desktop-cursor](https://docs.cortexhub.ai/frameworks/desktop-cursor).
116
115
 
117
116
  ## Configuration
118
117
 
@@ -128,14 +127,49 @@ Or pass it explicitly:
128
127
  cortexhub = Cortexhub(api_key="ch_live_…")
129
128
  ```
130
129
 
131
- The MCP gateway URL is fixed — `https://api.cortexhub.ai/v1/mcp-http`. There is no self-hosted mode and no base-URL override.
130
+ The MCP gateway URL is fixed — `https://api.cortexhub.ai/v1/mcp`. There is no self-hosted mode and no base-URL override.
131
+
132
+ ## Attributing tool calls to a user
133
+
134
+ 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:
135
+
136
+ ### From this SDK
137
+
138
+ `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.
139
+
140
+ ```python
141
+ session = cortexhub.create(user_id="user_123")
142
+ # session.mcp.headers ==
143
+ # {"X-API-Key": "ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}
144
+ ```
145
+
146
+ ### From any other MCP client (no SDK)
147
+
148
+ Add the header directly on every MCP request:
149
+
150
+ ```
151
+ X-Cortexhub-End-User-Subject: user_123
152
+ ```
153
+
154
+ E.g. with curl:
155
+
156
+ ```bash
157
+ curl -N "https://api.cortexhub.ai/v1/mcp" \
158
+ -H "x-api-key: $CORTEXHUB_API_KEY" \
159
+ -H "X-Cortexhub-End-User-Subject: user_123" \
160
+ -H "Content-Type: application/json" \
161
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
162
+ ```
163
+
164
+ 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.
132
165
 
133
- ## How `user_id` works
166
+ ### What `user_id` is for
134
167
 
135
168
  `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:
136
169
 
137
170
  - Route per-end-user OAuth tokens (when the toolkit needs them)
138
171
  - Attribute every tool call to that user in the audit log
172
+ - Scope per-end-user rate limits
139
173
 
140
174
  Calling `create()` with the same `user_id` twice is a no-op — the session is fully local and cheap to construct.
141
175
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "cortexhub"
3
- version = "1.0.2"
3
+ version = "1.0.3"
4
4
  description = "MCP gateway client for cortexhub agents — authenticate, hand the MCP URL to your framework of choice, done."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
@@ -30,7 +30,7 @@ from .errors import (
30
30
  )
31
31
  from .session import Session, SessionMcp
32
32
 
33
- __version__ = "1.0.1"
33
+ __version__ = "1.0.3"
34
34
  __all__ = [
35
35
  "Cortexhub",
36
36
  "Session",
@@ -5,11 +5,19 @@ and exposes ``session.mcp.url`` + ``session.mcp.headers`` which the caller
5
5
  hands to their framework's MCP client.
6
6
 
7
7
  Construction is fully local — no network call. The cortexhub MCP gateway
8
- authenticates each tool call by reading the ``Authorization`` header (the
9
- agent's API key) and the ``X-Cortexhub-End-User-Subject`` header (the
10
- end-user the session is bound to). Per-end-user OAuth state, per-agent
11
- budget caps, Policy decisions, and HITL approvals are all resolved
12
- server-side at the gateway — the SDK has no governance code.
8
+ authenticates each tool call by reading two headers:
9
+
10
+ * ``X-API-Key`` — the agent's raw API key (``ch_live_…`` /``ch_test_…``).
11
+ * ``X-Cortexhub-End-User-Subject`` — the end-user the session is bound to.
12
+
13
+ Per-end-user OAuth state, Policy decisions, and HITL approvals are all
14
+ resolved server-side at the gateway — the SDK has no governance code.
15
+
16
+ We deliberately do NOT use ``Authorization: Bearer …`` for the raw agent
17
+ key, even though MCP convention favours Bearer. The Bearer slot at the
18
+ gateway is reserved for short-lived MCP OAuth JWTs (issued via
19
+ ``/v1/oauth/mcp/token``) used by browser-based MCP clients like Claude.ai
20
+ and Cursor — mixing raw keys into Bearer would muddle that contract.
13
21
  """
14
22
 
15
23
  from __future__ import annotations
@@ -18,11 +26,12 @@ from dataclasses import dataclass, field
18
26
 
19
27
  # Hosted gateway URL. Hard-coded — the SDK does not support self-hosted
20
28
  # deployments, so there is no override to thread through.
21
- _MCP_URL = "https://api.cortexhub.ai/v1/mcp-http"
29
+ _MCP_URL = "https://api.cortexhub.ai/v1/mcp"
22
30
 
23
- # Header the gateway reads to bind a session to a specific end-user. Mirrors
24
- # the convention used elsewhere in cortexhub (``X-Cortexhub-...``); kept in
25
- # one place so a future rename only needs to touch this module.
31
+ # Headers the gateway reads. Both are namespaced ``X-Cortexhub-…`` /
32
+ # ``X-API-Key`` so they don't clash with framework-injected Bearer tokens
33
+ # (e.g. when the user's framework also speaks OAuth to other backends).
34
+ _API_KEY_HEADER = "X-API-Key"
26
35
  _END_USER_SUBJECT_HEADER = "X-Cortexhub-End-User-Subject"
27
36
 
28
37
 
@@ -60,7 +69,7 @@ class Session:
60
69
  self.mcp: SessionMcp = SessionMcp(
61
70
  url=_MCP_URL,
62
71
  headers={
63
- "Authorization": f"Bearer {api_key}",
72
+ _API_KEY_HEADER: api_key,
64
73
  _END_USER_SUBJECT_HEADER: user_id,
65
74
  },
66
75
  )
File without changes
File without changes