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, 16:00 UTC
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>