@devries-cameron20 / composio-1 / commits / 7a4eb320e
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: document is_enabled_for_tool_router on the Custom MCP page

Session auto-match only considers auth configs with this flag, and the custom flow has no default (platform#11223 was reverted), so configs created without it fail session execution with NoActiveConnection. Adds the auth-config creation step with the flag, a PATCH note for existing configs, and updates the session and known-gaps guidance from "don't rely on auto-match" to "auto-match works when the flag is set". Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

shams haroon committed Aug 2, 2026 at 15:30 UTC 7a4eb320e153bd935eeab9375df3b4f9118f5cb4
3 files changed +32 -125
docs/content/docs/custom-toolkits.mdx deleted
-122
@@ -1,122 +0,0 @@
1 ----
2 -title: Custom toolkits
3 -description: Register your own remote MCP server as a project toolkit and use its tools in sessions alongside the Composio catalog
4 -keywords: [custom toolkit, bring your own mcp, custom mcp server, register mcp server, CUSTOM_ toolkit]
5 ----
6 -
7 -A custom toolkit turns your own remote MCP server into a first-class Composio toolkit, scoped to your project. Once registered, its tools show up in session search and execute through the same paths as every catalog toolkit, so your agents can mix your internal tools with Gmail, Slack, and the rest without special-casing anything.
8 -
9 -<Callout type="info">
10 -Custom toolkits are in a limited pilot and API-only for now. Your project needs the feature enabled; contact us if you'd like access.
11 -</Callout>
12 -
13 -Four steps: register the toolkit, create an auth config for it, connect an account, and sync its tools. After that, sessions just work.
14 -
15 -## Register the toolkit
16 -
17 -Send your MCP server's URL and how it authenticates. Your slug gets prefixed with `CUSTOM_` so it can never collide with a catalog toolkit.
18 -
19 -```bash
20 -curl -X POST https://backend.composio.dev/api/v3/custom/toolkits/upsert \
21 - -H "x-api-key: $COMPOSIO_API_KEY" \
22 - -H "Content-Type: application/json" \
23 - -d '{
24 - "slug": "ACME_ADMIN",
25 - "toolkit_config": {
26 - "name": "Acme Admin",
27 - "app_url": "https://mcp.acme.dev/mcp",
28 - "auth_schemes": [
29 - {
30 - "mode": "API_KEY",
31 - "headers": { "Authorization": "Bearer {{generic_api_key}}" }
32 - }
33 - ]
34 - }
35 - }'
36 -```
37 -
38 -The response returns your canonical slug, `CUSTOM_ACME_ADMIN`. Use that slug everywhere from here on.
39 -
40 -For `API_KEY` schemes, put the `{{generic_api_key}}` placeholder wherever the key goes; each connected account supplies its own value later. If your server implements OAuth dynamic client registration, use `{ "mode": "DCR_OAUTH", "discovery_url": "https://mcp.acme.dev/.well-known/oauth-authorization-server" }` instead.
41 -
42 -Note that the tool count is 0 at this point. That's expected: Composio can't list tools from an authenticated MCP server until it has a credential, which is what the next two steps provide.
43 -
44 -## Create an auth config
45 -
46 -Create an auth config for the toolkit, and set `is_enabled_for_tool_router` to `true`:
47 -
48 -```bash
49 -curl -X POST https://backend.composio.dev/api/v3/auth_configs \
50 - -H "x-api-key: $COMPOSIO_API_KEY" \
51 - -H "Content-Type: application/json" \
52 - -d '{
53 - "toolkit": { "slug": "CUSTOM_ACME_ADMIN" },
54 - "auth_config": {
55 - "type": "use_custom_auth",
56 - "authScheme": "API_KEY",
57 - "credentials": {},
58 - "is_enabled_for_tool_router": true
59 - }
60 - }'
61 -```
62 -
63 -<Callout type="warn">
64 -`is_enabled_for_tool_router: true` is required for sessions to find this toolkit's connected accounts automatically. If you skip it, session executions fail with `NoActiveConnection` even though the account exists. If you already created the config without it, patch it: `PATCH /api/v3/auth_configs/{id}` with `{ "is_enabled_for_tool_router": true }`.
65 -</Callout>
66 -
67 -Store the returned `ac_...` ID for the next step.
68 -
69 -## Connect an account
70 -
71 -Create a connected account under the auth config, carrying the actual API key for your MCP server and the `user_id` your sessions will use:
72 -
73 -```bash
74 -curl -X POST https://backend.composio.dev/api/v3/connected_accounts \
75 - -H "x-api-key: $COMPOSIO_API_KEY" \
76 - -H "Content-Type: application/json" \
77 - -d '{
78 - "auth_config": { "id": "ac_xxxxxxxx" },
79 - "connection": {
80 - "user_id": "user-123",
81 - "state": {
82 - "authScheme": "API_KEY",
83 - "val": { "status": "ACTIVE", "generic_api_key": "sk-your-server-key" }
84 - }
85 - }
86 - }'
87 -```
88 -
89 -## Sync the tools
90 -
91 -Point the sync at your new connected account. Composio connects to your MCP server with that credential, lists the tools, and registers them under your toolkit:
92 -
93 -```bash
94 -curl -X POST https://backend.composio.dev/api/v3/custom/toolkits/sync \
95 - -H "x-api-key: $COMPOSIO_API_KEY" \
96 - -H "Content-Type: application/json" \
97 - -d '{
98 - "slug": "CUSTOM_ACME_ADMIN",
99 - "connected_account_id": "ca_xxxxxxxx"
100 - }'
101 -```
102 -
103 -Tool slugs take the form `CUSTOM_ACME_ADMIN_<TOOL_NAME>`. Re-run the sync whenever your server's tool list changes.
104 -
105 -## Use it in a session
106 -
107 -Create a session with the same `user_id` and the toolkit behaves like any other: tools are searchable, and execution matches the connected account automatically.
108 -
109 -```bash
110 -curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
111 - -H "x-api-key: $COMPOSIO_API_KEY" \
112 - -H "Content-Type: application/json" \
113 - -d '{ "user_id": "user-123" }'
114 -```
115 -
116 -## Direct execution
117 -
118 -You can also call custom tools outside sessions. Use the v3.1 endpoints, which resolve tools at their latest version. On v3, pass `version=latest` explicitly: custom tools are published only at dated sync versions, so v3's pinned default version won't match them.
119 -
120 -## Removing a toolkit
121 -
122 -`DELETE /api/v3.1/custom/toolkits/{slug}` removes the toolkit and its tools, and disconnects its accounts. Re-registering the same slug afterward works normally.
docs/content/docs/extending-sessions/custom-mcp.mdx
+32 -2
@@ -126,6 +126,36 @@ Choose the mode that matches your server, then complete any required connection:
126
127 For DCR OAuth, the server must support the standard authorization-code flow. Other OAuth grant types aren't supported.
128
129 +### Create the auth config for automatic account matching
130 +
131 +For API-key and DCR OAuth servers, create the toolkit's auth config with `is_enabled_for_tool_router` set to `true`:
132 +
133 +```bash
134 +curl --request POST \
135 + --url https://backend.composio.dev/api/v3.1/auth_configs \
136 + --header "x-api-key: $COMPOSIO_API_KEY" \
137 + --header "Content-Type: application/json" \
138 + --data '{
139 + "toolkit": { "slug": "CUSTOM_ACME" },
140 + "auth_config": {
141 + "type": "use_custom_auth",
142 + "authScheme": "API_KEY",
143 + "credentials": {},
144 + "is_enabled_for_tool_router": true
145 + }
146 + }'
147 +```
148 +
149 +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:
150 +
151 +```bash
152 +curl --request PATCH \
153 + --url https://backend.composio.dev/api/v3.1/auth_configs/ac_xxxxxxxx \
154 + --header "x-api-key: $COMPOSIO_API_KEY" \
155 + --header "Content-Type: application/json" \
156 + --data '{ "is_enabled_for_tool_router": true }'
157 +```
158 +
159 ## Sync and resync tools
160
161 Call `POST /api/v3.1/custom/toolkits/sync` to fetch the server's current tools:
@@ -242,7 +272,7 @@ With the default search-first session, your agent can discover the custom tools
272
273 ### Use an authenticated server
274
245 -For API-key and DCR OAuth servers, explicitly select the connected account in the session config. Don't rely on automatic account matching for Custom MCP toolkits yet.
275 +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:
276
277 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
278 <Tab value="Python">
@@ -326,7 +356,7 @@ See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more example
356 </Accordion>
357 <Accordion title="Sessions and tool APIs">
358
329 -- **Select authenticated accounts explicitly:** Custom MCP sessions don't reliably match a connected account automatically. Pass its ID through `connected_accounts` in Python or `connectedAccounts` in TypeScript.
359 +- **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.
360 - **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.
361
362 </Accordion>
docs/content/docs/meta.json
-1
@@ -21,7 +21,6 @@
21 "programmatic-auth-configs",
22 "controlling-scopes",
23 "white-labeling-authentication",
24 - "custom-toolkits",
24 "---Triggers---",
25 "triggers",
26 "setting-up-triggers/creating-triggers",