Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: simplify the Custom MCP guide (PLEN-4800)
Shorter sentences and plain words. One create example plus an auth-mode table instead of nine tabbed examples; the logo becomes a short note; one sync example; troubleshooting and limits replace the technical-behavior and known-gaps sections. Drops the outdated "no dashboard" note. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H6YzWrR4j8HcSUKs9b7EhV
Bharath committed
Nov 3, 2026 at 16:16 UTC
7ecfd411e034506717dd46d1d09cad1f1a4cc98d
1 file changed
+65
-463
docs/content/docs/extending-sessions/custom-mcp.mdx
+65
-463
@@ -5,46 +5,28 @@ keywords: [custom mcp, bring your own mcp, remote mcp, custom toolkits, end user
5
experimental: true
6
---
7
8
-Custom MCP lets you use tools from your remote MCP server in the same session as Composio's built-in toolkits. A Custom MCP is either shared with every user in your project or private to one end user, so your users can bring their own MCP servers. Register the server, connect it if authentication is required, then add its synced `CUSTOM_*` toolkit slug to a session.
8
+Custom MCP lets you add your own remote MCP server to Composio and use its tools in sessions, next to Composio's toolkits. A Custom MCP toolkit is either shared with every user in your project or private to one user, so your users can add their own MCP servers too.
9
10
<Callout type="warn">
11
-Custom MCP is experimental. Its setup flow, authentication options, and API contracts may change while we work with early customers.
11
+Custom MCP is experimental. The APIs may change.
12
</Callout>
13
14
-This is different from [Custom Tools and Toolkits](/docs/extending-sessions/custom-tools-and-toolkits). Custom tools run inside your application. A custom MCP server runs outside Composio and exposes its tools over a public HTTPS endpoint.
14
+This is different from [Custom Tools and Toolkits](/docs/extending-sessions/custom-tools-and-toolkits), which run inside your app. A Custom MCP server runs on its own public HTTPS URL.
15
16
-## Custom MCP lifecycle
17
-
18
-A Custom MCP moves through this lifecycle:
16
+## How it works
17
18
1. **Deploy** your MCP server at a public HTTPS URL.
21
-2. **Register** its URL and authentication scheme. Composio creates a `CUSTOM_*` toolkit, shared or private to one user.
22
-3. **Connect** an account if the server uses an API key or DCR OAuth. No-auth servers skip this step.
23
-4. **Sync** its tools. The first sync starts automatically; later tool changes require a manual sync.
19
+2. **Create** a toolkit for it. Composio gives it a `CUSTOM_*` slug.
20
+3. **Connect** an account if the server needs an API key or OAuth.
21
+4. Composio **syncs** the tools automatically.
22
5. **Use** the toolkit in a session.
23
26
-<Callout type="warn" title="API-only while Custom MCP is experimental">
27
-Use the lifecycle endpoints below to create, update, sync, and delete Custom MCP toolkits. You can also use the experimental SDK methods described below. These contracts may change while Custom MCP is experimental. The API reference has the full request and response schemas for [create](/reference/api-reference/toolkits/postCustomToolkits), [update](/reference/api-reference/toolkits/patchCustomToolkitsBySlug), [sync](/reference/api-reference/toolkits/postCustomToolkitsSync), and [delete](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug). Dashboard management is coming soon for customers who prefer a UI.
28
-</Callout>
29
-
30
-### Manage custom toolkits with the SDK
31
-
32
-You can also run this lifecycle through `composio.experimental.custom_toolkits` in Python or `composio.experimental.customToolkits` in TypeScript. Both provide `create()` to register a toolkit, `update()` to change its name or logo, `sync()` to fetch its remote tool definitions, and `delete()` to remove it and its associated auth configs and connections. `upsert()` is deprecated; use `create()` and `update()`.
33
-
34
-<Callout>
35
-These project-owned toolkit APIs are experimental. They manage remote toolkits registered in Composio; [local custom toolkits](/docs/extending-sessions/custom-tools-and-toolkits) run in your SDK process.
36
-</Callout>
37
-
38
-## Register a Custom MCP
24
+Use the SDK (`composio.experimental.custom_toolkits` in Python, `composio.experimental.customToolkits` in TypeScript) or the API. See the API reference for [create](/reference/api-reference/toolkits/postCustomToolkits), [update](/reference/api-reference/toolkits/patchCustomToolkitsBySlug), [sync](/reference/api-reference/toolkits/postCustomToolkitsSync), and [delete](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug). `upsert()` is deprecated; use `create()` and `update()`.
25
40
-Call `POST /api/v3.1/custom/toolkits` with your public server URL, authentication scheme, and `user_id`. Set `user_id` to `"all"` to share the toolkit with every user in your project, or [to one user's ID](#create-a-toolkit-for-one-end-user). Authenticate the request with your Composio project API key.
26
+## Create a toolkit
27
42
-<Callout type="warn" title="Serve the registered endpoint directly">
43
-Use the final HTTPS MCP endpoint as `app_url`, without redirects. Cross-origin redirects strip `Authorization`, but custom credential headers can remain attached. Custom MCP does not expose a redirect policy that guarantees credentials stay on the registered origin. Keep keys out of the URL. If a credential reaches an untrusted destination, revoke or rotate it at its issuer.
44
-</Callout>
28
+Pass the server's URL, how to authenticate, and `user_id`. Use `"all"` to share the toolkit with every user in your project:
29
46
-<Tabs items={['No auth', 'API key', 'DCR OAuth']}>
47
-<Tab value="No auth">
30
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
31
<Tab value="Python">
32
```python
@@ -87,142 +69,31 @@ curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
69
```
70
</Tab>
71
</Tabs>
90
-</Tab>
91
-<Tab value="API key">
92
-<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
93
-<Tab value="Python">
94
-```python
95
-result = composio.experimental.custom_toolkits.create(
96
- name="Acme",
97
- app_url="https://mcp.acme.com/mcp",
98
- auth_schemes=[
99
- {
100
- "mode": "API_KEY",
101
- "headers": {"Authorization": "Bearer {{generic_api_key}}"},
102
- }
103
- ],
104
- user_id="all",
105
-)
72
107
-print(result.slug) # CUSTOM_ACME
108
-```
109
-</Tab>
110
-<Tab value="TypeScript">
111
-```typescript
112
-import { Composio } from '@composio/core';
113
-const composio = new Composio();
114
-// ---cut---
115
-const result = await composio.experimental.customToolkits.create({
116
- name: 'Acme',
117
- appUrl: 'https://mcp.acme.com/mcp',
118
- authSchemes: [
119
- { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
120
- ],
121
- userId: 'all',
122
-});
73
+Composio picks the slug from the server's domain, and adds a random suffix if it's taken. Save the slug: you need it to sync, update, or delete the toolkit.
74
124
-console.log(result.slug); // CUSTOM_ACME
125
-```
126
-</Tab>
127
-<Tab value="API">
128
-```bash
129
-curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
130
- -H "x-api-key: $COMPOSIO_API_KEY" \
131
- -H "Content-Type: application/json" \
132
- -d '{
133
- "name": "Acme",
134
- "app_url": "https://mcp.acme.com/mcp",
135
- "auth_schemes": [
136
- {
137
- "mode": "API_KEY",
138
- "headers": {"Authorization": "Bearer {{generic_api_key}}"}
139
- }
140
- ],
141
- "user_id": "all"
142
- }'
143
-```
144
-</Tab>
145
-</Tabs>
146
-
147
-`generic_api_key` is replaced with the credential stored on the connected account. You can use a different header name or value format, but at least one header value must contain `{{generic_api_key}}`.
148
-</Tab>
149
-<Tab value="DCR OAuth">
150
-<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
151
-<Tab value="Python">
152
-```python
153
-result = composio.experimental.custom_toolkits.create(
154
- name="Acme",
155
- app_url="https://mcp.acme.com/mcp",
156
- auth_schemes=[
157
- {
158
- "mode": "DCR_OAUTH",
159
- "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server",
160
- }
161
- ],
162
- user_id="all",
163
-)
75
+`app_url`, `auth_schemes`, and `user_id` can't change later. To change them, delete the toolkit and create it again.
76
165
-print(result.slug) # CUSTOM_ACME
166
-```
167
-</Tab>
168
-<Tab value="TypeScript">
169
-```typescript
170
-import { Composio } from '@composio/core';
171
-const composio = new Composio();
172
-// ---cut---
173
-const result = await composio.experimental.customToolkits.create({
174
- name: 'Acme',
175
- appUrl: 'https://mcp.acme.com/mcp',
176
- authSchemes: [
177
- {
178
- mode: 'DCR_OAUTH',
179
- discoveryUrl: 'https://mcp.acme.com/.well-known/oauth-authorization-server',
180
- },
181
- ],
182
- userId: 'all',
183
-});
77
+<Callout type="warn" title="Use the final URL">
78
+Set `app_url` to the final MCP endpoint, with no redirects: a redirect can send credentials to another host. Don't put keys in the URL.
79
+</Callout>
80
185
-console.log(result.slug); // CUSTOM_ACME
186
-```
187
-</Tab>
188
-<Tab value="API">
189
-```bash
190
-curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
191
- -H "x-api-key: $COMPOSIO_API_KEY" \
192
- -H "Content-Type: application/json" \
193
- -d '{
194
- "name": "Acme",
195
- "app_url": "https://mcp.acme.com/mcp",
196
- "auth_schemes": [
197
- {
198
- "mode": "DCR_OAUTH",
199
- "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server"
200
- }
201
- ],
202
- "user_id": "all"
203
- }'
204
-```
205
-</Tab>
206
-</Tabs>
207
-</Tab>
208
-</Tabs>
81
+### Choose how users authenticate
82
210
-Composio picks the slug from the server's domain and adds a random suffix if that slug is taken. Store it: you need it to sync, update, or delete the toolkit.
83
+Set `auth_schemes` to one of these:
84
212
-```json
213
-{
214
- "slug": "CUSTOM_ACME",
215
- "connect_link": null
216
-}
217
-```
85
+| Mode | Use it when | `auth_schemes` |
86
+| --- | --- | --- |
87
+| No auth | The server needs no credentials. | `[{"mode": "NO_AUTH"}]` |
88
+| API key | Each user brings an API key. | `[{"mode": "API_KEY", "headers": {"Authorization": "Bearer {{generic_api_key}}"}}]` |
89
+| DCR OAuth | The server supports OAuth Dynamic Client Registration. | `[{"mode": "DCR_OAUTH", "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server"}]` |
90
219
-<Callout type="warn" title="app_url, auth_schemes, and user_id are immutable">
220
-`app_url`, `auth_schemes`, and `user_id` can't change after creation. To change the name, logo, or API key field label, [update the toolkit](#update-a-toolkit). To change anything else, [delete the toolkit](#delete-or-replace-a-custom-mcp) and create it again.
221
-</Callout>
91
+- **API key:** Composio replaces `{{generic_api_key}}` with the user's key. Any header name works, but at least one header must contain `{{generic_api_key}}`. Composio only checks that a key was given, so run a safe tool after connecting to test it.
92
+- **DCR OAuth:** `discovery_url` is the OAuth authorization server's metadata URL. The server must support the authorization-code flow. Client ID Metadata Documents (CIMD) aren't supported. Composio sends a `resource` parameter: the one the server advertises, or else `app_url` without its query string or trailing slash.
93
223
-### Create a toolkit for one end user
94
+### Create a toolkit for one user
95
225
-Set `user_id` to an end user's ID to make the toolkit private to them: only sessions and API calls for that user can see or run its tools. A private toolkit's slug always has a random suffix, such as `CUSTOM_ACME_K7F2Q`.
96
+Set `user_id` to a user's ID to make the toolkit private: only that user's sessions and API calls can see or run its tools. A private toolkit's slug always has a random suffix, such as `CUSTOM_ACME_K7F2Q`.
97
98
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
99
<Tab value="Python">
@@ -301,174 +172,24 @@ curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
172
}
173
```
174
304
-For a private toolkit that needs authentication, `connect_link` is a hosted connect page for that user. Send them to `redirect_url`; once they connect, the tools sync automatically. `connect_link` is `null` for no-auth and shared toolkits, or if the link couldn't be created. To get a new link, call [`POST /api/v3.1/connected_accounts/link`](/reference/api-reference/connected-accounts/postConnectedAccountsLink).
305
-
306
-A second private toolkit for the same user and MCP URL returns `409 Conflict`, as does a second shared toolkit for the same URL. `"default"` and other spellings of `"all"`, such as `"ALL"`, return `400`.
307
-
308
-## Add a toolkit logo
175
+If the server needs auth, send the user to `connect_link.redirect_url`. Once they connect, the tools sync. `connect_link` is `null` for shared and no-auth toolkits. To get a new link, call [`POST /api/v3.1/connected_accounts/link`](/reference/api-reference/connected-accounts/postConnectedAccountsLink).
176
310
-Without a logo, your toolkit shows the Composio logo in the dashboard and on end-user connect screens. To ship your own branding, include `logo_file` when you create the toolkit: the image itself, base64-encoded. Composio validates it, stores it on Composio-hosted asset storage, and renders it everywhere the toolkit appears. You don't host anything, and the logo keeps working even if your own site changes or goes down.
177
+Creating the same MCP URL twice for one user, or twice as shared, returns `409`. `"default"` and other spellings of `"all"` (such as `"ALL"`) return `400`.
178
312
-Save your PNG as `logo.png`. This example creates the `NO_AUTH` toolkit above with a logo; use the auth scheme you selected.
313
-
314
-<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
315
-<Tab value="Python">
316
-```python
317
-from base64 import b64encode
318
-from pathlib import Path
319
-from composio import Composio
179
+### Add a logo
180
321
-composio = Composio()
322
-logo_content = b64encode(Path("logo.png").read_bytes()).decode("ascii")
323
-result = composio.experimental.custom_toolkits.create(
324
- name="Acme",
325
- app_url="https://mcp.acme.com/mcp",
326
- logo_file={
327
- "content": logo_content,
328
- "mime_type": "image/png",
329
- },
330
- auth_schemes=[{"mode": "NO_AUTH"}],
331
- user_id="all",
332
-)
181
+Add `logo_file` to create or update: a square PNG or JPEG, 256 to 1024 pixels, at most 3MB, base64-encoded on one line. Composio hosts it. Without one, the toolkit shows the Composio logo.
182
334
-print(result.slug) # CUSTOM_ACME
335
-```
336
-</Tab>
337
-<Tab value="TypeScript">
338
-```typescript
339
-import { Composio } from '@composio/core';
340
-import { readFileSync } from 'node:fs';
341
-const composio = new Composio();
342
-// ---cut---
343
-const logoContent = readFileSync('logo.png').toString('base64');
344
-const result = await composio.experimental.customToolkits.create({
345
- name: 'Acme',
346
- appUrl: 'https://mcp.acme.com/mcp',
347
- logoFile: {
348
- content: logoContent,
349
- mimeType: 'image/png',
350
- },
351
- authSchemes: [{ mode: 'NO_AUTH' }],
352
- userId: 'all',
353
-});
354
-
355
-console.log(result.slug); // CUSTOM_ACME
356
-```
357
-</Tab>
358
-<Tab value="API">
359
-```bash
360
-set -euo pipefail
361
-LOGO_BASE64=$(base64 < logo.png | tr -d '\n')
362
-curl --fail-with-body -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
363
- -H "x-api-key: $COMPOSIO_API_KEY" \
364
- -H "Content-Type: application/json" \
365
- -d '{
366
- "name": "Acme",
367
- "app_url": "https://mcp.acme.com/mcp",
368
- "logo_file": {
369
- "content": "'"$LOGO_BASE64"'",
370
- "mime_type": "image/png"
371
- },
372
- "auth_schemes": [{"mode": "NO_AUTH"}],
373
- "user_id": "all"
374
- }'
375
-```
376
-</Tab>
377
-</Tabs>
378
-
379
-Set `content` to your image encoded as base64: a single line, with no line breaks or whitespace. The image must be:
380
-
381
-- **PNG or JPEG** (`mime_type` of `image/png` or `image/jpeg`)
382
-- **Square**, between 256 and 1024 pixels
383
-- **At most 3MB** before encoding
384
-
385
-Omit `logo_file` to keep the Composio default.
386
-
387
-## Update a toolkit
388
-
389
-Call `PATCH /api/v3.1/custom/toolkits/{slug}` to change `name`, `logo_file`, or the API key field's label (`api_key_field`). Omitted fields keep their value. On a project with 2FA enabled, updating a private toolkit requires the `user_id` it is private to.
390
-
391
-This example replaces the logo:
392
-
393
-<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
394
-<Tab value="Python">
395
-```python
396
-from base64 import b64encode
397
-from pathlib import Path
398
-from composio import Composio
399
-
400
-composio = Composio()
401
-logo_content = b64encode(Path("logo.png").read_bytes()).decode("ascii")
402
-result = composio.experimental.custom_toolkits.update(
403
- "CUSTOM_ACME",
404
- logo_file={
405
- "content": logo_content,
406
- "mime_type": "image/png",
407
- },
408
-)
409
-
410
-print(result.success) # True
411
-```
412
-</Tab>
413
-<Tab value="TypeScript">
414
-```typescript
415
-import { Composio } from '@composio/core';
416
-import { readFileSync } from 'node:fs';
417
-const composio = new Composio();
418
-// ---cut---
419
-const logoContent = readFileSync('logo.png').toString('base64');
420
-const result = await composio.experimental.customToolkits.update('CUSTOM_ACME', {
421
- logoFile: {
422
- content: logoContent,
423
- mimeType: 'image/png',
424
- },
425
-});
426
-
427
-console.log(result.success); // true
428
-```
429
-</Tab>
430
-<Tab value="API">
431
-```bash
432
-set -euo pipefail
433
-LOGO_BASE64=$(base64 < logo.png | tr -d '\n')
434
-curl --fail-with-body -X PATCH https://backend.composio.dev/api/v3.1/custom/toolkits/CUSTOM_ACME \
435
- -H "x-api-key: $COMPOSIO_API_KEY" \
436
- -H "Content-Type: application/json" \
437
- -d '{
438
- "logo_file": {
439
- "content": "'"$LOGO_BASE64"'",
440
- "mime_type": "image/png"
441
- }
442
- }'
183
+```json
184
+"logo_file": {"content": "<base64>", "mime_type": "image/png"}
185
```
444
-</Tab>
445
-</Tabs>
446
-
447
-## Complete setup for your authentication mode
448
-
449
-Choose the mode that matches your server, then complete any required connection:
450
-
451
-| Authentication | Use it when | After registration |
452
-| --- | --- | --- |
453
-| No auth | The server accepts requests without credentials. | No connection is required. Initial sync runs automatically. |
454
-| API key | Each connected account supplies an API key. | Create an active connection. Initial sync then starts in the background. |
455
-| DCR OAuth | The server supports OAuth Dynamic Client Registration. | Authorize a connection. Initial sync starts when it becomes active. |
456
-
457
-For DCR OAuth, the server must support the standard authorization-code flow and compatible OAuth client registration. Other OAuth grant types aren't supported. Client ID Metadata Documents (CIMD) are not supported for customer-created Custom MCP toolkits. A server that only supports CIMD cannot complete this OAuth flow.
458
-
459
-If that server also supports API-token authentication, you can register a separate API-key Custom MCP using the server's documented header format. Connect each intended account with its own token. That token determines the identity and permissions used by the server.
460
-
461
-### OAuth discovery metadata
462
-
463
-`discovery_url` points to **authorization-server metadata** that supplies the OAuth endpoints and client-registration information. A protected-resource metadata document serves a different purpose and is not interchangeable with it. An OpenID configuration document can work when it supplies the OAuth information this flow needs.
464
-
465
-Registration also attempts protected-resource discovery from `app_url`. Successful registration does not prove that OAuth setup is complete: authorize a connection, sync the tools, and run a safe read-only tool to verify the full path.
186
467
-DCR OAuth sends a `resource` parameter during authorization, authorization-code exchange, and refresh. When protected-resource discovery succeeds, Composio uses the advertised resource identifier exactly. Otherwise, a project-scoped Custom MCP falls back to `app_url` with its path retained and its query, fragment, and trailing slash removed. The authorization-server URL is not the default resource identifier.
187
+## Connect and sync
188
469
-## Sync and resync tools
189
+- **No auth:** tools sync when you create the toolkit.
190
+- **API key or DCR OAuth:** tools sync when the first account connects.
191
471
-Call `POST /api/v3.1/custom/toolkits/sync` to fetch the server's current tools:
192
+Sync again only if that first sync fails or the server's tools change. Pass an active connected account, or leave it out for a no-auth server:
193
194
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
195
<Tab value="Python">
@@ -503,14 +224,18 @@ curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/sync \
224
</Tab>
225
</Tabs>
226
506
-For an API-key or DCR OAuth server, `connected_account_id` must identify an active account from the same toolkit and project. For a no-auth server, omit it:
227
+A toolkit can have at most 500 tools. If the server has more, the sync fails and the last good version stays.
228
+
229
+## Update a toolkit
230
+
231
+Update changes `name`, `logo_file`, or the API key field's label (`api_key_field`). Fields you leave out stay the same. If your project has 2FA on, updating a private toolkit needs its `user_id`.
232
233
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
234
<Tab value="Python">
235
```python
511
-result = composio.experimental.custom_toolkits.sync("CUSTOM_ACME")
236
+result = composio.experimental.custom_toolkits.update("CUSTOM_ACME", name="Acme (prod)")
237
513
-print(result.version, result.synced_count)
238
+print(result.success) # True
239
```
240
</Tab>
241
<Tab value="TypeScript">
@@ -518,47 +243,26 @@ print(result.version, result.synced_count)
243
import { Composio } from '@composio/core';
244
const composio = new Composio();
245
// ---cut---
521
-const result = await composio.experimental.customToolkits.sync('CUSTOM_ACME');
246
+const result = await composio.experimental.customToolkits.update('CUSTOM_ACME', {
247
+ name: 'Acme (prod)',
248
+});
249
523
-console.log(result.version, result.syncedCount);
250
+console.log(result.success); // true
251
```
252
</Tab>
253
<Tab value="API">
254
```bash
528
-curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/sync \
255
+curl -X PATCH https://backend.composio.dev/api/v3.1/custom/toolkits/CUSTOM_ACME \
256
-H "x-api-key: $COMPOSIO_API_KEY" \
257
-H "Content-Type: application/json" \
531
- -d '{"slug": "CUSTOM_ACME"}'
258
+ -d '{"name": "Acme (prod)"}'
259
```
260
</Tab>
261
</Tabs>
262
536
-A successful sync returns the toolkit version and the number of tools discovered:
537
-
538
-```json
539
-{
540
- "slug": "CUSTOM_ACME",
541
- "version": "20260728_00",
542
- "synced_count": 12
543
-}
544
-```
545
-
546
-<Callout type="info" title="When to sync manually">
547
-Composio starts the initial sync automatically:
548
-
549
-- **No auth:** during registration
550
-- **API key or DCR OAuth:** when the first connected account becomes active
551
-
552
-Call the sync endpoint only if the initial sync fails or the server's tool definitions change. Later connections don't resync a toolkit that already has tools.
553
-</Callout>
554
-
555
-A Custom MCP toolkit can contain at most 500 tools. If the server returns more than 500, the sync fails without importing a partial tool list. The last successful version stays available.
556
-
557
-## Delete or replace a Custom MCP
263
+## Delete a toolkit
264
559
-[Update](#update-a-toolkit) changes the name and logo, but `app_url`, `auth_schemes`, and `user_id` can't change. To replace one, delete the toolkit and create it again.
560
-
561
-Call `DELETE /api/v3.1/custom/toolkits/{slug}`:
265
+Delete removes the toolkit and its tools, auth configs, and connected accounts.
266
267
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
268
<Tab value="Python">
@@ -586,23 +290,11 @@ curl -X DELETE https://backend.composio.dev/api/v3.1/custom/toolkits/CUSTOM_ACME
290
</Tab>
291
</Tabs>
292
589
-A successful response confirms the deletion with `deleted: true`. By default, toolkit deletion also starts background revocation jobs and returns their `revoke_job_ids`. Pass `?revoke_on_delete=false` to skip those jobs. This differs from [deleting one connected account](/reference/api-reference/connected-accounts/deleteConnectedAccountsByNanoid), where revocation defaults to `false`. See the [toolkit delete endpoint reference](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug) for the full response.
590
-
591
-<Callout type="warn" title="Deletion also removes connections">
592
-Deletion removes the custom toolkit and its tools, auth configurations, and connected accounts. Any replacement starts with new connections. A successful deletion or a started revocation job does not prove that the remote server has invalidated its credentials.
593
-</Callout>
594
-
595
-Custom MCP DCR OAuth credentials are not currently revoked through Composio's connected-account revocation implementation. API-key revocation requires a configured provider-specific operation; storing `generic_api_key` alone does not provide one. Revoke the grant or key at its issuer when you need to invalidate it there.
596
-
597
-Deletion blocks subsequent account lookups. It does not guarantee cancellation of operations that already resolved credentials, immediate credential purging, or removal of earlier execution logs. See [connected-account deletion](/reference/api-reference/connected-accounts/deleteConnectedAccountsByNanoid) and [data retention](/docs/security/data-retention) for the separate lifecycle controls.
598
-
599
-## Use Custom MCP in a session
293
+By default, delete also starts jobs to revoke the accounts' credentials and returns their `revoke_job_ids`. Pass `?revoke_on_delete=false` to skip them. DCR OAuth grants and API keys usually aren't revoked on the server's side, so revoke them there if you need to. Delete doesn't stop calls already in progress or remove past [execution logs](/docs/security/data-retention).
294
601
-Once the toolkit is synced, add its `CUSTOM_*` slug to a session.
295
+## Use the toolkit in a session
296
603
-### Create a session
604
-
605
-Pass the toolkit slug when you create the session:
297
+Add the slug to a session. A session only sees the custom toolkits its `user_id` can use: naming another user's private toolkit returns `400`, and running its tools returns `403`.
298
299
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
300
<Tab value="Python">
@@ -645,13 +337,7 @@ curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_I
337
</Tab>
338
</Tabs>
339
648
-A session only sees the custom toolkits its `user_id` can use. Naming another user's private toolkit in `toolkits` returns `400`, and executing its tools returns `403`.
649
-
650
-With the default search-first session, your agent uses `COMPOSIO_SEARCH_TOOLS` to discover the custom tools and the Tool Router to execute them. If a synced tool is missing from search, see [troubleshooting discovery](#troubleshoot-missing-search-results).
651
-
652
-### Use an authenticated server
653
-
654
-Sessions automatically match connected accounts by `user_id`. If you created the auth config yourself, [set `is_enabled_for_tool_router: true`](/reference/api-reference/auth-configs/patchAuthConfigsByNanoid) to enable automatic account matching. To select a specific connected account, pass its ID in the session configuration:
340
+Your agent finds the tools with `COMPOSIO_SEARCH_TOOLS`. Sessions pick the user's connected account automatically. If you created the auth config yourself, [set `is_enabled_for_tool_router: true`](/reference/api-reference/auth-configs/patchAuthConfigsByNanoid) on it. To use a specific account, pass it in the session:
341
342
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
343
<Tab value="Python">
@@ -697,105 +383,21 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
383
</Tab>
384
</Tabs>
385
700
-The pinned account must belong to the custom toolkit and be active. Explicit selection ensures tool calls use its credentials.
701
-
702
-## What you manage and what Composio handles
703
-
704
-| Area | You manage | Composio handles |
705
-| --- | --- | --- |
706
-| Server | Deploying and operating the remote MCP server at a public HTTPS URL. | Connecting to the URL for tool discovery and execution. Composio does not host the server. |
707
-| Tools | Implementing tools and deciding when later definition changes are ready to sync. | Starting the initial sync, importing tool schemas, versioning them, and exposing them to sessions. |
708
-| Authentication | Implementing the server's API-key or DCR OAuth behavior and completing each required connection. | Storing connected-account credentials and sending them when discovering or calling tools. |
709
-| Lifecycle | Choosing when to resync, delete, or replace the toolkit. | Providing the project-scoped registration, sync, and deletion operations. |
710
-
711
-## Technical behavior
712
-
713
-List your custom toolkits with `GET /api/v3.1/toolkits?type=custom`. Add `user_id` to include the toolkits private to that user; each toolkit's `access` is `"all"` or `"user"`.
714
-
715
-Each registered server becomes a custom toolkit scoped to your project:
716
-
717
-- The toolkit has `type: "custom"` and the `CUSTOM` category.
718
-- Its slug starts with `CUSTOM_`, such as `CUSTOM_ACME`.
719
-- Its tools are exposed through Tool Router search and toolkit-filtered tool listing, subject to the [search limitation below](#troubleshoot-missing-search-results).
720
-- Tool execution is proxied to your MCP server with the selected connected account's credentials.
721
-
722
-On v3, `GET /api/v3/tools?toolkit_slug=CUSTOM_ACME` can return an empty list even after a successful sync. This is *not* a sync failure: v3 reads from a pinned toolkit version by default, and custom tools only exist in the latest version. Add `toolkit_versions=latest` to the request, or use v3.1, which always resolves the latest version:
723
-
724
-<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
725
-<Tab value="Python">
726
-```python
727
-from composio import Composio
728
-
729
-composio = Composio()
730
-tools = composio.client.get(
731
- "/api/v3/tools",
732
- cast_to=object,
733
- query={"toolkit_slug": "CUSTOM_ACME", "toolkit_versions": "latest"},
734
-)
735
-print(tools)
736
-```
737
-</Tab>
738
-<Tab value="TypeScript">
739
-```typescript
740
-import { Composio } from '@composio/core';
741
-
742
-const composio = new Composio();
743
-const tools = await composio.getClient().get<unknown>('/api/v3/tools', {
744
- query: { toolkit_slug: 'CUSTOM_ACME', toolkit_versions: 'latest' },
745
-});
746
-console.log(tools);
747
-```
748
-</Tab>
749
-<Tab value="API">
750
-{/* code-example: unchecked-api rule="api-legacy-version" operation="GET /api/v3/tools" reason="this example deliberately demonstrates the previous REST version's toolkit_versions=latest workaround" */}
751
-```bash
752
-curl -X GET "https://backend.composio.dev/api/v3/tools?toolkit_slug=CUSTOM_ACME&toolkit_versions=latest" \
753
- -H "x-api-key: $COMPOSIO_API_KEY"
754
-```
755
-</Tab>
756
-</Tabs>
757
-
758
-Custom toolkits use dated registry versions. The v3.1 tools API selects the latest version by default. If you use v3 directly, select the latest version for each operation:
759
-
760
-| v3 operation | Select the latest version |
761
-| --- | --- |
762
-| List tools | Add the `toolkit_versions=latest` query parameter. |
763
-| Retrieve one tool | Add the `version=latest` query parameter. |
764
-| Execute one tool | Set `"version": "latest"` in the request body. |
765
-
766
-See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more examples.
767
-
768
-### Troubleshoot missing search results
769
-
770
-Custom MCP tools can sync and execute successfully while remaining absent from `COMPOSIO_SEARCH_TOOLS` results. This is a known search-path issue, separate from the 500-tool limit on syncing one toolkit.
771
-
772
-First, confirm that toolkit-filtered listing or `COMPOSIO_GET_TOOL_SCHEMAS` returns the expected tool. If it does, a missing search result does not mean the tool failed to sync. You can use the known slug with `COMPOSIO_MULTI_EXECUTE_TOOL` while the search issue is investigated. Inspect the schema and choose a safe read-only call when verifying execution.
773
-
774
-Reconnects and repeated syncs do not bypass the search-path limit, and there is no customer re-index operation for it. Report the toolkit slug, UTC timestamp, and search and schema/execution log IDs to support.
775
-
776
-## Known gaps
777
-
778
-<Accordions>
779
-<Accordion title="Setup and lifecycle">
780
-
781
-- **Dashboard coming soon:** Custom MCP management isn't available in the dashboard yet.
782
-- **Remote servers only:** Composio doesn't host your server. Deploy it at a public HTTPS endpoint; local and STDIO-only servers aren't supported.
783
-- **Immutable `app_url`, `auth_schemes`, and `user_id`:** Update changes only the name, logo, and API key field label. Delete the toolkit and create it again to change anything else. Deletion also removes its auth configurations and connected accounts.
784
-- **500-tool limit:** Split larger servers into smaller MCP servers. If a later sync exceeds the limit, the last successful version stays available.
386
+## List your toolkits
387
786
-</Accordion>
787
-<Accordion title="Sync and authentication">
388
+`GET /api/v3.1/toolkits?type=custom` lists your shared custom toolkits. Add `user_id` to include that user's private ones. Each toolkit's `access` is `"all"` (shared) or `"user"` (private).
389
789
-- **No continuous sync:** Auto-sync only populates an empty toolkit during registration or the first active connection. If it fails, call the sync endpoint with an active connected account. Sync again whenever tool definitions change.
790
-- **API-key validation is limited:** Setup checks that a key was provided, not that the remote server accepts it. Run a safe tool after connecting to verify the credential end to end.
390
+## Troubleshooting
391
792
-</Accordion>
793
-<Accordion title="Sessions and tool APIs">
392
+- **Tools missing from search:** search can miss custom tools that synced fine. Check with toolkit-filtered tool listing or `COMPOSIO_GET_TOOL_SCHEMAS`, then call the tool by slug with `COMPOSIO_MULTI_EXECUTE_TOOL`. Resyncing doesn't help; send the slug, time (UTC), and log IDs to support.
393
+- **Empty tool list on v3:** the v3 tools API reads a pinned toolkit version that has no custom tools. Use v3.1, or ask for the latest version: `toolkit_versions=latest` to list tools, `version=latest` to get one, or `"version": "latest"` in the body to execute. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning).
394
795
-- **Prefer the v3.1 tools API:** The v3 tools API pins a default version that doesn't contain custom tools. If you must use v3, explicitly select `latest` as described above.
395
+## Limits
396
797
-</Accordion>
798
-</Accordions>
397
+- Remote servers only: local and STDIO servers aren't supported.
398
+- `app_url`, `auth_schemes`, and `user_id` can't change after creation.
399
+- At most 500 tools per toolkit.
400
+- No automatic resync: sync again when the server's tools change.
401
402
## Related guides
403