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, 08:30 UTC
docs: correct Custom MCP auth, revocation, and discovery guidance
Vinayak Agarwal committed
Oct 20, 2026 at 13:09 UTC
86ad9894ea6969c83c7aa90b6615c78c5affb44d
1 file changed
+32
-6
docs/content/docs/extending-sessions/custom-mcp.mdx
+32
-6
@@ -1,7 +1,7 @@
1
---
2
title: Custom MCP
3
description: Use tools from a remote MCP server in Composio sessions
4
-keywords: [custom mcp, bring your own mcp, remote mcp, custom toolkits, experimental]
4
+keywords: [custom mcp, bring your own mcp, remote mcp, custom toolkits, experimental, dcr, cimd, discovery, revocation]
5
experimental: true
6
---
7
@@ -39,6 +39,10 @@ These project-owned toolkit APIs are experimental. They manage remote toolkits r
39
40
Call `POST /api/v3.1/custom/toolkits/upsert` with your public server URL and authentication scheme. Authenticate the request with your Composio project API key.
41
42
+<Callout type="warn" title="Serve the registered endpoint directly">
43
+Use the final HTTPS MCP endpoint as `app_url`, without redirects. Cross-origin redirects strip `Authorization`, but custom credential headers can remain attached. Custom MCP does not expose a redirect policy that guarantees credentials stay on the registered origin. Keep keys out of the URL. If a credential reaches an untrusted destination, revoke or rotate it at its issuer.
44
+</Callout>
45
+
46
<Tabs items={['No auth', 'API key', 'DCR OAuth']}>
47
<Tab value="No auth">
48
```bash
@@ -165,7 +169,17 @@ Choose the mode that matches your server, then complete any required connection:
169
| API key | Each connected account supplies an API key. | Create an active connection. Initial sync then starts in the background. |
170
| DCR OAuth | The server supports OAuth Dynamic Client Registration. | Authorize a connection. Initial sync starts when it becomes active. |
171
168
-For DCR OAuth, the server must support the standard authorization-code flow. Other OAuth grant types aren't supported.
172
+For DCR OAuth, the server must support the standard authorization-code flow and compatible OAuth client registration. Other OAuth grant types aren't supported. Client ID Metadata Documents (CIMD) are not supported for customer-created Custom MCP toolkits. A server that only supports CIMD cannot complete this OAuth flow.
173
+
174
+If that server also supports API-token authentication, you can register a separate API-key Custom MCP using the server's documented header format. Connect each intended account with its own token. That token determines the identity and permissions used by the server.
175
+
176
+### OAuth discovery metadata
177
+
178
+`discovery_url` points to **authorization-server metadata** that supplies the OAuth endpoints and client-registration information. A protected-resource metadata document serves a different purpose and is not interchangeable with it. An OpenID configuration document can work when it supplies the OAuth information this flow needs.
179
+
180
+Registration also attempts protected-resource discovery from `app_url`. Successful registration does not prove that OAuth setup is complete: authorize a connection, sync the tools, and run a safe read-only tool to verify the full path.
181
+
182
+DCR OAuth sends a `resource` parameter during authorization, authorization-code exchange, and refresh. When protected-resource discovery succeeds, Composio uses the advertised resource identifier exactly. Otherwise, a project-scoped Custom MCP falls back to `app_url` with its path retained and its query, fragment, and trailing slash removed. The authorization-server URL is not the default resource identifier.
183
184
## Sync and resync tools
185
@@ -227,12 +241,16 @@ curl --request DELETE \
241
--header "x-api-key: $COMPOSIO_API_KEY"
242
```
243
230
-A successful response confirms the deletion with `deleted: true`. See the [delete endpoint reference](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug) for the full response.
244
+A successful response confirms the deletion with `deleted: true`. By default, toolkit deletion also starts background revocation jobs and returns their `revoke_job_ids`. Pass `?revoke_on_delete=false` to skip those jobs. This differs from [deleting one connected account](/reference/api-reference/connected-accounts/deleteConnectedAccountsByNanoid), where revocation defaults to `false`. See the [toolkit delete endpoint reference](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug) for the full response.
245
246
<Callout type="warn" title="Deletion also removes connections">
233
-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.
247
+Deletion removes the custom toolkit and its tools, auth configurations, and connected accounts. Any replacement starts with new connections. A successful deletion or a started revocation job does not prove that the remote server has invalidated its credentials.
248
</Callout>
249
250
+Custom MCP DCR OAuth credentials are not currently revoked through Composio's connected-account revocation implementation. API-key revocation requires a configured provider-specific operation; storing `generic_api_key` alone does not provide one. Revoke the grant or key at its issuer when you need to invalidate it there.
251
+
252
+Deletion blocks subsequent account lookups. It does not guarantee cancellation of operations that already resolved credentials, immediate credential purging, or removal of earlier execution logs. See [connected-account deletion](/reference/api-reference/connected-accounts/deleteConnectedAccountsByNanoid) and [data retention](/docs/security/data-retention) for the separate lifecycle controls.
253
+
254
## Use Custom MCP in a session
255
256
Once the toolkit is synced, add its `CUSTOM_*` slug to a session.
@@ -271,7 +289,7 @@ const tools = await session.tools();
289
</Tab>
290
</Tabs>
291
274
-With the default search-first session, your agent can discover the custom tools through `COMPOSIO_SEARCH_TOOLS` and execute them through the Tool Router.
292
+With the default search-first session, your agent uses `COMPOSIO_SEARCH_TOOLS` to discover the custom tools and the Tool Router to execute them. If a synced tool is missing from search, see [troubleshooting discovery](#troubleshoot-missing-search-results).
293
294
### Use an authenticated server
295
@@ -328,7 +346,7 @@ Each registered server becomes a custom toolkit scoped to your project:
346
347
- The toolkit has `type: "custom"` and the `CUSTOM` category.
348
- Its slug starts with `CUSTOM_`, such as `CUSTOM_ACME`.
331
-- Its tools are available through Tool Router search and toolkit-filtered tool listing.
349
+- Its tools are exposed through Tool Router search and toolkit-filtered tool listing, subject to the [search limitation below](#troubleshoot-missing-search-results).
350
- Tool execution is proxied to your MCP server with the selected connected account's credentials.
351
352
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:
@@ -349,6 +367,14 @@ Custom toolkits use dated registry versions. The v3.1 tools API selects the late
367
368
See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more examples.
369
370
+### Troubleshoot missing search results
371
+
372
+Custom MCP tools can sync and execute successfully while remaining absent from `COMPOSIO_SEARCH_TOOLS` results. This is a known search-path issue, separate from the 500-tool limit on syncing one toolkit.
373
+
374
+First, confirm that toolkit-filtered listing or `COMPOSIO_GET_TOOL_SCHEMAS` returns the expected tool. If it does, a missing search result does not mean the tool failed to sync. You can use the known slug with `COMPOSIO_MULTI_EXECUTE_TOOL` while the search issue is investigated. Inspect the schema and choose a safe read-only call when verifying execution.
375
+
376
+Reconnects and repeated syncs do not bypass the search-path limit, and there is no customer re-index operation for it. Report the toolkit slug, UTC timestamp, and search and schema/execution log IDs to support.
377
+
378
## Known gaps
379
380
<Accordions>