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, 17:15 UTC
docs: custom toolkits guide (register, auth config flag, sync, sessions)
The is_enabled_for_tool_router step is load-bearing: after the revert of platform#11223 there is no default, and configs created without the flag make session execution fail with NoActiveConnection. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
shams haroon committed
Aug 2, 2026 at 14:57 UTC
2ada960e068ac7ba70053fded8ff3593a9f89b66
2 files changed
+123
docs/content/docs/custom-toolkits.mdx
new
+122
@@ -0,0 +1,122 @@
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/meta.json
+1
@@ -21,6 +21,7 @@
21
"programmatic-auth-configs",
22
"controlling-scopes",
23
"white-labeling-authentication",
24
+ "custom-toolkits",
25
"---Triggers---",
26
"triggers",
27
"setting-up-triggers/creating-triggers",