Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(core,python): add custom toolkit create/update, deprecate upsert (PLEN-4785)
Wrap the v3.1 custom toolkit create (POST /api/v3.1/custom/toolkits) and update (PATCH /api/v3.1/custom/toolkits/{slug}) endpoints as experimental.customToolkits.create()/update() in TypeScript and experimental.custom_toolkits.create()/update() in Python. upsert() is deprecated and warns once per process. Bumps @composio/client and composio-client to 2.0.1, which add the two operations. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H6YzWq98kCUE5K3atCRATH
Bharath committed
Nov 3, 2026 at 11:34 UTC
a5a1fc867410fcb0d190d3c23869d4e977876a45
14 files changed
+585
-48
.changeset/custom-toolkit-create-update.md
new
+6
@@ -0,0 +1,6 @@
1
+---
2
+'@composio/core': minor
3
+'@composio/slim': minor
4
+---
5
+
6
+Requires `@composio/client` `2.0.1`. Adds `composio.experimental.customToolkits.create()` and `update()`, which call the v3.1 custom toolkit create and update endpoints. `create()` takes `userId` (`'all'` to share the toolkit, or the user it is private to), generates the slug, and returns a `connectLink` for a private toolkit. `upsert()` is deprecated and logs a warning once per process; it keeps working.
pnpm-lock.yaml
+9
-9
@@ -28,8 +28,8 @@ catalogs:
28
specifier: ^5.20261019.1
29
version: 5.20261019.1
30
'@composio/client':
31
- specifier: 2.0.0
32
- version: 2.0.0
31
+ specifier: 2.0.1
32
+ version: 2.0.1
33
'@effect/language-service':
34
specifier: ^0.87.5
35
version: 0.87.5
@@ -998,7 +998,7 @@ importers:
998
dependencies:
999
'@composio/client':
1000
specifier: 'catalog:'
1001
- version: 2.0.0(effect@4.1.1)
1001
+ version: 2.0.1(effect@4.1.1)
1002
'@composio/core':
1003
specifier: workspace:*
1004
version: link:../../packages/core
@@ -1246,7 +1246,7 @@ importers:
1246
version: link:../cli-keyring
1247
'@composio/client':
1248
specifier: 'catalog:'
1249
- version: 2.0.0(effect@4.1.1)
1249
+ version: 2.0.1(effect@4.1.1)
1250
'@composio/core':
1251
specifier: workspace:*
1252
version: link:../core
@@ -1355,7 +1355,7 @@ importers:
1355
dependencies:
1356
'@composio/client':
1357
specifier: 'catalog:'
1358
- version: 2.0.0(effect@4.1.1)
1358
+ version: 2.0.1(effect@4.1.1)
1359
'@composio/json-schema-to-zod':
1360
specifier: workspace:*
1361
version: link:../json-schema-to-zod
@@ -1772,7 +1772,7 @@ importers:
1772
dependencies:
1773
'@composio/client':
1774
specifier: 'catalog:'
1775
- version: 2.0.0(effect@4.1.1)
1775
+ version: 2.0.1(effect@4.1.1)
1776
'@composio/json-schema-to-zod':
1777
specifier: workspace:*
1778
version: link:../json-schema-to-zod
@@ -2324,8 +2324,8 @@ packages:
2324
resolution: {integrity: sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ==}
2325
engines: {node: '>=0.1.90'}
2326
2327
- '@composio/client@2.0.0':
2328
- resolution: {integrity: sha512-6NK+TNvpsencFPMLJSm3gaVLl0rwYh+8N8pfRywuK9YcjxsP8H0zunO8h/1xg3rq1iV5/KUxKMGwNWookQLbMQ==}
2327
+ '@composio/client@2.0.1':
2328
+ resolution: {integrity: sha512-1+Azl8W/grinmXVt6KhDKy5UlvTiv7MCMgjqBDxd8TqndjM92/HotxLabnB63A285bvo5Lcu4kbOz413uaPmEQ==}
2329
engines: {node: '>=22'}
2330
peerDependencies:
2331
effect: '*'
@@ -7541,7 +7541,7 @@ snapshots:
7541
'@colors/colors@1.5.0':
7542
optional: true
7543
7544
- '@composio/client@2.0.0(effect@4.1.1)':
7544
+ '@composio/client@2.0.1(effect@4.1.1)':
7545
optionalDependencies:
7546
effect: 4.1.1
7547
pnpm-workspace.yaml
+1
-1
@@ -33,7 +33,7 @@ catalog:
33
'@clack/prompts': '^1.8.1'
34
'@cloudflare/vitest-pool-workers': 0.23.0
35
'@cloudflare/workers-types': ^5.20261019.1
36
- '@composio/client': 2.0.0
36
+ '@composio/client': 2.0.1
37
'@effect/language-service': ^0.87.5
38
'@effect/platform-bun': ^4.1.0
39
'@effect/vitest': ^4.1.0
python/composio/client/types.py
+8
@@ -27,8 +27,12 @@ from composio_client.types import (
27
connected_account_retrieve_response,
28
connected_account_revoke_response,
29
connected_account_update_status_response,
30
+ custom_create_toolkit_params,
31
+ custom_create_toolkit_response,
32
custom_delete_toolkit_response,
33
custom_sync_response,
34
+ custom_update_toolkits_params,
35
+ custom_update_toolkits_response,
36
custom_upsert_params,
37
custom_upsert_response,
38
keyring_list_transfer_keys_response,
@@ -137,8 +141,12 @@ __all__ = (
141
"connected_account_retrieve_response",
142
"connected_account_revoke_response",
143
"connected_account_update_status_response",
144
+ "custom_create_toolkit_params",
145
+ "custom_create_toolkit_response",
146
"custom_delete_toolkit_response",
147
"custom_sync_response",
148
+ "custom_update_toolkits_params",
149
+ "custom_update_toolkits_response",
150
"custom_upsert_params",
151
"custom_upsert_response",
152
"keyring_list_transfer_keys_response",
python/composio/core/models/experimental.py
+98
-1
@@ -17,6 +17,7 @@ not on the underlying model modules.
17
from __future__ import annotations
18
19
import typing as t
20
+import warnings
21
22
import typing_extensions as te
23
from pydantic import BaseModel
@@ -25,8 +26,12 @@ from composio.client import HttpClient
26
from composio.utils.pydantic import none_to_omit
27
from composio.client.types import (
28
connected_account_patch_response,
29
+ custom_create_toolkit_params,
30
+ custom_create_toolkit_response,
31
custom_delete_toolkit_response,
32
custom_sync_response,
33
+ custom_update_toolkits_params,
34
+ custom_update_toolkits_response,
35
custom_upsert_params,
36
custom_upsert_response,
37
usage_retrieve_params,
@@ -129,6 +134,15 @@ class ExperimentalUsage:
134
return self._require_client().project.usage.retrieve(entity_type, **params)
135
136
137
+_UPSERT_DEPRECATION = (
138
+ "experimental.custom_toolkits.upsert() is deprecated. Use create() for a "
139
+ "new toolkit and update(slug, ...) to change its name, logo or API key field."
140
+)
141
+
142
+# Warn once per process so services that upsert on every deploy aren't spammed.
143
+_upsert_warning_emitted = False
144
+
145
+
146
class ExperimentalCustomToolkits:
147
"""Project-owned custom toolkits, accessed via
148
``composio.experimental.custom_toolkits``.
@@ -149,10 +163,78 @@ class ExperimentalCustomToolkits:
163
if self._client is None:
164
raise exceptions.ValidationError(
165
"experimental.custom_toolkits requires a Composio client. Access "
152
- "it via composio.experimental.custom_toolkits.upsert(...)."
166
+ "it via composio.experimental.custom_toolkits.create(...)."
167
)
168
return self._client
169
170
+ def create(
171
+ self,
172
+ **params: te.Unpack[custom_create_toolkit_params.CustomCreateToolkitParams],
173
+ ) -> custom_create_toolkit_response.CustomCreateToolkitResponse:
174
+ """
175
+ Create a custom MCP toolkit and return its generated slug.
176
+ Experimental — shape may change.
177
+
178
+ Set ``user_id`` to ``"all"`` to share the toolkit with every user in
179
+ the project, or to a user ID to make it private to that user.
180
+ ``app_url``, ``auth_schemes`` and ``user_id`` cannot change later:
181
+ delete and re-create the toolkit instead.
182
+
183
+ :param name: Display name of the toolkit.
184
+ :param app_url: The MCP server URL. Must use https.
185
+ :param auth_schemes: How users authenticate to the MCP server.
186
+ :param user_id: ``"all"``, or the user ID the toolkit is private to.
187
+ :param logo_file: Optional base64 PNG or JPEG logo.
188
+ :param callback_url: Where to send the user after they connect. Used
189
+ only for ``connect_link``.
190
+ :return: The toolkit ``slug`` and, for a private toolkit, a
191
+ ``connect_link`` to send that user to (else ``None``).
192
+
193
+ Example:
194
+ toolkit = composio.experimental.custom_toolkits.create(
195
+ name="Internal API",
196
+ app_url="https://mcp.internal.example.com/mcp",
197
+ auth_schemes=[
198
+ {
199
+ "mode": "API_KEY",
200
+ "headers": {"Authorization": "Bearer {{generic_api_key}}"},
201
+ }
202
+ ],
203
+ user_id="user_123",
204
+ )
205
+ """
206
+ return self._require_client().custom.create_toolkit(**params)
207
+
208
+ def update(
209
+ self,
210
+ slug: str,
211
+ **params: te.Unpack[custom_update_toolkits_params.CustomUpdateToolkitsParams],
212
+ ) -> custom_update_toolkits_response.CustomUpdateToolkitsResponse:
213
+ """
214
+ Update a custom toolkit's name, logo or API key field copy. Omitted
215
+ fields keep their current value. Experimental — shape may change.
216
+
217
+ On a project with 2FA enabled, updating a private toolkit requires the
218
+ ``user_id`` it is private to.
219
+
220
+ :param slug: The custom toolkit slug returned by :meth:`create`.
221
+ :param name: New display name.
222
+ :param logo_file: New base64 PNG or JPEG logo.
223
+ :param api_key_field: Label and help text for the API key input on
224
+ the connect page. API_KEY toolkits only.
225
+ :param user_id: The user the toolkit is private to.
226
+ :return: ``success``.
227
+
228
+ Example:
229
+ composio.experimental.custom_toolkits.update(
230
+ "CUSTOM_INTERNAL_API_K7F2Q",
231
+ name="Internal API (prod)",
232
+ user_id="user_123",
233
+ )
234
+ """
235
+ return self._require_client().custom.update_toolkits(slug, **params)
236
+
237
+ @te.deprecated(_UPSERT_DEPRECATION, category=None)
238
def upsert(
239
self,
240
**params: te.Unpack[custom_upsert_params.CustomUpsertParams],
@@ -162,6 +244,11 @@ class ExperimentalCustomToolkits:
244
field copy) when the project already owns one with this slug.
245
Experimental — shape may change.
246
247
+ .. deprecated::
248
+ Use :meth:`create` for a new toolkit and :meth:`update` to change
249
+ its name, logo or API key field. ``create`` generates the slug,
250
+ so store the slug it returns.
251
+
252
``app_url`` and ``auth_schemes`` cannot change on an existing
253
toolkit: re-sending them unchanged is a no-op, and changing them fails
254
with a 409. Delete and re-register the toolkit instead, which revokes
@@ -188,6 +275,16 @@ class ExperimentalCustomToolkits:
275
},
276
)
277
"""
278
+ global _upsert_warning_emitted
279
+ if not _upsert_warning_emitted:
280
+ from composio import exceptions
281
+
282
+ _upsert_warning_emitted = True
283
+ warnings.warn(
284
+ _UPSERT_DEPRECATION,
285
+ exceptions.ComposioDeprecationWarning,
286
+ stacklevel=2,
287
+ )
288
return self._require_client().custom.upsert(**params)
289
290
def sync(
python/pyproject.toml
+1
-1
@@ -14,7 +14,7 @@ dependencies = [
14
"pysher==1.0.8",
15
"websocket-client<2",
16
"pydantic>=2.11.9,<3",
17
- "composio-client==2.0.0",
17
+ "composio-client==2.0.1",
18
"typing-extensions>=4.16.0,<5",
19
"openai>=2.48.0,<4",
20
"json-schema-to-pydantic>=0.4.11,<1",
python/setup.py
+1
-1
@@ -28,7 +28,7 @@ setup(
28
"pysher==1.0.8",
29
"websocket-client<2",
30
"pydantic>=2.11.9,<3",
31
- "composio-client==2.0.0",
31
+ "composio-client==2.0.1",
32
"typing-extensions>=4.16.0,<5",
33
"openai>=2.48.0,<4",
34
"json-schema-to-pydantic>=0.4.11,<1",
python/tests/test_experimental_custom_toolkits.py
+45
-1
@@ -1,5 +1,6 @@
1
"""Tests for ``composio.experimental.custom_toolkits``."""
2
3
+import warnings
4
from unittest.mock import Mock
5
6
import pytest
@@ -7,6 +8,7 @@ from composio_client import omit
8
9
from composio import exceptions
10
from composio.client.types import custom_upsert_params
11
+from composio.core.models import experimental as experimental_module
12
from composio.core.models.experimental import (
13
ExperimentalAPI,
14
ExperimentalCustomToolkits,
@@ -43,6 +45,46 @@ class TestExperimentalCustomToolkits:
45
assert isinstance(experimental.custom_toolkits, ExperimentalCustomToolkits)
46
assert experimental.custom_toolkits._client is mock_client
47
48
+ def test_create_passes_params_through(self, custom_toolkits, mock_client):
49
+ mock_client.custom.create_toolkit.return_value = "created"
50
+
51
+ result = custom_toolkits.create(**TOOLKIT_CONFIG, user_id="user_123")
52
+
53
+ assert result == "created"
54
+ mock_client.custom.create_toolkit.assert_called_once_with(
55
+ **TOOLKIT_CONFIG, user_id="user_123"
56
+ )
57
+
58
+ def test_update_passes_slug_and_params_through(self, custom_toolkits, mock_client):
59
+ mock_client.custom.update_toolkits.return_value = "updated"
60
+
61
+ result = custom_toolkits.update(
62
+ "CUSTOM_MY_TOOLKIT_K7F2Q", name="Renamed", user_id="user_123"
63
+ )
64
+
65
+ assert result == "updated"
66
+ mock_client.custom.update_toolkits.assert_called_once_with(
67
+ "CUSTOM_MY_TOOLKIT_K7F2Q", name="Renamed", user_id="user_123"
68
+ )
69
+
70
+ def test_upsert_warns_once_per_process(
71
+ self, custom_toolkits, mock_client, monkeypatch
72
+ ):
73
+ monkeypatch.setattr(experimental_module, "_upsert_warning_emitted", False)
74
+
75
+ with warnings.catch_warnings(record=True) as caught:
76
+ warnings.simplefilter("always")
77
+ custom_toolkits.upsert(slug="MY_TOOLKIT", toolkit_config=TOOLKIT_CONFIG)
78
+ custom_toolkits.upsert(slug="MY_TOOLKIT", toolkit_config=TOOLKIT_CONFIG)
79
+
80
+ deprecations = [
81
+ w
82
+ for w in caught
83
+ if issubclass(w.category, exceptions.ComposioDeprecationWarning)
84
+ ]
85
+ assert len(deprecations) == 1
86
+ assert "create()" in str(deprecations[0].message)
87
+
88
def test_upsert_passes_params_through(self, custom_toolkits, mock_client):
89
mock_client.custom.upsert.return_value = "upserted"
90
@@ -84,7 +126,9 @@ class TestExperimentalCustomToolkits:
126
custom_toolkits = ExperimentalCustomToolkits(client=None)
127
128
with pytest.raises(exceptions.ValidationError):
87
- custom_toolkits.upsert(slug="MY_TOOLKIT", toolkit_config=TOOLKIT_CONFIG)
129
+ custom_toolkits.create(**TOOLKIT_CONFIG, user_id="all")
130
+ with pytest.raises(exceptions.ValidationError):
131
+ custom_toolkits.update("CUSTOM_MY_TOOLKIT", name="Renamed")
132
with pytest.raises(exceptions.ValidationError):
133
custom_toolkits.sync("CUSTOM_MY_TOOLKIT")
134
with pytest.raises(exceptions.ValidationError):
ts/packages/core/src/models/CustomToolkits.ts
+114
-8
@@ -7,10 +7,16 @@
7
*/
8
import ComposioClient from '@composio/client';
9
import {
10
+ CustomToolkitCreateParams,
11
+ CustomToolkitCreateParamsSchema,
12
+ CustomToolkitCreateResponse,
13
CustomToolkitDeleteResponse,
14
CustomToolkitSyncParams,
15
CustomToolkitSyncParamsSchema,
16
CustomToolkitSyncResponse,
17
+ CustomToolkitUpdateParams,
18
+ CustomToolkitUpdateParamsSchema,
19
+ CustomToolkitUpdateResponse,
20
CustomToolkitUpsertParams,
21
CustomToolkitUpsertParamsSchema,
22
CustomToolkitUpsertResponse,
@@ -19,14 +25,24 @@ import { ComposioRequestOptions } from '../types/requestOptions.types';
25
import { ValidationError } from '../errors/ValidationErrors';
26
import { telemetry } from '../telemetry/Telemetry';
27
import { withCancellation } from '../utils/cancellation';
28
+import logger from '../utils/logger';
29
import {
30
+ transformCustomToolkitCreateParams,
31
+ transformCustomToolkitCreateResponse,
32
transformCustomToolkitDeleteResponse,
33
transformCustomToolkitSyncParams,
34
transformCustomToolkitSyncResponse,
35
+ transformCustomToolkitUpdateParams,
36
+ transformCustomToolkitUpdateResponse,
37
transformCustomToolkitUpsertParams,
38
transformCustomToolkitUpsertResponse,
39
} from '../utils/transformers/customToolkits';
40
41
+const UPSERT_DEPRECATION =
42
+ '[Deprecation] composio.experimental.customToolkits.upsert() is deprecated. ' +
43
+ 'Use create() for a new toolkit and update(slug, ...) to change its name, logo or API key field.';
44
+let _upsertDeprecationWarned = false;
45
+
46
/**
47
* `composio.experimental.customToolkits` — toolkits your project registers
48
* from its own app or MCP server, with their own auth configs and connected
@@ -38,15 +54,13 @@ import {
54
*
55
* @example
56
* ```typescript
41
- * const { slug } = await composio.experimental.customToolkits.upsert({
42
- * slug: 'MY_TOOLKIT',
43
- * toolkitConfig: {
44
- * name: 'My Toolkit',
45
- * appUrl: 'https://mcp.example.com/mcp',
46
- * authSchemes: [{ mode: 'DCR_OAUTH', discoveryUrl: 'https://mcp.example.com/.well-known/oauth-authorization-server' }],
47
- * },
57
+ * const { slug } = await composio.experimental.customToolkits.create({
58
+ * name: 'My Toolkit',
59
+ * appUrl: 'https://mcp.example.com/mcp',
60
+ * authSchemes: [{ mode: 'DCR_OAUTH', discoveryUrl: 'https://mcp.example.com/.well-known/oauth-authorization-server' }],
61
+ * userId: 'all',
62
* });
49
- * await composio.experimental.customToolkits.sync(slug);
63
+ * await composio.experimental.customToolkits.update(slug, { name: 'My Renamed Toolkit' });
64
* ```
65
*/
66
export class CustomToolkits {
@@ -57,6 +71,90 @@ export class CustomToolkits {
71
telemetry.instrument(this, 'CustomToolkits');
72
}
73
74
+ /**
75
+ * Creates a custom MCP toolkit and returns its generated slug.
76
+ * **Experimental — custom toolkits are in pilot; shape may change.**
77
+ *
78
+ * Set `userId` to `'all'` to share the toolkit with every user in the
79
+ * project, or to a user ID to make it private to that user. `appUrl`,
80
+ * `authSchemes` and `userId` cannot change later: delete and re-create the
81
+ * toolkit instead. For a private toolkit, `connectLink` is where to send
82
+ * that user to connect.
83
+ *
84
+ * @param {CustomToolkitCreateParams} params - The toolkit to create
85
+ * @returns {Promise<CustomToolkitCreateResponse>} The toolkit's slug and, for a private toolkit, a connect link
86
+ * @throws {ValidationError} If the params fail validation
87
+ *
88
+ * @example
89
+ * ```typescript
90
+ * const { slug, connectLink } = await composio.experimental.customToolkits.create({
91
+ * name: 'Internal API',
92
+ * appUrl: 'https://mcp.internal.example.com/mcp',
93
+ * authSchemes: [
94
+ * { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
95
+ * ],
96
+ * userId: 'user_123',
97
+ * });
98
+ * ```
99
+ */
100
+ async create(
101
+ params: CustomToolkitCreateParams,
102
+ requestOptions?: ComposioRequestOptions
103
+ ): Promise<CustomToolkitCreateResponse> {
104
+ const parsedParams = CustomToolkitCreateParamsSchema.safeParse(params);
105
+ if (!parsedParams.success) {
106
+ throw new ValidationError('Failed to parse custom toolkit create params', {
107
+ cause: parsedParams.error,
108
+ });
109
+ }
110
+ const body = transformCustomToolkitCreateParams(parsedParams.data);
111
+ const result = await withCancellation(
112
+ () => this.client.custom.createToolkit(body, requestOptions),
113
+ requestOptions?.signal
114
+ );
115
+ return transformCustomToolkitCreateResponse(result);
116
+ }
117
+
118
+ /**
119
+ * Updates a custom toolkit's name, logo or API key field copy. Omitted
120
+ * fields keep their current value.
121
+ * **Experimental — custom toolkits are in pilot; shape may change.**
122
+ *
123
+ * On a project with 2FA enabled, updating a private toolkit requires the
124
+ * `userId` it is private to.
125
+ *
126
+ * @param {string} slug - The custom toolkit slug returned by `create()`
127
+ * @param {CustomToolkitUpdateParams} params - At least one of `name`, `logoFile`, `apiKeyField`
128
+ * @returns {Promise<CustomToolkitUpdateResponse>} `{ success: true }`
129
+ * @throws {ValidationError} If the params fail validation
130
+ *
131
+ * @example
132
+ * ```typescript
133
+ * await composio.experimental.customToolkits.update('CUSTOM_INTERNAL_API_K7F2Q', {
134
+ * name: 'Internal API (prod)',
135
+ * userId: 'user_123',
136
+ * });
137
+ * ```
138
+ */
139
+ async update(
140
+ slug: string,
141
+ params: CustomToolkitUpdateParams,
142
+ requestOptions?: ComposioRequestOptions
143
+ ): Promise<CustomToolkitUpdateResponse> {
144
+ const parsedParams = CustomToolkitUpdateParamsSchema.safeParse(params);
145
+ if (!parsedParams.success) {
146
+ throw new ValidationError('Failed to parse custom toolkit update params', {
147
+ cause: parsedParams.error,
148
+ });
149
+ }
150
+ const body = transformCustomToolkitUpdateParams(parsedParams.data);
151
+ const result = await withCancellation(
152
+ () => this.client.custom.updateToolkits(slug, body, requestOptions),
153
+ requestOptions?.signal
154
+ );
155
+ return transformCustomToolkitUpdateResponse(result);
156
+ }
157
+
158
/**
159
* Creates a custom toolkit, or updates its display metadata (name, API key
160
* field copy) when the project already owns a toolkit with this slug.
@@ -83,11 +181,19 @@ export class CustomToolkits {
181
* },
182
* });
183
* ```
184
+ *
185
+ * @deprecated Use `create()` for a new toolkit and `update(slug, ...)` to change
186
+ * its name, logo or API key field. `create()` generates the slug, so store the
187
+ * slug it returns.
188
*/
189
async upsert(
190
params: CustomToolkitUpsertParams,
191
requestOptions?: ComposioRequestOptions
192
): Promise<CustomToolkitUpsertResponse> {
193
+ if (!_upsertDeprecationWarned) {
194
+ _upsertDeprecationWarned = true;
195
+ logger.warn(UPSERT_DEPRECATION);
196
+ }
197
const parsedParams = CustomToolkitUpsertParamsSchema.safeParse(params);
198
if (!parsedParams.success) {
199
throw new ValidationError('Failed to parse custom toolkit upsert params', {
ts/packages/core/src/models/Experimental.ts
+1
-1
@@ -144,7 +144,7 @@ export class Experimental {
144
usage: Usage;
145
146
/**
147
- * Register and manage project-owned custom toolkits (`upsert()` / `sync()` / `delete()`).
147
+ * Register and manage project-owned custom toolkits (`create()` / `update()` / `sync()` / `delete()`).
148
* **Experimental — custom toolkits are in pilot; shape may change.**
149
*
150
* @example
ts/packages/core/src/types/customToolkits.types.ts
+83
-12
@@ -1,5 +1,11 @@
1
import { z } from 'zod/v3';
2
3
+const CustomToolkitApiKeyFieldSchema = z.object({
4
+ displayName: z.string().min(1).max(100).optional(),
5
+ description: z.string().min(1).max(500).optional(),
6
+});
7
+export type CustomToolkitApiKeyField = z.infer<typeof CustomToolkitApiKeyFieldSchema>;
8
+
9
/**
10
* How end users authenticate to a custom toolkit.
11
* **Experimental — custom toolkits are in pilot; shape may change.**
@@ -15,12 +21,7 @@ export const CustomToolkitAuthSchemeSchema = z.discriminatedUnion('mode', [
21
*/
22
headers: z.record(z.string(), z.string()),
23
/** End-user copy for the API key input on the connect page. */
18
- apiKeyField: z
19
- .object({
20
- displayName: z.string().min(1).max(100).optional(),
21
- description: z.string().min(1).max(500).optional(),
22
- })
23
- .optional(),
24
+ apiKeyField: CustomToolkitApiKeyFieldSchema.optional(),
25
}),
26
z.object({
27
mode: z.literal('DCR_OAUTH'),
@@ -33,9 +34,84 @@ export const CustomToolkitAuthSchemeSchema = z.discriminatedUnion('mode', [
34
]);
35
export type CustomToolkitAuthScheme = z.infer<typeof CustomToolkitAuthSchemeSchema>;
36
37
+const CustomToolkitLogoFileSchema = z.object({
38
+ content: z.string().min(1),
39
+ mimeType: z.enum(['image/png', 'image/jpeg']),
40
+});
41
+export type CustomToolkitLogoFile = z.infer<typeof CustomToolkitLogoFileSchema>;
42
+
43
+/**
44
+ * Params for `composio.experimental.customToolkits.create()`.
45
+ * **Experimental — custom toolkits are in pilot; shape may change.**
46
+ */
47
+export const CustomToolkitCreateParamsSchema = z.object({
48
+ /** Human-readable toolkit name. */
49
+ name: z.string().min(1).max(200),
50
+ /** The MCP server URL. Must use https. */
51
+ appUrl: z.string().url(),
52
+ /** Square PNG or JPEG logo (256-1024px, max 3MB), base64-encoded. Defaults to the MCP logo. */
53
+ logoFile: CustomToolkitLogoFileSchema.optional(),
54
+ /** At least one scheme. Cannot be changed after create. */
55
+ authSchemes: z.array(CustomToolkitAuthSchemeSchema).min(1),
56
+ /**
57
+ * `'all'` to share the toolkit with every user in the project, or a user ID
58
+ * to make it private to that user. Cannot be changed after create.
59
+ */
60
+ userId: z.string().min(1),
61
+ /** Where to send the user after they connect. Used only for `connectLink`. */
62
+ callbackUrl: z.string().url().optional(),
63
+});
64
+export type CustomToolkitCreateParams = z.infer<typeof CustomToolkitCreateParamsSchema>;
65
+
66
+export const CustomToolkitCreateResponseSchema = z.object({
67
+ /** Slug of the created toolkit. Store it to update, sync or delete the toolkit later. */
68
+ slug: z.string(),
69
+ /**
70
+ * Hosted connect page for a private toolkit's user. `null` for shared or
71
+ * no-auth toolkits, or if the link could not be created.
72
+ */
73
+ connectLink: z
74
+ .object({
75
+ redirectUrl: z.string(),
76
+ expiresAt: z.string(),
77
+ connectedAccountId: z.string(),
78
+ })
79
+ .nullable(),
80
+});
81
+export type CustomToolkitCreateResponse = z.infer<typeof CustomToolkitCreateResponseSchema>;
82
+
83
+/**
84
+ * Params for `composio.experimental.customToolkits.update()`.
85
+ * **Experimental — custom toolkits are in pilot; shape may change.**
86
+ */
87
+export const CustomToolkitUpdateParamsSchema = z
88
+ .object({
89
+ name: z.string().min(1).max(200).optional(),
90
+ logoFile: CustomToolkitLogoFileSchema.optional(),
91
+ /** End-user copy for the API key input on the connect page. API_KEY toolkits only. */
92
+ apiKeyField: CustomToolkitApiKeyFieldSchema.optional(),
93
+ /**
94
+ * The user the toolkit is private to. Required to update a private toolkit
95
+ * when the project has 2FA enabled.
96
+ */
97
+ userId: z.string().min(1).optional(),
98
+ })
99
+ .refine(
100
+ params => [params.name, params.logoFile, params.apiKeyField].some(value => value !== undefined),
101
+ { message: 'Provide at least one of name, logoFile, apiKeyField' }
102
+ );
103
+export type CustomToolkitUpdateParams = z.infer<typeof CustomToolkitUpdateParamsSchema>;
104
+
105
+export const CustomToolkitUpdateResponseSchema = z.object({
106
+ success: z.literal(true),
107
+});
108
+export type CustomToolkitUpdateResponse = z.infer<typeof CustomToolkitUpdateResponseSchema>;
109
+
110
/**
111
* Params for `composio.experimental.customToolkits.upsert()`.
112
* **Experimental — custom toolkits are in pilot; shape may change.**
113
+ *
114
+ * @deprecated Use `CustomToolkitCreateParams` with `create()`.
115
*/
116
export const CustomToolkitUpsertParamsSchema = z.object({
117
/**
@@ -53,12 +129,7 @@ export const CustomToolkitUpsertParamsSchema = z.object({
129
/** The app URL. For an MCP app, the MCP server URL. */
130
appUrl: z.string().url(),
131
/** Square PNG or JPEG logo (256-1024px, max 3MB), base64-encoded. Defaults to the Composio logo. */
56
- logoFile: z
57
- .object({
58
- content: z.string().min(1),
59
- mimeType: z.enum(['image/png', 'image/jpeg']),
60
- })
61
- .optional(),
132
+ logoFile: CustomToolkitLogoFileSchema.optional(),
133
/** At least one scheme. The schemes cannot change once the toolkit exists. */
134
authSchemes: z.array(CustomToolkitAuthSchemeSchema).min(1),
135
}),
ts/packages/core/src/utils/transformers/customToolkits.ts
+70
-9
@@ -1,24 +1,48 @@
1
import type {
2
+ CustomCreateToolkitParams as RawCustomCreateToolkitParams,
3
+ CustomCreateToolkitResponse as RawCustomCreateToolkitResponse,
4
CustomDeleteToolkitResponse as RawCustomDeleteToolkitResponse,
5
CustomSyncParams as RawCustomSyncParams,
6
CustomSyncResponse as RawCustomSyncResponse,
7
+ CustomUpdateToolkitsParams as RawCustomUpdateToolkitsParams,
8
+ CustomUpdateToolkitsResponse as RawCustomUpdateToolkitsResponse,
9
CustomUpsertParams as RawCustomUpsertParams,
10
CustomUpsertResponse as RawCustomUpsertResponse,
11
} from '@composio/client/resources/custom';
12
import {
13
+ CustomToolkitApiKeyField,
14
CustomToolkitAuthScheme,
15
+ CustomToolkitCreateParams,
16
+ CustomToolkitCreateResponse,
17
+ CustomToolkitCreateResponseSchema,
18
CustomToolkitDeleteResponse,
19
CustomToolkitDeleteResponseSchema,
20
+ CustomToolkitLogoFile,
21
CustomToolkitSyncParams,
22
CustomToolkitSyncResponse,
23
CustomToolkitSyncResponseSchema,
24
+ CustomToolkitUpdateParams,
25
+ CustomToolkitUpdateResponse,
26
+ CustomToolkitUpdateResponseSchema,
27
CustomToolkitUpsertParams,
28
CustomToolkitUpsertResponse,
29
CustomToolkitUpsertResponseSchema,
30
} from '../../types/customToolkits.types';
31
import { transform } from '../transform';
32
21
-type RawCustomToolkitAuthScheme = RawCustomUpsertParams['toolkit_config']['auth_schemes'][number];
33
+type RawCustomToolkitAuthScheme = RawCustomCreateToolkitParams['auth_schemes'][number];
34
+type RawCustomToolkitLogoFile = NonNullable<RawCustomCreateToolkitParams['logo_file']>;
35
+
36
+const transformCustomToolkitLogoFile = (
37
+ logoFile: CustomToolkitLogoFile | undefined
38
+): RawCustomToolkitLogoFile | undefined =>
39
+ logoFile && { content: logoFile.content, mime_type: logoFile.mimeType };
40
+
41
+const transformCustomToolkitApiKeyField = (apiKeyField: CustomToolkitApiKeyField | undefined) =>
42
+ apiKeyField && {
43
+ display_name: apiKeyField.displayName,
44
+ description: apiKeyField.description,
45
+ };
46
47
const transformCustomToolkitAuthScheme = (
48
scheme: CustomToolkitAuthScheme
@@ -30,16 +54,56 @@ const transformCustomToolkitAuthScheme = (
54
return {
55
mode: 'API_KEY',
56
headers: scheme.headers,
33
- api_key_field: scheme.apiKeyField && {
34
- display_name: scheme.apiKeyField.displayName,
35
- description: scheme.apiKeyField.description,
36
- },
57
+ api_key_field: transformCustomToolkitApiKeyField(scheme.apiKeyField),
58
};
59
case 'DCR_OAUTH':
60
return { mode: 'DCR_OAUTH', discovery_url: scheme.discoveryUrl };
61
}
62
};
63
64
+export const transformCustomToolkitCreateParams = (
65
+ params: CustomToolkitCreateParams
66
+): RawCustomCreateToolkitParams => ({
67
+ name: params.name,
68
+ app_url: params.appUrl,
69
+ logo_file: transformCustomToolkitLogoFile(params.logoFile),
70
+ auth_schemes: params.authSchemes.map(transformCustomToolkitAuthScheme),
71
+ user_id: params.userId,
72
+ callback_url: params.callbackUrl,
73
+});
74
+
75
+export const transformCustomToolkitCreateResponse = (
76
+ response: RawCustomCreateToolkitResponse
77
+): CustomToolkitCreateResponse => {
78
+ return transform(response)
79
+ .with(CustomToolkitCreateResponseSchema)
80
+ .using(response => ({
81
+ slug: response.slug,
82
+ connectLink: response.connect_link && {
83
+ redirectUrl: response.connect_link.redirect_url,
84
+ expiresAt: response.connect_link.expires_at,
85
+ connectedAccountId: response.connect_link.connected_account_id,
86
+ },
87
+ }));
88
+};
89
+
90
+export const transformCustomToolkitUpdateParams = (
91
+ params: CustomToolkitUpdateParams
92
+): RawCustomUpdateToolkitsParams => ({
93
+ name: params.name,
94
+ logo_file: transformCustomToolkitLogoFile(params.logoFile),
95
+ api_key_field: transformCustomToolkitApiKeyField(params.apiKeyField),
96
+ user_id: params.userId,
97
+});
98
+
99
+export const transformCustomToolkitUpdateResponse = (
100
+ response: RawCustomUpdateToolkitsResponse
101
+): CustomToolkitUpdateResponse => {
102
+ return transform(response)
103
+ .with(CustomToolkitUpdateResponseSchema)
104
+ .using(response => ({ success: response.success }));
105
+};
106
+
107
export const transformCustomToolkitUpsertParams = (
108
params: CustomToolkitUpsertParams
109
): RawCustomUpsertParams => ({
@@ -47,10 +111,7 @@ export const transformCustomToolkitUpsertParams = (
111
toolkit_config: {
112
name: params.toolkitConfig.name,
113
app_url: params.toolkitConfig.appUrl,
50
- logo_file: params.toolkitConfig.logoFile && {
51
- content: params.toolkitConfig.logoFile.content,
52
- mime_type: params.toolkitConfig.logoFile.mimeType,
53
- },
114
+ logo_file: transformCustomToolkitLogoFile(params.toolkitConfig.logoFile),
115
auth_schemes: params.toolkitConfig.authSchemes.map(transformCustomToolkitAuthScheme),
116
},
117
});
ts/packages/core/test/models/customToolkits.test.ts
+144
@@ -13,6 +13,8 @@ vi.mock('../../src/telemetry/Telemetry', () => ({
13
14
const createMockClient = () => ({
15
custom: {
16
+ createToolkit: vi.fn(),
17
+ updateToolkits: vi.fn(),
18
upsert: vi.fn(),
19
sync: vi.fn(),
20
deleteToolkit: vi.fn(),
@@ -34,7 +36,149 @@ describe('Experimental.customToolkits', () => {
36
expect(telemetry.instrument).toHaveBeenCalledWith(customToolkits, 'CustomToolkits');
37
});
38
39
+ describe('create', () => {
40
+ it('maps the toolkit to the wire and transforms the connect link', async () => {
41
+ mockClient.custom.createToolkit.mockResolvedValue({
42
+ slug: 'CUSTOM_MY_TOOLKIT_K7F2Q',
43
+ connect_link: {
44
+ redirect_url: 'https://connect.composio.dev/link/lk_1',
45
+ expires_at: '2026-11-03T12:00:00Z',
46
+ connected_account_id: 'ca_abc123',
47
+ },
48
+ });
49
+ const signal = new AbortController().signal;
50
+
51
+ const result = await customToolkits.create(
52
+ {
53
+ name: 'My Toolkit',
54
+ appUrl: 'https://mcp.example.com/mcp',
55
+ logoFile: { content: 'aGVsbG8=', mimeType: 'image/png' },
56
+ authSchemes: [
57
+ {
58
+ mode: 'API_KEY',
59
+ headers: { Authorization: 'Bearer {{generic_api_key}}' },
60
+ apiKeyField: { displayName: 'API key' },
61
+ },
62
+ ],
63
+ userId: 'user_123',
64
+ callbackUrl: 'https://app.example.com/connected',
65
+ },
66
+ { signal }
67
+ );
68
+
69
+ const [body, options] = mockClient.custom.createToolkit.mock.calls[0];
70
+ expect(JSON.parse(JSON.stringify(body))).toEqual({
71
+ name: 'My Toolkit',
72
+ app_url: 'https://mcp.example.com/mcp',
73
+ logo_file: { content: 'aGVsbG8=', mime_type: 'image/png' },
74
+ auth_schemes: [
75
+ {
76
+ mode: 'API_KEY',
77
+ headers: { Authorization: 'Bearer {{generic_api_key}}' },
78
+ api_key_field: { display_name: 'API key' },
79
+ },
80
+ ],
81
+ user_id: 'user_123',
82
+ callback_url: 'https://app.example.com/connected',
83
+ });
84
+ expect(options).toEqual({ signal });
85
+ expect(result).toEqual({
86
+ slug: 'CUSTOM_MY_TOOLKIT_K7F2Q',
87
+ connectLink: {
88
+ redirectUrl: 'https://connect.composio.dev/link/lk_1',
89
+ expiresAt: '2026-11-03T12:00:00Z',
90
+ connectedAccountId: 'ca_abc123',
91
+ },
92
+ });
93
+ });
94
+
95
+ it('returns a null connect link for a shared toolkit', async () => {
96
+ mockClient.custom.createToolkit.mockResolvedValue({
97
+ slug: 'CUSTOM_MY_TOOLKIT_K7F2Q',
98
+ connect_link: null,
99
+ });
100
+
101
+ const result = await customToolkits.create({
102
+ name: 'My Toolkit',
103
+ appUrl: 'https://mcp.example.com/mcp',
104
+ authSchemes: [{ mode: 'NO_AUTH' }],
105
+ userId: 'all',
106
+ });
107
+
108
+ expect(result).toEqual({ slug: 'CUSTOM_MY_TOOLKIT_K7F2Q', connectLink: null });
109
+ });
110
+
111
+ it.each([
112
+ ['no user ID', { userId: undefined }],
113
+ ['no auth schemes', { authSchemes: [] }],
114
+ ['an app URL that is not a URL', { appUrl: 'not a url' }],
115
+ ])('rejects %s before calling the API', async (_label, override) => {
116
+ await expect(
117
+ customToolkits.create({
118
+ name: 'My Toolkit',
119
+ appUrl: 'https://mcp.example.com/mcp',
120
+ authSchemes: [{ mode: 'NO_AUTH' }],
121
+ userId: 'all',
122
+ ...(override as object),
123
+ })
124
+ ).rejects.toThrow(ValidationError);
125
+ expect(mockClient.custom.createToolkit).not.toHaveBeenCalled();
126
+ });
127
+ });
128
+
129
+ describe('update', () => {
130
+ it('sends only the given fields and transforms the response', async () => {
131
+ mockClient.custom.updateToolkits.mockResolvedValue({ success: true });
132
+
133
+ const result = await customToolkits.update('CUSTOM_MY_TOOLKIT_K7F2Q', {
134
+ apiKeyField: { displayName: 'Token', description: 'From your settings page' },
135
+ userId: 'user_123',
136
+ });
137
+
138
+ const [slug, body] = mockClient.custom.updateToolkits.mock.calls[0];
139
+ expect(slug).toBe('CUSTOM_MY_TOOLKIT_K7F2Q');
140
+ expect(JSON.parse(JSON.stringify(body))).toEqual({
141
+ api_key_field: { display_name: 'Token', description: 'From your settings page' },
142
+ user_id: 'user_123',
143
+ });
144
+ expect(result).toEqual({ success: true });
145
+ });
146
+
147
+ it('rejects an update with nothing to change before calling the API', async () => {
148
+ await expect(
149
+ customToolkits.update('CUSTOM_MY_TOOLKIT_K7F2Q', { userId: 'user_123' })
150
+ ).rejects.toThrow(ValidationError);
151
+ expect(mockClient.custom.updateToolkits).not.toHaveBeenCalled();
152
+ });
153
+ });
154
+
155
describe('upsert', () => {
156
+ it('warns once per process that it is deprecated', async () => {
157
+ vi.resetModules();
158
+ const { CustomToolkits: FreshCustomToolkits } =
159
+ await import('../../src/models/CustomToolkits');
160
+ const { default: freshLogger } = await import('../../src/utils/logger');
161
+ const warn = vi.spyOn(freshLogger, 'warn').mockImplementation(() => {});
162
+ mockClient.custom.upsert.mockResolvedValue({ slug: 'CUSTOM_MY_TOOLKIT' });
163
+ const fresh = new FreshCustomToolkits(mockClient as unknown as ComposioClient);
164
+ const params = {
165
+ slug: 'MY_TOOLKIT',
166
+ toolkitConfig: {
167
+ name: 'My Toolkit',
168
+ appUrl: 'https://mcp.example.com/mcp',
169
+ authSchemes: [{ mode: 'NO_AUTH' as const }],
170
+ },
171
+ };
172
+
173
+ await fresh.upsert(params);
174
+ await fresh.upsert(params);
175
+
176
+ const deprecationWarnings = warn.mock.calls.filter(([message]) =>
177
+ String(message).includes('upsert() is deprecated')
178
+ );
179
+ expect(deprecationWarnings).toHaveLength(1);
180
+ });
181
+
182
it('maps every auth scheme and the logo to the wire', async () => {
183
mockClient.custom.upsert.mockResolvedValue({ slug: 'CUSTOM_MY_TOOLKIT' });
184
uv.lock
+4
-4
@@ -534,7 +534,7 @@ release = [
534
[package.metadata]
535
requires-dist = [
536
{ name = "certifi", specifier = ">=2026.10.19" },
537
- { name = "composio-client", specifier = "==2.0.0" },
537
+ { name = "composio-client", specifier = "==2.0.1" },
538
{ name = "json-schema-to-pydantic", specifier = ">=0.4.11,<1" },
539
{ name = "jsonschema", specifier = ">=4.23.0,<5" },
540
{ name = "openai", specifier = ">=2.48.0,<4" },
@@ -586,16 +586,16 @@ requires-dist = [
586
587
[[package]]
588
name = "composio-client"
589
-version = "2.0.0"
589
+version = "2.0.1"
590
source = { registry = "https://pypi.org/simple" }
591
dependencies = [
592
{ name = "httpx" },
593
{ name = "pydantic" },
594
{ name = "typing-extensions" },
595
]
596
-sdist = { url = "https://files.pythonhosted.org/packages/c8/7b/be475ecbab35280d6f565b689724d350c06491d3412d65b7f69b4b48c76a/composio_client-2.0.0.tar.gz", hash = "sha256:78d852ace33f6c330bf66628f2e794e8f6a333eeed20f740d162160ec0466944", size = 588293, upload-time = "2026-11-03T08:31:56.577Z" }
596
+sdist = { url = "https://files.pythonhosted.org/packages/11/69/0e6e74fcd32748c9c2f58604e92e1a9fd293033231250d61b35d6a7a93e4/composio_client-2.0.1.tar.gz", hash = "sha256:d23d185b5a45f6628263a37db56567bd8dab6b1dabc0de899ea8ce389b29517b", size = 591542, upload-time = "2026-11-03T11:21:56.274Z" }
597
wheels = [
598
- { url = "https://files.pythonhosted.org/packages/5e/be/2ce8fe148ffaa6ad343a8eea6a4f8558c740fca2308970980e7874f6dbf5/composio_client-2.0.0-py3-none-any.whl", hash = "sha256:4de6ef10ae4b731857dd70b6edbf0fd62c4fd41169e5f8d3f21655637c53cfe6", size = 471648, upload-time = "2026-11-03T08:31:54.624Z" },
598
+ { url = "https://files.pythonhosted.org/packages/2e/d7/d4ca7bbbbf4c8b3b2e232e029313a8d59a4dd2f9396683806218f0eefaae/composio_client-2.0.1-py3-none-any.whl", hash = "sha256:e9a24a0883dfa67e19c3d70e0cfe1034cf427411c70edf5e5f4925e4e4d73845", size = 477792, upload-time = "2026-11-03T11:21:54.465Z" },
599
]
600
601
[[package]]