> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom MCP

> Use tools from a remote MCP server in Composio sessions

Custom MCP lets you add your own remote MCP server to Composio and use its tools in sessions, next to Composio's toolkits. A Custom MCP toolkit is either shared with every user in your project or private to one user, so your users can add their own MCP servers too.

> [!WARNING]
>
> Custom MCP is experimental. The APIs may change.

This is different from [Custom Tools and Toolkits](https://composio-preview.mintlify.site/docs/extending-sessions/custom-tools-and-toolkits.md), which run inside your app. A Custom MCP server runs on its own public HTTPS URL.

## How it works

1. **Get** a remote MCP server at a public HTTPS URL: your own, or an existing one.
2. **Create** a toolkit for it. Composio gives it a `CUSTOM_*` slug.
3. **Connect** an account if the server needs an API key or DCR OAuth.
4. Composio **syncs** the tools automatically.
5. **Use** the toolkit in a session.

Use the SDK (`composio.experimental.custom_toolkits` in Python, `composio.experimental.customToolkits` in TypeScript) or the API. See the API reference for [create](https://composio-preview.mintlify.site/reference/api-reference/toolkits/postCustomToolkits.md), [update](https://composio-preview.mintlify.site/reference/api-reference/toolkits/patchCustomToolkitsBySlug.md), [sync](https://composio-preview.mintlify.site/reference/api-reference/toolkits/postCustomToolkitsSync.md), and [delete](https://composio-preview.mintlify.site/reference/api-reference/toolkits/deleteCustomToolkitsBySlug.md). `upsert()` is deprecated; use `create()` and `update()`. See [Move from upsert](#move-from-upsert).

## Create a toolkit

Pass your MCP server's URL as `app_url`, how to authenticate, and `user_id`. Use `"all"` to share the toolkit with every user in your project:

> [tab] Python
>
> ```python theme={null}
> result = composio.experimental.custom_toolkits.create(
>     name="Acme",
>     app_url="https://mcp.acme.com/mcp",
>     auth_schemes=[{"mode": "NO_AUTH"}],
>     user_id="all",
> )
>
> print(result.slug)  # CUSTOM_ACME
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const result = await composio.experimental.customToolkits.create({
>   name: 'Acme',
>   appUrl: 'https://mcp.acme.com/mcp',
>   authSchemes: [{ mode: 'NO_AUTH' }],
>   userId: 'all',
> });
>
> console.log(result.slug); // CUSTOM_ACME
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Acme",
>     "app_url": "https://mcp.acme.com/mcp",
>     "auth_schemes": [{"mode": "NO_AUTH"}],
>     "user_id": "all"
>   }'
> ```

Save the returned slug: you need it to sync, update, or delete the toolkit.

`app_url`, `auth_schemes`, and `user_id` can't change later. To change them, delete the toolkit and create it again.

> [!WARNING]
>
> **Use the final URL**
>
> Set `app_url` to the final MCP endpoint, with no redirects: a redirect can send credentials to another host. Don't put keys in the URL.

### Choose how users authenticate

Set `auth_schemes` to one of these:

| Mode | Use it when | `auth_schemes` |
| - | - | - |
| No auth | The server needs no credentials. | `[{"mode": "NO_AUTH"}]` |
| API key | Each user brings an API key. | `[{"mode": "API_KEY", "headers": {"Authorization": "Bearer {{generic_api_key}}"}}]` |
| DCR OAuth | The server supports OAuth Dynamic Client Registration. | `[{"mode": "DCR_OAUTH", "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server"}]` |

* **API key:** put `{{generic_api_key}}` in the header where the key goes, as in the table. Composio fills in each user's key when it calls your server.
* **DCR OAuth:** set `discovery_url` to your OAuth server's metadata URL, usually ending in `/.well-known/oauth-authorization-server`. The server must support Dynamic Client Registration and the authorization-code flow.

### Create a toolkit for one user

Set `user_id` to a user's ID to make the toolkit private: only that user's sessions and API calls can see or run its tools. Private toolkits need a Pro plan: on the free plan, create returns `403`.

> [tab] Python
>
> ```python theme={null}
> result = composio.experimental.custom_toolkits.create(
>     name="Acme",
>     app_url="https://mcp.acme.com/mcp",
>     auth_schemes=[
>         {
>             "mode": "DCR_OAUTH",
>             "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server",
>         }
>     ],
>     user_id="user_123",
>     callback_url="https://app.example.com/connected",
> )
>
> print(result.slug)  # CUSTOM_ACME_K7F2Q
> if result.connect_link is not None:
>     print(result.connect_link.redirect_url)  # send user_123 here
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const result = await composio.experimental.customToolkits.create({
>   name: 'Acme',
>   appUrl: 'https://mcp.acme.com/mcp',
>   authSchemes: [
>     {
>       mode: 'DCR_OAUTH',
>       discoveryUrl: 'https://mcp.acme.com/.well-known/oauth-authorization-server',
>     },
>   ],
>   userId: 'user_123',
>   callbackUrl: 'https://app.example.com/connected',
> });
>
> console.log(result.slug); // CUSTOM_ACME_K7F2Q
> if (result.connectLink) {
>   console.log(result.connectLink.redirectUrl); // send user_123 here
> }
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Acme",
>     "app_url": "https://mcp.acme.com/mcp",
>     "auth_schemes": [
>       {
>         "mode": "DCR_OAUTH",
>         "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server"
>       }
>     ],
>     "user_id": "user_123",
>     "callback_url": "https://app.example.com/connected"
>   }'
> ```

```json theme={null}
{
  "slug": "CUSTOM_ACME_K7F2Q",
  "connect_link": {
    "redirect_url": "https://connect.composio.dev/link/lk_...",
    "expires_at": "2026-11-03T12:10:00.000Z",
    "connected_account_id": "ca_..."
  }
}
```

If the server needs auth, send the user to `connect_link.redirect_url`. Once they connect, the tools sync. `connect_link` is `null` for shared and no-auth toolkits. To get a new link, call [`POST /api/v3.1/connected_accounts/link`](https://composio-preview.mintlify.site/reference/api-reference/connected-accounts/postConnectedAccountsLink).

Creating the same MCP URL twice for one user, or twice as shared, returns `409`. `"default"` and other spellings of `"all"` (such as `"ALL"`) return `400`.

### Add a logo

Add `logo_file` to create or update: a square PNG or JPEG, 256 to 1024 pixels, at most 3MB, base64-encoded on one line. Composio hosts it. Without one, the toolkit shows the MCP logo.

```json theme={null}
"logo_file": {"content": "<base64>", "mime_type": "image/png"}
```

## Connect and sync

* **No auth:** tools sync when you create the toolkit.
* **API key or DCR OAuth:** tools sync when the first account connects.

Sync again only if that first sync fails or the server's tools change. Pass an active connected account, or leave it out for a no-auth server:

> [tab] Python
>
> ```python theme={null}
> result = composio.experimental.custom_toolkits.sync(
>     "CUSTOM_ACME",
>     connected_account_id="ca_custom_acme",
> )
>
> print(result.version, result.synced_count)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const result = await composio.experimental.customToolkits.sync('CUSTOM_ACME', {
>   connectedAccountId: 'ca_custom_acme',
> });
>
> console.log(result.version, result.syncedCount);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/sync \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"slug": "CUSTOM_ACME", "connected_account_id": "ca_custom_acme"}'
> ```

A toolkit can have at most 500 tools. If the server has more, the sync fails and the last good version stays.

## Update a toolkit

Update changes `name`, `logo_file`, or the API key field's label (`api_key_field`). Fields you leave out stay the same. If your project has 2FA on, updating a private toolkit needs its `user_id`.

> [tab] Python
>
> ```python theme={null}
> result = composio.experimental.custom_toolkits.update("CUSTOM_ACME", name="Acme (prod)")
>
> print(result.success)  # True
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const result = await composio.experimental.customToolkits.update('CUSTOM_ACME', {
>   name: 'Acme (prod)',
> });
>
> console.log(result.success); // true
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/custom/toolkits/CUSTOM_ACME \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"name": "Acme (prod)"}'
> ```

## Delete a toolkit

Delete removes the toolkit and its tools, auth configs, and connected accounts.

> [tab] Python
>
> ```python theme={null}
> result = composio.experimental.custom_toolkits.delete("CUSTOM_ACME")
>
> print(result.deleted, result.revoke_job_ids)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const result = await composio.experimental.customToolkits.delete('CUSTOM_ACME');
>
> console.log(result.deleted, result.revokeJobIds);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X DELETE https://backend.composio.dev/api/v3.1/custom/toolkits/CUSTOM_ACME \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

By default, delete also starts jobs to revoke the accounts' credentials and returns their `revoke_job_ids`. Pass `?revoke_on_delete=false` to skip them. DCR OAuth grants and API keys usually aren't revoked on the server's side, so revoke them there if you need to. Delete doesn't stop calls already in progress or remove past [execution logs](https://composio-preview.mintlify.site/docs/security/data-retention.md).

## Use the toolkit in a session

Add the slug to a session. A session only sees the custom toolkits its `user_id` can use: naming another user's private toolkit returns `400`, and running its tools returns `403`.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio(api_key="your_api_key")
>
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits=["CUSTOM_ACME"],
> )
>
> tools = session.tools()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
>
> const composio = new Composio({ apiKey: "your_api_key" });
>
> const session = await composio.sessions.create("user_123", {
>   toolkits: ["CUSTOM_ACME"],
> });
>
> const tools = await session.tools();
> ```

> [tab] API
>
> ```bash theme={null}
> SESSION_ID=$(curl -s -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", "toolkits": {"enable": ["CUSTOM_ACME"]}}' | jq -r '.session_id')
>
> curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

Your agent finds the tools with `COMPOSIO_SEARCH_TOOLS`. Sessions pick the user's connected account automatically. If you created the auth config yourself, [set `is_enabled_for_tool_router: true`](https://composio-preview.mintlify.site/reference/api-reference/auth-configs/patchAuthConfigsByNanoid) on it. To use a specific account, pass it in the session:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio(api_key="your_api_key")
>
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits=["CUSTOM_ACME"],
>     connected_accounts={
>         "CUSTOM_ACME": ["ca_custom_acme"],
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
>
> const composio = new Composio({ apiKey: "your_api_key" });
>
> const session = await composio.sessions.create("user_123", {
>   toolkits: ["CUSTOM_ACME"],
>   connectedAccounts: {
>     CUSTOM_ACME: ["ca_custom_acme"],
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> 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",
>     "toolkits": {"enable": ["CUSTOM_ACME"]},
>     "connected_accounts": {"CUSTOM_ACME": ["ca_custom_acme"]}
>   }'
> ```

## List your toolkits

`GET /api/v3.1/toolkits?type=custom` lists your shared custom toolkits. Add `user_id` to include that user's private ones. Each toolkit's `access` is `"all"` (shared) or `"user"` (private).

## Troubleshooting

* **Tools missing from search:** search can miss custom tools that synced fine. Check with toolkit-filtered tool listing or `COMPOSIO_GET_TOOL_SCHEMAS`, then call the tool by slug with `COMPOSIO_MULTI_EXECUTE_TOOL`. Resyncing doesn't help; send the slug, time (UTC), and log IDs to support.
* **Empty tool list on v3:** the v3 tools API reads a pinned toolkit version that has no custom tools. Use v3.1, or ask for the latest version: `toolkit_versions=latest` to list tools, `version=latest` to get one, or `"version": "latest"` in the body to execute. See [Toolkit Versioning](https://composio-preview.mintlify.site/docs/tools-direct/toolkit-versioning.md).

## Move from upsert

`upsert()` and `POST /api/v3.1/custom/toolkits/upsert` still work but are deprecated. Toolkits you created with upsert keep working and keep their slugs.

* **New toolkit:** call create instead of upsert. Don't pass a slug: create returns one, so save it. Set `user_id` to `"all"` to share the toolkit like upsert did, or to a user's ID to make it private.
* **Existing toolkit:** call update with its slug to change the name, logo, or API key field label. Don't create it again: a second shared toolkit for the same URL returns `409`.
* **Request shape:** create takes the fields directly (`name`, `app_url`, `auth_schemes`, ...), not inside `toolkit_config`.

## Limits

* Private toolkits need a Pro plan. Shared toolkits (`user_id: "all"`) work on every plan.
* Remote servers only: local and STDIO servers aren't supported.
* `app_url`, `auth_schemes`, and `user_id` can't change after creation.
* At most 500 tools per toolkit.
* OAuth works only through Dynamic Client Registration (DCR). Servers that need a pre-registered OAuth client, or that only support Client ID Metadata Documents (CIMD), aren't supported.
* No automatic resync: sync again when the server's tools change.

## Related guides

> [card] [Using sessions via MCP](https://composio-preview.mintlify.site/docs/sessions-via-mcp.md)
>
> Connect an MCP client to a Composio-hosted session

> [card] [Custom Tools and Toolkits](https://composio-preview.mintlify.site/docs/extending-sessions/custom-tools-and-toolkits.md)
>
> Run your own tools inside your application process

> [card] [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md)
>
> Configure toolkit and tool filtering

> [card] [Managing Multiple Connected Accounts](https://composio-preview.mintlify.site/docs/authentication/managing-multiple-connected-accounts.md)
>
> Select a connected account explicitly
