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.
- {cortexhub-1.0.2 → cortexhub-1.0.3}/PKG-INFO +42 -8
- {cortexhub-1.0.2 → cortexhub-1.0.3}/README.md +41 -7
- {cortexhub-1.0.2 → cortexhub-1.0.3}/pyproject.toml +1 -1
- {cortexhub-1.0.2 → cortexhub-1.0.3}/src/cortexhub/__init__.py +1 -1
- {cortexhub-1.0.2 → cortexhub-1.0.3}/src/cortexhub/session.py +19 -10
- {cortexhub-1.0.2 → cortexhub-1.0.3}/.gitignore +0 -0
- {cortexhub-1.0.2 → cortexhub-1.0.3}/LICENSE +0 -0
- {cortexhub-1.0.2 → cortexhub-1.0.3}/src/cortexhub/client.py +0 -0
- {cortexhub-1.0.2 → cortexhub-1.0.3}/src/cortexhub/errors.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: cortexhub
|
|
3
|
-
Version: 1.0.
|
|
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)
|
|
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
|
|
45
|
-
print(session.mcp.headers) # {"
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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)
|
|
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
|
|
22
|
-
print(session.mcp.headers) # {"
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
|
@@ -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
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
|
29
|
+
_MCP_URL = "https://api.cortexhub.ai/v1/mcp"
|
|
22
30
|
|
|
23
|
-
#
|
|
24
|
-
#
|
|
25
|
-
#
|
|
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
|
-
|
|
72
|
+
_API_KEY_HEADER: api_key,
|
|
64
73
|
_END_USER_SUBJECT_HEADER: user_id,
|
|
65
74
|
},
|
|
66
75
|
)
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|