CustomToolkits
Usage
Access this class through the composio.customToolkits property:
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.
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. mcpUrl,
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.
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
const { slug, connectLink } = await composio.customToolkits.create({
name: 'Internal API',
mcpUrl: '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).
Composio-managed toolkits cannot be deleted; the API answers 403.
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
const result = await composio.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.
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
const { version, syncedCount } = await composio.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.
On a project with 2FA enabled, updating a private toolkit requires the
userId it is private to.
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
await composio.customToolkits.update('CUSTOM_INTERNAL_API_K7F2Q', {
name: 'Internal API (prod)',
userId: 'user_123',
});upsert() (deprecated)
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.
mcpUrl 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.
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
await composio.customToolkits.upsert({
slug: 'INTERNAL_API',
toolkitConfig: {
name: 'Internal API',
mcpUrl: 'https://mcp.internal.example.com/mcp',
authSchemes: [
{ mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
],
},
});