> ## 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.

# CustomToolkits

> `composio.experimental.customToolkits` — toolkits your project registers from its own app or MCP server, with their own auth configs and connected accounts. **Experimental — custom toolkits are in pilot; shape may change.**  These live on the Composio platform. They are unrelated to the in-process toolkits built with `experimental_createToolkit()`, which run inside your application.

## Usage

Access this class through the `composio.customToolkits` property:

```typescript theme={null}
const composio = new Composio({ apiKey: 'your-api-key' });
const result = await composio.customToolkits.list();
```

## Methods

### create()

Creates a custom MCP toolkit and returns its generated slug. **Experimental — custom toolkits are in pilot; shape may change.**

Set `userId` to `'all'` to share the toolkit with every user in the project, or to a user ID to make it private to that user. `appUrl`, `authSchemes` and `userId` cannot change later: delete and re-create the toolkit instead. For a private toolkit, `connectLink` is where to send that user to connect.

```typescript theme={null}
async create(params: CustomToolkitCreateParams, requestOptions?: ComposioRequestOptions): Promise<CustomToolkitCreateResponse>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `params` | `CustomToolkitCreateParams` | The toolkit to create |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<CustomToolkitCreateResponse>` — The toolkit's slug and, for a private toolkit, a connect link

**Example**

```typescript theme={null}
const { slug, connectLink } = await composio.experimental.customToolkits.create({
  name: 'Internal API',
  appUrl: 'https://mcp.internal.example.com/mcp',
  authSchemes: [
    { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
  ],
  userId: 'user_123',
});
```

***

### delete()

Deletes a custom toolkit owned by the project, with its tools, auth configs and connected accounts. The credentials behind those connected accounts are revoked in background jobs (`revokeJobIds`). **Experimental — custom toolkits are in pilot; shape may change.**

Composio-managed toolkits cannot be deleted; the API answers 403.

```typescript theme={null}
async delete(slug: string, requestOptions?: ComposioRequestOptions): Promise<CustomToolkitDeleteResponse>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `slug` | `string` | The custom toolkit slug (`CUSTOM_...`) |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<CustomToolkitDeleteResponse>` — What was deleted

**Example**

```typescript theme={null}
const result = await composio.experimental.customToolkits.delete('CUSTOM_MY_TOOLKIT');
console.log(result.connectedAccountsDeleted);
```

***

### sync()

Re-fetches the tool definitions of a custom toolkit from its remote MCP server. Call it when automatic sync fails or the remote tools change. **Experimental — custom toolkits are in pilot; shape may change.**

```typescript theme={null}
async sync(slug: string, params?: CustomToolkitSyncParams, requestOptions?: ComposioRequestOptions): Promise<CustomToolkitSyncResponse>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `slug` | `string` | The custom toolkit slug (`CUSTOM_...`) |
| `params?` | `CustomToolkitSyncParams` | Optional connected account to fetch the definitions with |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<CustomToolkitSyncResponse>` — The toolkit version and number of tools synced

**Example**

```typescript theme={null}
const { version, syncedCount } = await composio.experimental.customToolkits.sync(
  'CUSTOM_MY_TOOLKIT',
  { connectedAccountId: 'ca_abc123' }
);
```

***

### update()

Updates a custom toolkit's name, logo or API key field copy. Omitted fields keep their current value. **Experimental — custom toolkits are in pilot; shape may change.**

On a project with 2FA enabled, updating a private toolkit requires the `userId` it is private to.

```typescript theme={null}
async update(slug: string, params: CustomToolkitUpdateParams, requestOptions?: ComposioRequestOptions): Promise<CustomToolkitUpdateResponse>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `slug` | `string` | The custom toolkit slug returned by `create()` |
| `params` | `CustomToolkitUpdateParams` | At least one of `name`, `logoFile`, `apiKeyField` |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<CustomToolkitUpdateResponse>` — `\{ success: true \}`

**Example**

```typescript theme={null}
await composio.experimental.customToolkits.update('CUSTOM_INTERNAL_API_K7F2Q', {
  name: 'Internal API (prod)',
  userId: 'user_123',
});
```

***

### upsert() (deprecated)

> [!WARNING]
>
> **Deprecated**
>
> Use `create()` for a new toolkit and `update(slug, ...)` to change its name, logo or API key field. `create()` generates the slug, so store the slug it returns.

Creates a custom toolkit, or updates its display metadata (name, API key field copy) when the project already owns a toolkit with this slug. **Experimental — custom toolkits are in pilot; shape may change.**

`appUrl` and `authSchemes` cannot change on an existing toolkit: re-sending them unchanged is a no-op, and changing them fails with a 409. Delete and re-register the toolkit instead, which revokes its connections.

```typescript theme={null}
async upsert(params: CustomToolkitUpsertParams, requestOptions?: ComposioRequestOptions): Promise<CustomToolkitUpsertResponse>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `params` | `CustomToolkitUpsertParams` | The slug and toolkit configuration |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<CustomToolkitUpsertResponse>` — The toolkit's slug

**Example**

```typescript theme={null}
await composio.experimental.customToolkits.upsert({
  slug: 'INTERNAL_API',
  toolkitConfig: {
    name: 'Internal API',
    appUrl: 'https://mcp.internal.example.com/mcp',
    authSchemes: [
      { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
    ],
  },
});
```

***
