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(custom-mcp): DCR-only OAuth, existing servers, upsert migration
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H6YzWrR4j8HcSUKs9b7EhV
Bharath committed
Nov 3, 2026 at 17:29 UTC
195382f62ed23f787786b5aeec73b4d94485c453
1 file changed
+13
-5
docs/content/docs/extending-sessions/custom-mcp.mdx
+13
-5
@@ -15,17 +15,17 @@ This is different from [Custom Tools and Toolkits](/docs/extending-sessions/cust
15
16
## How it works
17
18
-1. **Deploy** your MCP server at a public HTTPS URL.
18
+1. **Get** a remote MCP server at a public HTTPS URL: your own, or an existing one.
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.
20
+3. **Connect** an account if the server needs an API key or DCR OAuth.
21
4. Composio **syncs** the tools automatically.
22
5. **Use** the toolkit in a session.
23
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()`.
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()`. See [Move from upsert](#move-from-upsert).
25
26
## Create a toolkit
27
28
-Pass the server's URL, how to authenticate, and `user_id`. Use `"all"` to share the toolkit with every user in your project:
28
+Pass your MCP server's URL as `app_url`, how to authenticate, and `user_id`. Use `"all"` to share the toolkit with every user in your project:
29
30
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
31
<Tab value="Python">
@@ -392,12 +392,20 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
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
395
+## Move from upsert
396
+
397
+`upsert()` and `POST /api/v3.1/custom/toolkits/upsert` still work but are deprecated. Toolkits you created with upsert keep working and keep their slugs.
398
+
399
+- **New toolkit:** call create instead of upsert. Don't pass a slug: create returns one, so save it. Set `user_id` to `"all"` to share the toolkit like upsert did, or to a user's ID to make it private.
400
+- **Existing toolkit:** call update with its slug to change the name, logo, or API key field label. Don't create it again: a second shared toolkit for the same URL returns `409`.
401
+- **Request shape:** create takes the fields directly (`name`, `app_url`, `auth_schemes`, ...), not inside `toolkit_config`.
402
+
403
## Limits
404
405
- Remote servers only: local and STDIO servers aren't supported.
406
- `app_url`, `auth_schemes`, and `user_id` can't change after creation.
407
- At most 500 tools per toolkit.
400
-- OAuth servers that only support Client ID Metadata Documents (CIMD) aren't supported.
408
+- OAuth works only through Dynamic Client Registration (DCR). Servers that need a pre-registered OAuth client, or that only support Client ID Metadata Documents (CIMD), aren't supported.
409
- No automatic resync: sync again when the server's tools change.
410
411
## Related guides