Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: document is_enabled_for_tool_router on the Custom MCP page
shams haroon7a4eb320e153
diff --git a/docs/content/docs/custom-toolkits.mdx b/docs/content/docs/custom-toolkits.mdxdeleted file mode 100644index b9b198e37..000000000--- a/docs/content/docs/custom-toolkits.mdx+++ /dev/null@@ -1,122 +0,0 @@-----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/extending-sessions/custom-mcp.mdx b/docs/content/docs/extending-sessions/custom-mcp.mdxindex a66f27024..00ed7a962 100644--- a/docs/content/docs/extending-sessions/custom-mcp.mdx+++ b/docs/content/docs/extending-sessions/custom-mcp.mdx@@ -126,6 +126,36 @@ Choose the mode that matches your server, then complete any required connection:For DCR OAuth, the server must support the standard authorization-code flow. Other OAuth grant types aren't supported.+### Create the auth config for automatic account matching++For API-key and DCR OAuth servers, create the toolkit's auth config with `is_enabled_for_tool_router` set to `true`:++```bash+curl --request POST \+ --url https://backend.composio.dev/api/v3.1/auth_configs \+ --header "x-api-key: $COMPOSIO_API_KEY" \+ --header "Content-Type: application/json" \+ --data '{+ "toolkit": { "slug": "CUSTOM_ACME" },+ "auth_config": {+ "type": "use_custom_auth",+ "authScheme": "API_KEY",+ "credentials": {},+ "is_enabled_for_tool_router": true+ }+ }'+```++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:++```bash+curl --request PATCH \+ --url https://backend.composio.dev/api/v3.1/auth_configs/ac_xxxxxxxx \+ --header "x-api-key: $COMPOSIO_API_KEY" \+ --header "Content-Type: application/json" \+ --data '{ "is_enabled_for_tool_router": true }'+```+## Sync and resync toolsCall `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### Use an authenticated server-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.+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:<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">@@ -326,7 +356,7 @@ See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more example</Accordion><Accordion title="Sessions and tool APIs">-- **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.+- **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.- **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.</Accordion>diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.jsonindex e71885de6..05214a485 100644--- a/docs/content/docs/meta.json+++ b/docs/content/docs/meta.json@@ -21,7 +21,6 @@"programmatic-auth-configs","controlling-scopes","white-labeling-authentication",- "custom-toolkits","---Triggers---","triggers","setting-up-triggers/creating-triggers",