SDK ReferenceTypeScript SDK

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

NameTypeDescription
paramsCustomToolkitCreateParamsThe 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

NameTypeDescription
slugstringThe 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

NameTypeDescription
slugstringThe custom toolkit slug (CUSTOM_...)
params?CustomToolkitSyncParamsOptional 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

NameTypeDescription
slugstringThe custom toolkit slug returned by create()
paramsCustomToolkitUpdateParamsAt 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

NameTypeDescription
paramsCustomToolkitUpsertParamsThe 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}}' } },
    ],
  },
});