@devries-cameron20 / composio-1 / commits / 86d2eac42
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(core)!: custom toolkit create/upsert take mcpUrl (PLEN-4820) (#5218)

Rename experimental custom toolkit create and upsert inputs from appUrl to mcpUrl while sending mcp_url to the API. Update TypeScript examples, validation tests, and the breaking-change release note.

Bharath Singh committed Nov 6, 2026 at 17:02 UTC 86d2eac424f7d62bbace8d69d801ba5528d9ba08
5 files changed +22 -21
.changeset/custom-toolkit-mcp-url.md
+3 -2
@@ -1,5 +1,6 @@
1 ---
2 -'@composio/core': patch
2 +'@composio/core': minor
3 +'@composio/slim': minor
4 ---
5
5 -Send custom toolkit URLs as `mcp_url` for the Platform API rename while preserving the public TypeScript `appUrl` input.
6 +Breaking (experimental API): `composio.experimental.customToolkits.create()` and `upsert()` take the MCP server URL as `mcpUrl` instead of `appUrl`, and send it to the API as `mcp_url`.
ts/packages/core/src/models/CustomToolkits.ts
+5 -5
@@ -56,7 +56,7 @@ let _upsertDeprecationWarned = false;
56 * ```typescript
57 * const { slug } = await composio.experimental.customToolkits.create({
58 * name: 'My Toolkit',
59 - * appUrl: 'https://mcp.example.com/mcp',
59 + * mcpUrl: 'https://mcp.example.com/mcp',
60 * authSchemes: [{ mode: 'DCR_OAUTH', discoveryUrl: 'https://mcp.example.com/.well-known/oauth-authorization-server' }],
61 * userId: 'all',
62 * });
@@ -76,7 +76,7 @@ export class CustomToolkits {
76 * **Experimental — custom toolkits are in pilot; shape may change.**
77 *
78 * Set `userId` to `'all'` to share the toolkit with every user in the
79 - * project, or to a user ID to make it private to that user. `appUrl`,
79 + * project, or to a user ID to make it private to that user. `mcpUrl`,
80 * `authSchemes` and `userId` cannot change later: delete and re-create the
81 * toolkit instead. For a private toolkit, `connectLink` is where to send
82 * that user to connect.
@@ -89,7 +89,7 @@ export class CustomToolkits {
89 * ```typescript
90 * const { slug, connectLink } = await composio.experimental.customToolkits.create({
91 * name: 'Internal API',
92 - * appUrl: 'https://mcp.internal.example.com/mcp',
92 + * mcpUrl: 'https://mcp.internal.example.com/mcp',
93 * authSchemes: [
94 * { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
95 * ],
@@ -160,7 +160,7 @@ export class CustomToolkits {
160 * field copy) when the project already owns a toolkit with this slug.
161 * **Experimental — custom toolkits are in pilot; shape may change.**
162 *
163 - * `appUrl` and `authSchemes` cannot change on an existing toolkit:
163 + * `mcpUrl` and `authSchemes` cannot change on an existing toolkit:
164 * re-sending them unchanged is a no-op, and changing them fails with a 409.
165 * Delete and re-register the toolkit instead, which revokes its connections.
166 *
@@ -174,7 +174,7 @@ export class CustomToolkits {
174 * slug: 'INTERNAL_API',
175 * toolkitConfig: {
176 * name: 'Internal API',
177 - * appUrl: 'https://mcp.internal.example.com/mcp',
177 + * mcpUrl: 'https://mcp.internal.example.com/mcp',
178 * authSchemes: [
179 * { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
180 * ],
ts/packages/core/src/types/customToolkits.types.ts
+3 -3
@@ -57,7 +57,7 @@ export const CustomToolkitCreateParamsSchema = z.object({
57 /** Human-readable toolkit name. */
58 name: z.string().min(1).max(200),
59 /** The MCP server URL. Must use https. */
60 - appUrl: z.string().url(),
60 + mcpUrl: z.string().url(),
61 /** Square PNG or JPEG logo (256-1024px, max 3MB), base64-encoded. Defaults to the MCP logo. */
62 logoFile: CustomToolkitLogoFileSchema.optional(),
63 /** At least one scheme. Cannot be changed after create. */
@@ -135,8 +135,8 @@ export const CustomToolkitUpsertParamsSchema = z.object({
135 toolkitConfig: z.object({
136 /** Human-readable toolkit name. */
137 name: z.string().min(1).max(200),
138 - /** The app URL. For an MCP app, the MCP server URL. */
139 - appUrl: z.string().url(),
138 + /** The MCP server URL. Must use https. */
139 + mcpUrl: z.string().url(),
140 /** Square PNG or JPEG logo (256-1024px, max 3MB), base64-encoded. Defaults to the Composio logo. */
141 logoFile: CustomToolkitLogoFileSchema.optional(),
142 /** At least one scheme. The schemes cannot change once the toolkit exists. */
ts/packages/core/src/utils/transformers/customToolkits.ts
+2 -2
@@ -73,7 +73,7 @@ export const transformCustomToolkitCreateParams = (
73 params: CustomToolkitCreateParams
74 ): RawCustomCreateToolkitParams => ({
75 name: params.name,
76 - mcp_url: params.appUrl,
76 + mcp_url: params.mcpUrl,
77 logo_file: transformCustomToolkitLogoFile(params.logoFile),
78 auth_schemes: params.authSchemes.map(transformCustomToolkitAuthScheme),
79 user_id: params.userId,
@@ -118,7 +118,7 @@ export const transformCustomToolkitUpsertParams = (
118 slug: params.slug,
119 toolkit_config: {
120 name: params.toolkitConfig.name,
121 - mcp_url: params.toolkitConfig.appUrl,
121 + mcp_url: params.toolkitConfig.mcpUrl,
122 logo_file: transformCustomToolkitLogoFile(params.toolkitConfig.logoFile),
123 auth_schemes: params.toolkitConfig.authSchemes.map(transformCustomToolkitAuthScheme),
124 },
ts/packages/core/test/models/customToolkits.test.ts
+9 -9
@@ -51,7 +51,7 @@ describe('Experimental.customToolkits', () => {
51 const result = await customToolkits.create(
52 {
53 name: 'My Toolkit',
54 - appUrl: 'https://mcp.example.com/mcp',
54 + mcpUrl: 'https://mcp.example.com/mcp',
55 logoFile: { content: 'aGVsbG8=', mimeType: 'image/png' },
56 authSchemes: [
57 {
@@ -118,7 +118,7 @@ describe('Experimental.customToolkits', () => {
118
119 const result = await customToolkits.create({
120 name: 'My Toolkit',
121 - appUrl: 'https://mcp.example.com/mcp',
121 + mcpUrl: 'https://mcp.example.com/mcp',
122 authSchemes: [{ mode: 'NO_AUTH' }],
123 userId: 'all',
124 });
@@ -129,7 +129,7 @@ describe('Experimental.customToolkits', () => {
129 it.each([
130 ['no user ID', { userId: undefined }],
131 ['no auth schemes', { authSchemes: [] }],
132 - ['an app URL that is not a URL', { appUrl: 'not a url' }],
132 + ['an MCP URL that is not a URL', { mcpUrl: 'not a url' }],
133 [
134 'an additional API key field without a display name',
135 {
@@ -146,7 +146,7 @@ describe('Experimental.customToolkits', () => {
146 await expect(
147 customToolkits.create({
148 name: 'My Toolkit',
149 - appUrl: 'https://mcp.example.com/mcp',
149 + mcpUrl: 'https://mcp.example.com/mcp',
150 authSchemes: [{ mode: 'NO_AUTH' }],
151 userId: 'all',
152 ...(override as object),
@@ -195,7 +195,7 @@ describe('Experimental.customToolkits', () => {
195 slug: 'MY_TOOLKIT',
196 toolkitConfig: {
197 name: 'My Toolkit',
198 - appUrl: 'https://mcp.example.com/mcp',
198 + mcpUrl: 'https://mcp.example.com/mcp',
199 authSchemes: [{ mode: 'NO_AUTH' as const }],
200 },
201 };
@@ -216,7 +216,7 @@ describe('Experimental.customToolkits', () => {
216 slug: 'MY TOOLKIT',
217 toolkitConfig: {
218 name: 'My Toolkit',
219 - appUrl: 'https://mcp.example.com/mcp',
219 + mcpUrl: 'https://mcp.example.com/mcp',
220 logoFile: { content: 'aGVsbG8=', mimeType: 'image/png' },
221 authSchemes: [
222 { mode: 'NO_AUTH' },
@@ -266,7 +266,7 @@ describe('Experimental.customToolkits', () => {
266 slug: 'MY_TOOLKIT',
267 toolkitConfig: {
268 name: 'My Toolkit',
269 - appUrl: 'https://mcp.example.com/mcp',
269 + mcpUrl: 'https://mcp.example.com/mcp',
270 authSchemes: [{ mode: 'API_KEY', headers: { 'x-api-key': '{{generic_api_key}}' } }],
271 },
272 });
@@ -285,7 +285,7 @@ describe('Experimental.customToolkits', () => {
285 it.each([
286 ['a slug outside the API grammar', { slug: 'my-toolkit' }],
287 ['no auth schemes', { authSchemes: [] }],
288 - ['an app URL that is not a URL', { appUrl: 'not a url' }],
288 + ['an MCP URL that is not a URL', { mcpUrl: 'not a url' }],
289 ])('rejects %s before calling the API', async (_label, override) => {
290 const { slug = 'MY_TOOLKIT', ...config } = override as Record<string, unknown>;
291
@@ -294,7 +294,7 @@ describe('Experimental.customToolkits', () => {
294 slug: slug as string,
295 toolkitConfig: {
296 name: 'My Toolkit',
297 - appUrl: 'https://mcp.example.com/mcp',
297 + mcpUrl: 'https://mcp.example.com/mcp',
298 authSchemes: [{ mode: 'NO_AUTH' }],
299 ...config,
300 },