Skip to content

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: custom toolkits guide (register, auth config flag, sync, sessions)

shams haroon2ada960e068a
diff --git a/docs/content/docs/custom-toolkits.mdx b/docs/content/docs/custom-toolkits.mdx
new file mode 100644
index 000000000..b9b198e37
--- /dev/null
+++ b/docs/content/docs/custom-toolkits.mdx
@@ -0,0 +1,122 @@
+---
+title: Custom toolkits
+description: Register your own remote MCP server as a project toolkit and use its tools in sessions alongside the Composio catalog
+keywords: [custom toolkit, bring your own mcp, custom mcp server, register mcp server, CUSTOM_ toolkit]
+---
+
+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.
+
+<Callout type="info">
+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.
+</Callout>
+
+Four steps: register the toolkit, create an auth config for it, connect an account, and sync its tools. After that, sessions just work.
+
+## Register the toolkit
+
+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.
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3/custom/toolkits/upsert \
+ -H "x-api-key: $COMPOSIO_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "slug": "ACME_ADMIN",
+ "toolkit_config": {
+ "name": "Acme Admin",
+ "app_url": "https://mcp.acme.dev/mcp",
+ "auth_schemes": [
+ {
+ "mode": "API_KEY",
+ "headers": { "Authorization": "Bearer {{generic_api_key}}" }
+ }
+ ]
+ }
+ }'
+```
+
+The response returns your canonical slug, `CUSTOM_ACME_ADMIN`. Use that slug everywhere from here on.
+
+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.
+
+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.
+
+## Create an auth config
+
+Create an auth config for the toolkit, and set `is_enabled_for_tool_router` to `true`:
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3/auth_configs \
+ -H "x-api-key: $COMPOSIO_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "toolkit": { "slug": "CUSTOM_ACME_ADMIN" },
+ "auth_config": {
+ "type": "use_custom_auth",
+ "authScheme": "API_KEY",
+ "credentials": {},
+ "is_enabled_for_tool_router": true
+ }
+ }'
+```
+
+<Callout type="warn">
+`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 }`.
+</Callout>
+
+Store the returned `ac_...` ID for the next step.
+
+## Connect an account
+
+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:
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3/connected_accounts \
+ -H "x-api-key: $COMPOSIO_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "auth_config": { "id": "ac_xxxxxxxx" },
+ "connection": {
+ "user_id": "user-123",
+ "state": {
+ "authScheme": "API_KEY",
+ "val": { "status": "ACTIVE", "generic_api_key": "sk-your-server-key" }
+ }
+ }
+ }'
+```
+
+## Sync the tools
+
+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:
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3/custom/toolkits/sync \
+ -H "x-api-key: $COMPOSIO_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "slug": "CUSTOM_ACME_ADMIN",
+ "connected_account_id": "ca_xxxxxxxx"
+ }'
+```
+
+Tool slugs take the form `CUSTOM_ACME_ADMIN_<TOOL_NAME>`. Re-run the sync whenever your server's tool list changes.
+
+## Use it in a session
+
+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.
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
+ -H "x-api-key: $COMPOSIO_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{ "user_id": "user-123" }'
+```
+
+## Direct execution
+
+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.
+
+## Removing a toolkit
+
+`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.
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 05214a485..e71885de6 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -21,6 +21,7 @@
"programmatic-auth-configs",
"controlling-scopes",
"white-labeling-authentication",
+ "custom-toolkits",
"---Triggers---",
"triggers",
"setting-up-triggers/creating-triggers",