@devries-cameron20 / composio Mirror · read-only / commits / 86ad9894e
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, 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>