@devries-cameron20 / composio Mirror · read-only / commits / 195382f62
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

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