@devries-cameron20 / composio-1 / commits / 1c183990c
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.

docs(custom-mcp): auth config is a required step, v3 version pinning, true-upsert semantics

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

shams haroon committed Aug 12, 2026 at 12:30 UTC 1c183990cfc2551b2516324cceb3bc56f73fb51a
1 file changed +15 -9
docs/content/docs/extending-sessions/custom-mcp.mdx
+15 -9
@@ -108,10 +108,8 @@ Composio adds the `CUSTOM_` prefix and returns the normalized toolkit slug:
108 }
109 ```
110
111 -<Callout type="warn" title="This endpoint only registers new toolkits">
112 -Despite `upsert` in the route name, this endpoint does not update or replace an existing toolkit. If the slug already exists, the request returns `409 Conflict`.
113 -
114 -To change the server URL, name, or authentication scheme, [delete the existing toolkit](#delete-or-replace-a-custom-mcp), then register it again. Deletion also revokes and removes the toolkit's auth configurations and connected accounts.
111 +<Callout type="warn" title="app_url and auth_schemes are immutable">
112 +Re-registering a slug your project already owns updates the toolkit in place: mutable fields like the name and logo take the new values, and an identical config is a harmless no-op. Two fields can't change after registration: `app_url` and `auth_schemes`. Changing either returns `409 Conflict`; [delete the existing toolkit](#delete-or-replace-a-custom-mcp), then register it again.
113 </Callout>
114
115 ## Add a toolkit logo
@@ -147,7 +145,7 @@ Set `content` to your image encoded as base64: a single line, with no line break
145 - **Square**, between 256 and 1024 pixels
146 - **At most 3MB** before encoding
147
150 -Omit `logo_file` to keep the Composio default. Because registration is insert-only, changing a logo later means deleting the toolkit and registering it again with the new image.
148 +Omit `logo_file` to keep the Composio default. To change a logo later, re-register the same slug with the new image: the upsert updates the toolkit in place.
149
150 ## Complete setup for your authentication mode
151
@@ -163,7 +161,7 @@ For DCR OAuth, the server must support the standard authorization-code flow. Oth
161
162 ### Create the auth config for automatic account matching
163
166 -For API-key and DCR OAuth servers, create the toolkit's auth config with `is_enabled_for_tool_router` set to `true`:
164 +Registering a toolkit does not create an auth config. For API-key and DCR OAuth servers, creating one yourself is a *required* separate step: without an auth config there is nothing for end users to connect to, and the toolkit's tools can't authenticate. Create it right after registration, with `is_enabled_for_tool_router` set to `true` so sessions can match connected accounts by `user_id`:
165
166 ```bash
167 curl --request POST \
@@ -188,7 +186,7 @@ curl --request PATCH \
186 --url https://backend.composio.dev/api/v3.1/auth_configs/ac_xxxxxxxx \
187 --header "x-api-key: $COMPOSIO_API_KEY" \
188 --header "Content-Type: application/json" \
191 - --data '{ "is_enabled_for_tool_router": true }'
189 + --data '{ "type": "custom", "is_enabled_for_tool_router": true }'
190 ```
191
192 ## Sync and resync tools
@@ -241,7 +239,7 @@ A Custom MCP toolkit can contain at most 500 tools. If the server returns more t
239
240 ## Delete or replace a Custom MCP
241
244 -The registration endpoint cannot update an existing toolkit. To replace its URL, name, or authentication scheme, delete the toolkit and register it again.
242 +Re-registering a slug updates mutable fields like the name and logo, but `app_url` and `auth_schemes` can't change after registration. To replace either, delete the toolkit and register it again.
243
244 Call `DELETE /api/v3.1/custom/toolkits/{slug}`:
245
@@ -361,6 +359,14 @@ Each registered server becomes a custom toolkit scoped to your project:
359 - Its tools are available through Tool Router search and toolkit-filtered tool listing.
360 - Tool execution is proxied to your MCP server with the selected connected account's credentials.
361
362 +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:
363 +
364 +```bash
365 +curl --request GET \
366 + --url "https://backend.composio.dev/api/v3/tools?toolkit_slug=CUSTOM_ACME&toolkit_versions=latest" \
367 + --header "x-api-key: $COMPOSIO_API_KEY"
368 +```
369 +
370 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:
371
372 | v3 operation | Select the latest version |
@@ -379,7 +385,7 @@ See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more example
385 - **API-only setup:** The SDKs don't expose registration, sync, update, or deletion methods yet. Use the lifecycle endpoints on this page, then use the toolkit slug through the SDK.
386 - **Dashboard coming soon:** Custom MCP management isn't available in the dashboard yet.
387 - **Remote servers only:** Composio doesn't host your server. Deploy it at a public HTTPS endpoint; local and STDIO-only servers aren't supported.
382 -- **Insert-only registration:** The `upsert` endpoint returns `409 Conflict` for an existing slug. Delete the toolkit, then register it again. Deletion also removes its auth configurations and connected accounts.
388 +- **Immutable `app_url` and `auth_schemes`:** Re-registering an existing slug updates other fields in place, but changing `app_url` or `auth_schemes` returns `409 Conflict`. Delete the toolkit, then register it again. Deletion also removes its auth configurations and connected accounts.
389 - **500-tool limit:** Split larger servers into smaller MCP servers. If a later sync exceeds the limit, the last successful version stays available.
390
391 </Accordion>