@devries-cameron20 / composio-1 / commits / 83c5346f0
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: correct custom MCP setup guidance (PLEN-3895)

Mukund committed Sep 29, 2026 at 17:40 UTC 83c5346f01db66259dfb247dd2a4dc92a899a2af
1 file changed +19 -17
docs/content/docs/extending-sessions/custom-mcp.mdx
+19 -17
@@ -21,7 +21,7 @@ A Custom MCP moves through this lifecycle:
21 2. **Register** its URL and authentication scheme. Composio creates a project-scoped `CUSTOM_*` toolkit.
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.
24 -5. **Use** the toolkit in a session. For authenticated servers, explicitly select the connected account.
24 +5. **Use** the toolkit in a session. Tool Router matches connected accounts to the session’s `user_id`; selecting an account explicitly is optional.
25
26 <Callout type="warn" title="API-only while Custom MCP is experimental">
27 Use the lifecycle endpoints below to register, 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 [upsert](/reference/api-reference/toolkits/postCustomToolkitsUpsert), [sync](/reference/api-reference/toolkits/postCustomToolkitsSync), and [delete](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug). Dashboard management is coming soon for customers who prefer a UI.
@@ -162,14 +162,20 @@ Choose the mode that matches your server, then complete any required connection:
162 | Authentication | Use it when | After registration |
163 | --- | --- | --- |
164 | No auth | The server accepts requests without credentials. | No connection is required. Initial sync runs automatically. |
165 -| API key | Each connected account supplies an API key. | Create an active connection. Initial sync then starts in the background. |
166 -| DCR OAuth | The server supports OAuth Dynamic Client Registration. | Authorize a connection. Initial sync starts when it becomes active. |
165 +| API key | Each connected account supplies an API key. | Use Tool Router to collect the key and create a connection. Initial sync then starts in the background. |
166 +| DCR OAuth | The server supports OAuth Dynamic Client Registration. | Use Tool Router to start authorization. Initial sync starts when the connection becomes active. |
167
168 For DCR OAuth, the server must support the standard authorization-code flow. Other OAuth grant types aren't supported.
169
170 -### Create the auth config for automatic account matching
170 +### Let Tool Router manage authentication
171
172 -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`:
172 +Add the registered `CUSTOM_*` toolkit to a session. When your agent needs a connection, `COMPOSIO_MANAGE_CONNECTIONS` can create an auth config automatically and return a link for the user to connect. No-auth servers need neither an auth config nor a connection.
173 +
174 +Tool Router reuses eligible connections for the session’s `user_id`. You don't need to create an auth config yourself or pass a connected account ID for this flow.
175 +
176 +### Create an auth config yourself (optional)
177 +
178 +For a setup flow you manage directly through the API, you can create the auth config yourself. Set `is_enabled_for_tool_router` to `true` so Tool Router can use it and match its connected accounts by `user_id`:
179
180 ```bash
181 curl --request POST \
@@ -187,7 +193,7 @@ curl --request POST \
193 }'
194 ```
195
190 -This flag is what lets sessions find the toolkit's connected accounts by `user_id` automatically. Without it, session executions fail with `NoActiveConnection` even when an active account exists, and you must [select the account explicitly](#use-an-authenticated-server) in every session. If you already created the config without the flag, patch it:
196 +Tool Router enables this flag on auth configs it creates automatically. If you created a config yourself without the flag, enable it to make its connections available for automatic matching:
197
198 ```bash
199 curl --request PATCH \
@@ -257,15 +263,7 @@ curl --request DELETE \
263 --header "x-api-key: $COMPOSIO_API_KEY"
264 ```
265
260 -```json
261 -{
262 - "slug": "CUSTOM_ACME",
263 - "deleted": true,
264 - "revoke_job_ids": ["job_123"],
265 - "auth_configs_soft_deleted": 1,
266 - "connected_accounts_soft_deleted": 1
267 -}
268 -```
266 +A successful response confirms the deletion with `deleted: true`. See the [delete endpoint reference](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug) for the full response.
267
268 <Callout type="warn" title="Deletion also removes connections">
269 Deletion removes the custom toolkit and its tools. It also revokes and removes the toolkit's auth configurations and connected accounts. Any replacement starts with new connections.
@@ -313,7 +311,9 @@ With the default search-first session, your agent can discover the custom tools
311
312 ### Use an authenticated server
313
316 -Sessions match a connected account by `user_id` automatically when the toolkit's auth config was [created with `is_enabled_for_tool_router: true`](#create-the-auth-config-for-automatic-account-matching). If your auth config doesn't have that flag, explicitly select the connected account in the session config instead:
314 +Create the session with the toolkit slug as in the example above. Tool Router can [create the auth config and start a connection](#let-tool-router-manage-authentication) when needed, then use the connected account for the session’s `user_id`.
315 +
316 +If you need a specific account, you can pin it explicitly:
317
318 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
319 <Tab value="Python">
@@ -360,6 +360,8 @@ The pinned account must belong to the custom toolkit and be active. Explicit sel
360
361 ## Technical behavior
362
363 +List your custom toolkits with `GET /api/v3.1/toolkits?type=custom`. The `managed_by` filter on the list endpoint is deprecated; use `type=native`, `type=custom`, or `type=all` instead.
364 +
365 Each registered server becomes a custom toolkit scoped to your project:
366
367 - The toolkit has `type: "custom"` and the `CUSTOM` category.
@@ -404,7 +406,7 @@ See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more example
406 </Accordion>
407 <Accordion title="Sessions and tool APIs">
408
407 -- **Automatic account matching requires a flag:** sessions only match a custom toolkit's connected accounts when its auth config has `is_enabled_for_tool_router: true`. Set it at creation (or PATCH it in later); otherwise pass the account ID through `connected_accounts` in Python or `connectedAccounts` in TypeScript.
409 +- **Manually created auth configs:** set `is_enabled_for_tool_router: true` to make their connections available for automatic matching. Tool Router sets this flag on configs it creates automatically.
410 - **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.
411
412 </Accordion>