@devries-cameron20 / composio-1 / commits / 6b6849dda
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.

docs: use custom toolkit create/update and cover end-user toolkits (PLEN-4800)

The Custom MCP guide taught the now-deprecated upsert. Switch its examples to create() / update() (POST and PATCH /api/v3.1/custom/toolkits), document private toolkits via user_id, connect_link, the 409/400 rules, session access and listing with ?user_id. Bump docs to @composio/core 0.28.0, which ships create/update. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H6YzWrR4j8HcSUKs9b7EhV

Bharath committed Nov 3, 2026 at 16:02 UTC 6b6849ddab0ce4728dd8e5268b3cd3a284a21666
3 files changed +266 -142
docs/bun.lock
+4 -4
@@ -50,7 +50,7 @@
50 "@anthropic-ai/sdk": "^0.115.0",
51 "@composio/anthropic": "^0.11.6",
52 "@composio/claude-agent-sdk": "^0.13.0",
53 - "@composio/core": "^0.27.0",
53 + "@composio/core": "^0.28.0",
54 "@composio/google": "^0.12.0",
55 "@composio/langchain": "^0.11.2",
56 "@composio/llamaindex": "^0.11.2",
@@ -223,9 +223,9 @@
223
224 "@composio/claude-agent-sdk": ["@composio/claude-agent-sdk@0.13.0", "", { "dependencies": { "@composio/json-schema-to-zod": "0.4.0", "zod": "^4.5.4" }, "peerDependencies": { "@anthropic-ai/claude-agent-sdk": "^0.3.199", "@composio/core": ">=0.10.0 <1.0.0 || >=1.0.0-beta.0 <1.0.0" } }, "sha512-HYEkahUuRlj7WL1m0WJQO9SVuhdTcu/Zg3DA/B5XijRDgY5luFST/otocg4VQ21xLcuo9fMvTYXVN3jQUugv6Q=="],
225
226 - "@composio/client": ["@composio/client@2.0.0-rc.19", "", { "peerDependencies": { "effect": "*" }, "optionalPeers": ["effect"] }, "sha512-EdBq7KXefbLXwK4F4wUtlG/e37pSxBQCAjJLRAgb0tHhiifDVqsmB/9AzLzpDsDfDKL/3UMUtYUiVUYaD87BVA=="],
226 + "@composio/client": ["@composio/client@2.0.1", "", { "peerDependencies": { "effect": "*" }, "optionalPeers": ["effect"] }, "sha512-1+Azl8W/grinmXVt6KhDKy5UlvTiv7MCMgjqBDxd8TqndjM92/HotxLabnB63A285bvo5Lcu4kbOz413uaPmEQ=="],
227
228 - "@composio/core": ["@composio/core@0.27.0", "", { "dependencies": { "@composio/client": "2.0.0-rc.19", "@composio/json-schema-to-zod": "0.4.0", "@types/json-schema": "^7.0.15", "is-fs-case-sensitive": "^2.0.0", "openai": "^7.32.0", "picocolors": "^1.1.1", "pusher-js": "^8.6.0", "semver": "^7.8.5", "undici": "^7.30.0", "zod-to-json-schema": "^3.25.2" }, "peerDependencies": { "zod": ">=3.25.76 <5" } }, "sha512-tkWThMKQ3NzCoIXpMioMSwVB1Lxd7Gk1h2Z+cIdw1P0d6ARYPcmwKkscJHSVknHy4qxJkBtc3Q3dFtinIoZSaA=="],
228 + "@composio/core": ["@composio/core@0.28.0", "", { "dependencies": { "@composio/client": "2.0.1", "@composio/json-schema-to-zod": "0.4.0", "@types/json-schema": "^7.0.15", "is-fs-case-sensitive": "^2.0.0", "openai": "^7.39.0", "picocolors": "^1.1.1", "pusher-js": "^8.6.0", "semver": "^7.8.5", "undici": "^7.30.1", "zod-to-json-schema": "^3.25.2" }, "peerDependencies": { "zod": ">=3.25.76 <5" } }, "sha512-OF2vC9Bc3uBmTPQKeq43QNWqmsVHHu0AKQJfNaQqM3h8fE8bvG3mUrisJ285mCkVSyY7tAr/dC+ONothQtQRDQ=="],
229
230 "@composio/google": ["@composio/google@0.12.0", "", { "peerDependencies": { "@composio/core": ">=0.16.0 <1.0.0 || >=1.0.0-beta.0 <1.0.0", "@google/genai": "^1.1.0" } }, "sha512-VYVd7F3Nu0b/bxZgQLMb2mR8A2bPNTSKBx3SqJtMOZsJ7Gayu7JE+ZmZtJq8fFXGUmGRoqpwoopwudNpq7GS+w=="],
231
@@ -2019,7 +2019,7 @@
2019
2020 "@ai-sdk/ui-utils-v5/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@2.2.8", "", { "dependencies": { "@ai-sdk/provider": "1.1.3", "nanoid": "^3.3.8", "secure-json-parse": "^2.7.0" }, "peerDependencies": { "zod": "^3.23.8" } }, "sha512-fqhG+4sCVv8x7nFzYnFo19ryhAa3w096Kmc3hWxMQfW/TubPOmt3A6tYZhl4mUfQWWQMsuSkLrtjlWuXBVSGQA=="],
2021
2022 - "@composio/core/openai": ["openai@7.34.0", "", { "peerDependencies": { "@aws-sdk/credential-provider-node": ">=3.972.0 <4", "@smithy/hash-node": ">=4.3.0 <5", "@smithy/signature-v4": ">=5.4.0 <6", "undici": ">=5 <9", "ws": "^8.21.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["@aws-sdk/credential-provider-node", "@smithy/hash-node", "@smithy/signature-v4", "undici", "ws", "zod"] }, "sha512-PMwuTQ/3cVyWZJOVpb6bzlrQj17uImlnUGQWqh5zHlN/snwK5ww4ZUHW8NYGtH6f9PQOEPxyD/f8WJVIHp1q2A=="],
2022 + "@composio/core/openai": ["openai@7.47.0", "", { "peerDependencies": { "@aws-sdk/credential-provider-node": ">=3.972.0 <4", "@smithy/hash-node": ">=4.3.0 <5", "@smithy/signature-v4": ">=5.4.0 <6", "google-auth-library": ">=9.15.1 <12", "undici": ">=5 <9", "ws": "^8.21.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["@aws-sdk/credential-provider-node", "@smithy/hash-node", "@smithy/signature-v4", "google-auth-library", "undici", "ws", "zod"] }, "sha512-BYa2RYgocAv9WjPUJmNu8fICuA1fFhkTBEpiR3sC5L1K6v8Hnhc8pcnQEhu8l/+W1XKA+JUaBa7HpT+AK1s77w=="],
2023
2024 "@floating-ui/react-dom/@floating-ui/dom": ["@floating-ui/dom@1.8.0", "", { "dependencies": { "@floating-ui/core": "^1.8.0", "@floating-ui/utils": "^0.2.12" } }, "sha512-yXSrzeHZBTZadLOlfyhCkJHNeLJnHRnRInwdZ40L7ZiaAtrBwoYlsDrX3v5zB1Utk7CLfzcOVnVVWoXEky7Ceg=="],
2025
docs/content/docs/extending-sessions/custom-mcp.mdx
+261 -137
@@ -1,11 +1,11 @@
1 ---
2 title: Custom MCP
3 description: Use tools from a remote MCP server in Composio sessions
4 -keywords: [custom mcp, bring your own mcp, remote mcp, custom toolkits, experimental, dcr, cimd, discovery, revocation]
4 +keywords: [custom mcp, bring your own mcp, remote mcp, custom toolkits, end user mcp, private toolkit, experimental, dcr, cimd, discovery, revocation]
5 experimental: true
6 ---
7
8 -Custom MCP lets you use tools from your remote MCP server in the same session as Composio's built-in toolkits. Register the server, connect it if authentication is required, then add its synced `CUSTOM_*` toolkit slug to a session.
8 +Custom MCP lets you use tools from your remote MCP server in the same session as Composio's built-in toolkits. A Custom MCP is either shared with every user in your project or private to one end user, so your users can bring their own MCP servers. Register the server, connect it if authentication is required, then add its synced `CUSTOM_*` toolkit slug to a session.
9
10 <Callout type="warn">
11 Custom MCP is experimental. Its setup flow, authentication options, and API contracts may change while we work with early customers.
@@ -18,18 +18,18 @@ This is different from [Custom Tools and Toolkits](/docs/extending-sessions/cust
18 A Custom MCP moves through this lifecycle:
19
20 1. **Deploy** your MCP server at a public HTTPS URL.
21 -2. **Register** its URL and authentication scheme. Composio creates a project-scoped `CUSTOM_*` toolkit.
21 +2. **Register** its URL and authentication scheme. Composio creates a `CUSTOM_*` toolkit, shared or private to one user.
22 3. **Connect** an account if the server uses an API key or DCR OAuth. No-auth servers skip this step.
23 4. **Sync** its tools. The first sync starts automatically; later tool changes require a manual sync.
24 5. **Use** the toolkit in a session.
25
26 <Callout type="warn" title="API-only while Custom MCP is experimental">
27 -Use the lifecycle endpoints below to register, sync, and delete Custom MCP toolkits. You can also use the experimental SDK methods described below. These contracts may change while Custom MCP is experimental. The API reference has the full request and response schemas for [upsert](/reference/api-reference/toolkits/postCustomToolkitsUpsert), [sync](/reference/api-reference/toolkits/postCustomToolkitsSync), and [delete](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug). Dashboard management is coming soon for customers who prefer a UI.
27 +Use the lifecycle endpoints below to create, update, sync, and delete Custom MCP toolkits. You can also use the experimental SDK methods described below. These contracts may change while Custom MCP is experimental. The API reference has the full request and response schemas for [create](/reference/api-reference/toolkits/postCustomToolkits), [update](/reference/api-reference/toolkits/patchCustomToolkitsBySlug), [sync](/reference/api-reference/toolkits/postCustomToolkitsSync), and [delete](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug). Dashboard management is coming soon for customers who prefer a UI.
28 </Callout>
29
30 ### Manage custom toolkits with the SDK
31
32 -You can also run this lifecycle through `composio.experimental.custom_toolkits` in Python or `composio.experimental.customToolkits` in TypeScript. Both provide `upsert()` to register a toolkit or update its display metadata, `sync()` to fetch its remote tool definitions, and `delete()` to remove it and its associated auth configs and connections.
32 +You can also run this lifecycle through `composio.experimental.custom_toolkits` in Python or `composio.experimental.customToolkits` in TypeScript. Both provide `create()` to register a toolkit, `update()` to change its name or logo, `sync()` to fetch its remote tool definitions, and `delete()` to remove it and its associated auth configs and connections. `upsert()` is deprecated; use `create()` and `update()`.
33
34 <Callout>
35 These project-owned toolkit APIs are experimental. They manage remote toolkits registered in Composio; [local custom toolkits](/docs/extending-sessions/custom-tools-and-toolkits) run in your SDK process.
@@ -37,7 +37,7 @@ These project-owned toolkit APIs are experimental. They manage remote toolkits r
37
38 ## Register a Custom MCP
39
40 -Call `POST /api/v3.1/custom/toolkits/upsert` with your public server URL and authentication scheme. Authenticate the request with your Composio project API key.
40 +Call `POST /api/v3.1/custom/toolkits` with your public server URL, authentication scheme, and `user_id`. Set `user_id` to `"all"` to share the toolkit with every user in your project, or [to one user's ID](#create-a-toolkit-for-one-end-user). Authenticate the request with your Composio project API key.
41
42 <Callout type="warn" title="Serve the registered endpoint directly">
43 Use the final HTTPS MCP endpoint as `app_url`, without redirects. Cross-origin redirects strip `Authorization`, but custom credential headers can remain attached. Custom MCP does not expose a redirect policy that guarantees credentials stay on the registered origin. Keep keys out of the URL. If a credential reaches an untrusted destination, revoke or rotate it at its issuer.
@@ -48,13 +48,11 @@ Use the final HTTPS MCP endpoint as `app_url`, without redirects. Cross-origin r
48 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
49 <Tab value="Python">
50 ```python
51 -result = composio.experimental.custom_toolkits.upsert(
52 - slug="ACME",
53 - toolkit_config={
54 - "name": "Acme",
55 - "app_url": "https://mcp.example.com/mcp",
56 - "auth_schemes": [{"mode": "NO_AUTH"}],
57 - },
51 +result = composio.experimental.custom_toolkits.create(
52 + name="Acme",
53 + app_url="https://mcp.acme.com/mcp",
54 + auth_schemes=[{"mode": "NO_AUTH"}],
55 + user_id="all",
56 )
57
58 print(result.slug) # CUSTOM_ACME
@@ -65,13 +63,11 @@ print(result.slug) # CUSTOM_ACME
63 import { Composio } from '@composio/core';
64 const composio = new Composio();
65 // ---cut---
68 -const result = await composio.experimental.customToolkits.upsert({
69 - slug: 'ACME',
70 - toolkitConfig: {
71 - name: 'Acme',
72 - appUrl: 'https://mcp.example.com/mcp',
73 - authSchemes: [{ mode: 'NO_AUTH' }],
74 - },
66 +const result = await composio.experimental.customToolkits.create({
67 + name: 'Acme',
68 + appUrl: 'https://mcp.acme.com/mcp',
69 + authSchemes: [{ mode: 'NO_AUTH' }],
70 + userId: 'all',
71 });
72
73 console.log(result.slug); // CUSTOM_ACME
@@ -79,16 +75,14 @@ console.log(result.slug); // CUSTOM_ACME
75 </Tab>
76 <Tab value="API">
77 ```bash
82 -curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
78 +curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
79 -H "x-api-key: $COMPOSIO_API_KEY" \
80 -H "Content-Type: application/json" \
81 -d '{
86 - "slug": "ACME",
87 - "toolkit_config": {
88 - "name": "Acme",
89 - "app_url": "https://mcp.example.com/mcp",
90 - "auth_schemes": [{"mode": "NO_AUTH"}]
91 - }
82 + "name": "Acme",
83 + "app_url": "https://mcp.acme.com/mcp",
84 + "auth_schemes": [{"mode": "NO_AUTH"}],
85 + "user_id": "all"
86 }'
87 ```
88 </Tab>
@@ -98,18 +92,16 @@ curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
92 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
93 <Tab value="Python">
94 ```python
101 -result = composio.experimental.custom_toolkits.upsert(
102 - slug="ACME",
103 - toolkit_config={
104 - "name": "Acme",
105 - "app_url": "https://mcp.example.com/mcp",
106 - "auth_schemes": [
107 - {
108 - "mode": "API_KEY",
109 - "headers": {"Authorization": "Bearer {{generic_api_key}}"},
110 - }
111 - ],
112 - },
95 +result = composio.experimental.custom_toolkits.create(
96 + name="Acme",
97 + app_url="https://mcp.acme.com/mcp",
98 + auth_schemes=[
99 + {
100 + "mode": "API_KEY",
101 + "headers": {"Authorization": "Bearer {{generic_api_key}}"},
102 + }
103 + ],
104 + user_id="all",
105 )
106
107 print(result.slug) # CUSTOM_ACME
@@ -120,15 +112,13 @@ print(result.slug) # CUSTOM_ACME
112 import { Composio } from '@composio/core';
113 const composio = new Composio();
114 // ---cut---
123 -const result = await composio.experimental.customToolkits.upsert({
124 - slug: 'ACME',
125 - toolkitConfig: {
126 - name: 'Acme',
127 - appUrl: 'https://mcp.example.com/mcp',
128 - authSchemes: [
129 - { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
130 - ],
131 - },
115 +const result = await composio.experimental.customToolkits.create({
116 + name: 'Acme',
117 + appUrl: 'https://mcp.acme.com/mcp',
118 + authSchemes: [
119 + { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
120 + ],
121 + userId: 'all',
122 });
123
124 console.log(result.slug); // CUSTOM_ACME
@@ -136,21 +126,19 @@ console.log(result.slug); // CUSTOM_ACME
126 </Tab>
127 <Tab value="API">
128 ```bash
139 -curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
129 +curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
130 -H "x-api-key: $COMPOSIO_API_KEY" \
131 -H "Content-Type: application/json" \
132 -d '{
143 - "slug": "ACME",
144 - "toolkit_config": {
145 - "name": "Acme",
146 - "app_url": "https://mcp.example.com/mcp",
147 - "auth_schemes": [
148 - {
149 - "mode": "API_KEY",
150 - "headers": {"Authorization": "Bearer {{generic_api_key}}"}
151 - }
152 - ]
153 - }
133 + "name": "Acme",
134 + "app_url": "https://mcp.acme.com/mcp",
135 + "auth_schemes": [
136 + {
137 + "mode": "API_KEY",
138 + "headers": {"Authorization": "Bearer {{generic_api_key}}"}
139 + }
140 + ],
141 + "user_id": "all"
142 }'
143 ```
144 </Tab>
@@ -162,18 +150,16 @@ curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
150 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
151 <Tab value="Python">
152 ```python
165 -result = composio.experimental.custom_toolkits.upsert(
166 - slug="ACME",
167 - toolkit_config={
168 - "name": "Acme",
169 - "app_url": "https://mcp.example.com/mcp",
170 - "auth_schemes": [
171 - {
172 - "mode": "DCR_OAUTH",
173 - "discovery_url": "https://mcp.example.com/.well-known/oauth-authorization-server",
174 - }
175 - ],
176 - },
153 +result = composio.experimental.custom_toolkits.create(
154 + name="Acme",
155 + app_url="https://mcp.acme.com/mcp",
156 + auth_schemes=[
157 + {
158 + "mode": "DCR_OAUTH",
159 + "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server",
160 + }
161 + ],
162 + user_id="all",
163 )
164
165 print(result.slug) # CUSTOM_ACME
@@ -184,18 +170,16 @@ print(result.slug) # CUSTOM_ACME
170 import { Composio } from '@composio/core';
171 const composio = new Composio();
172 // ---cut---
187 -const result = await composio.experimental.customToolkits.upsert({
188 - slug: 'ACME',
189 - toolkitConfig: {
190 - name: 'Acme',
191 - appUrl: 'https://mcp.example.com/mcp',
192 - authSchemes: [
193 - {
194 - mode: 'DCR_OAUTH',
195 - discoveryUrl: 'https://mcp.example.com/.well-known/oauth-authorization-server',
196 - },
197 - ],
198 - },
173 +const result = await composio.experimental.customToolkits.create({
174 + name: 'Acme',
175 + appUrl: 'https://mcp.acme.com/mcp',
176 + authSchemes: [
177 + {
178 + mode: 'DCR_OAUTH',
179 + discoveryUrl: 'https://mcp.acme.com/.well-known/oauth-authorization-server',
180 + },
181 + ],
182 + userId: 'all',
183 });
184
185 console.log(result.slug); // CUSTOM_ACME
@@ -203,21 +187,19 @@ console.log(result.slug); // CUSTOM_ACME
187 </Tab>
188 <Tab value="API">
189 ```bash
206 -curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
190 +curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
191 -H "x-api-key: $COMPOSIO_API_KEY" \
192 -H "Content-Type: application/json" \
193 -d '{
210 - "slug": "ACME",
211 - "toolkit_config": {
212 - "name": "Acme",
213 - "app_url": "https://mcp.example.com/mcp",
214 - "auth_schemes": [
215 - {
216 - "mode": "DCR_OAUTH",
217 - "discovery_url": "https://mcp.example.com/.well-known/oauth-authorization-server"
218 - }
219 - ]
220 - }
194 + "name": "Acme",
195 + "app_url": "https://mcp.acme.com/mcp",
196 + "auth_schemes": [
197 + {
198 + "mode": "DCR_OAUTH",
199 + "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server"
200 + }
201 + ],
202 + "user_id": "all"
203 }'
204 ```
205 </Tab>
@@ -225,23 +207,109 @@ curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
207 </Tab>
208 </Tabs>
209
228 -Composio adds the `CUSTOM_` prefix and returns the normalized toolkit slug:
210 +Composio picks the slug from the server's domain and adds a random suffix if that slug is taken. Store it: you need it to sync, update, or delete the toolkit.
211
212 ```json
213 {
232 - "slug": "CUSTOM_ACME"
214 + "slug": "CUSTOM_ACME",
215 + "connect_link": null
216 }
217 ```
218
236 -<Callout type="warn" title="app_url and auth_schemes are immutable">
237 -Re-registering a slug your project already owns updates the toolkit in place: mutable fields like the name and logo take the new values, and an identical config is a harmless no-op. Two fields can't change after registration: `app_url` and `auth_schemes`. Changing either returns `409 Conflict`; [delete the existing toolkit](#delete-or-replace-a-custom-mcp), then register it again.
219 +<Callout type="warn" title="app_url, auth_schemes, and user_id are immutable">
220 +`app_url`, `auth_schemes`, and `user_id` can't change after creation. To change the name, logo, or API key field label, [update the toolkit](#update-a-toolkit). To change anything else, [delete the toolkit](#delete-or-replace-a-custom-mcp) and create it again.
221 </Callout>
222
223 +### Create a toolkit for one end user
224 +
225 +Set `user_id` to an end user's ID to make the toolkit private to them: only sessions and API calls for that user can see or run its tools. A private toolkit's slug always has a random suffix, such as `CUSTOM_ACME_K7F2Q`.
226 +
227 +<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
228 +<Tab value="Python">
229 +```python
230 +result = composio.experimental.custom_toolkits.create(
231 + name="Acme",
232 + app_url="https://mcp.acme.com/mcp",
233 + auth_schemes=[
234 + {
235 + "mode": "DCR_OAUTH",
236 + "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server",
237 + }
238 + ],
239 + user_id="user_123",
240 + callback_url="https://app.example.com/connected",
241 +)
242 +
243 +print(result.slug) # CUSTOM_ACME_K7F2Q
244 +if result.connect_link is not None:
245 + print(result.connect_link.redirect_url) # send user_123 here
246 +```
247 +</Tab>
248 +<Tab value="TypeScript">
249 +```typescript
250 +import { Composio } from '@composio/core';
251 +const composio = new Composio();
252 +// ---cut---
253 +const result = await composio.experimental.customToolkits.create({
254 + name: 'Acme',
255 + appUrl: 'https://mcp.acme.com/mcp',
256 + authSchemes: [
257 + {
258 + mode: 'DCR_OAUTH',
259 + discoveryUrl: 'https://mcp.acme.com/.well-known/oauth-authorization-server',
260 + },
261 + ],
262 + userId: 'user_123',
263 + callbackUrl: 'https://app.example.com/connected',
264 +});
265 +
266 +console.log(result.slug); // CUSTOM_ACME_K7F2Q
267 +if (result.connectLink) {
268 + console.log(result.connectLink.redirectUrl); // send user_123 here
269 +}
270 +```
271 +</Tab>
272 +<Tab value="API">
273 +```bash
274 +curl -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
275 + -H "x-api-key: $COMPOSIO_API_KEY" \
276 + -H "Content-Type: application/json" \
277 + -d '{
278 + "name": "Acme",
279 + "app_url": "https://mcp.acme.com/mcp",
280 + "auth_schemes": [
281 + {
282 + "mode": "DCR_OAUTH",
283 + "discovery_url": "https://mcp.acme.com/.well-known/oauth-authorization-server"
284 + }
285 + ],
286 + "user_id": "user_123",
287 + "callback_url": "https://app.example.com/connected"
288 + }'
289 +```
290 +</Tab>
291 +</Tabs>
292 +
293 +```json
294 +{
295 + "slug": "CUSTOM_ACME_K7F2Q",
296 + "connect_link": {
297 + "redirect_url": "https://connect.composio.dev/link/lk_...",
298 + "expires_at": "2026-11-03T12:10:00.000Z",
299 + "connected_account_id": "ca_..."
300 + }
301 +}
302 +```
303 +
304 +For a private toolkit that needs authentication, `connect_link` is a hosted connect page for that user. Send them to `redirect_url`; once they connect, the tools sync automatically. `connect_link` is `null` for no-auth and shared toolkits, or if the link couldn't be created. To get a new link, call [`POST /api/v3.1/connected_accounts/link`](/reference/api-reference/connected-accounts/postConnectedAccountsLink).
305 +
306 +A second private toolkit for the same user and MCP URL returns `409 Conflict`, as does a second shared toolkit for the same URL. `"default"` and other spellings of `"all"`, such as `"ALL"`, return `400`.
307 +
308 ## Add a toolkit logo
309
242 -Without a logo, your toolkit shows the Composio logo in the dashboard and on end-user connect screens. To ship your own branding, include `toolkit_config.logo_file` when you register: the image itself, base64-encoded. Composio validates it, stores it on Composio-hosted asset storage, and renders it everywhere the toolkit appears. You don't host anything, and the logo keeps working even if your own site changes or goes down.
310 +Without a logo, your toolkit shows the Composio logo in the dashboard and on end-user connect screens. To ship your own branding, include `logo_file` when you create the toolkit: the image itself, base64-encoded. Composio validates it, stores it on Composio-hosted asset storage, and renders it everywhere the toolkit appears. You don't host anything, and the logo keeps working even if your own site changes or goes down.
311
244 -Save your PNG as `logo.png`. This example updates the `NO_AUTH` registration above; preserve the original `app_url` and `auth_schemes` if you selected another auth mode.
312 +Save your PNG as `logo.png`. This example creates the `NO_AUTH` toolkit above with a logo; use the auth scheme you selected.
313
314 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
315 <Tab value="Python">
@@ -252,17 +320,15 @@ from composio import Composio
320
321 composio = Composio()
322 logo_content = b64encode(Path("logo.png").read_bytes()).decode("ascii")
255 -result = composio.experimental.custom_toolkits.upsert(
256 - slug="ACME",
257 - toolkit_config={
258 - "name": "Acme",
259 - "app_url": "https://mcp.example.com/mcp",
260 - "logo_file": {
261 - "content": logo_content,
262 - "mime_type": "image/png",
263 - },
264 - "auth_schemes": [{"mode": "NO_AUTH"}],
323 +result = composio.experimental.custom_toolkits.create(
324 + name="Acme",
325 + app_url="https://mcp.acme.com/mcp",
326 + logo_file={
327 + "content": logo_content,
328 + "mime_type": "image/png",
329 },
330 + auth_schemes=[{"mode": "NO_AUTH"}],
331 + user_id="all",
332 )
333
334 print(result.slug) # CUSTOM_ACME
@@ -275,17 +341,15 @@ import { readFileSync } from 'node:fs';
341 const composio = new Composio();
342 // ---cut---
343 const logoContent = readFileSync('logo.png').toString('base64');
278 -const result = await composio.experimental.customToolkits.upsert({
279 - slug: 'ACME',
280 - toolkitConfig: {
281 - name: 'Acme',
282 - appUrl: 'https://mcp.example.com/mcp',
283 - logoFile: {
284 - content: logoContent,
285 - mimeType: 'image/png',
286 - },
287 - authSchemes: [{ mode: 'NO_AUTH' }],
344 +const result = await composio.experimental.customToolkits.create({
345 + name: 'Acme',
346 + appUrl: 'https://mcp.acme.com/mcp',
347 + logoFile: {
348 + content: logoContent,
349 + mimeType: 'image/png',
350 },
351 + authSchemes: [{ mode: 'NO_AUTH' }],
352 + userId: 'all',
353 });
354
355 console.log(result.slug); // CUSTOM_ACME
@@ -295,20 +359,18 @@ console.log(result.slug); // CUSTOM_ACME
359 ```bash
360 set -euo pipefail
361 LOGO_BASE64=$(base64 < logo.png | tr -d '\n')
298 -curl --fail-with-body -X POST https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
362 +curl --fail-with-body -X POST https://backend.composio.dev/api/v3.1/custom/toolkits \
363 -H "x-api-key: $COMPOSIO_API_KEY" \
364 -H "Content-Type: application/json" \
365 -d '{
302 - "slug": "ACME",
303 - "toolkit_config": {
304 - "name": "Acme",
305 - "app_url": "https://mcp.example.com/mcp",
306 - "logo_file": {
307 - "content": "'"$LOGO_BASE64"'",
308 - "mime_type": "image/png"
309 - },
310 - "auth_schemes": [{"mode": "NO_AUTH"}]
311 - }
366 + "name": "Acme",
367 + "app_url": "https://mcp.acme.com/mcp",
368 + "logo_file": {
369 + "content": "'"$LOGO_BASE64"'",
370 + "mime_type": "image/png"
371 + },
372 + "auth_schemes": [{"mode": "NO_AUTH"}],
373 + "user_id": "all"
374 }'
375 ```
376 </Tab>
@@ -320,7 +382,67 @@ Set `content` to your image encoded as base64: a single line, with no line break
382 - **Square**, between 256 and 1024 pixels
383 - **At most 3MB** before encoding
384
323 -Omit `logo_file` to keep the Composio default. To change a logo later, re-register the same slug with the new image: the upsert updates the toolkit in place.
385 +Omit `logo_file` to keep the Composio default.
386 +
387 +## Update a toolkit
388 +
389 +Call `PATCH /api/v3.1/custom/toolkits/{slug}` to change `name`, `logo_file`, or the API key field's label (`api_key_field`). Omitted fields keep their value. On a project with 2FA enabled, updating a private toolkit requires the `user_id` it is private to.
390 +
391 +This example replaces the logo:
392 +
393 +<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
394 +<Tab value="Python">
395 +```python
396 +from base64 import b64encode
397 +from pathlib import Path
398 +from composio import Composio
399 +
400 +composio = Composio()
401 +logo_content = b64encode(Path("logo.png").read_bytes()).decode("ascii")
402 +result = composio.experimental.custom_toolkits.update(
403 + "CUSTOM_ACME",
404 + logo_file={
405 + "content": logo_content,
406 + "mime_type": "image/png",
407 + },
408 +)
409 +
410 +print(result.success) # True
411 +```
412 +</Tab>
413 +<Tab value="TypeScript">
414 +```typescript
415 +import { Composio } from '@composio/core';
416 +import { readFileSync } from 'node:fs';
417 +const composio = new Composio();
418 +// ---cut---
419 +const logoContent = readFileSync('logo.png').toString('base64');
420 +const result = await composio.experimental.customToolkits.update('CUSTOM_ACME', {
421 + logoFile: {
422 + content: logoContent,
423 + mimeType: 'image/png',
424 + },
425 +});
426 +
427 +console.log(result.success); // true
428 +```
429 +</Tab>
430 +<Tab value="API">
431 +```bash
432 +set -euo pipefail
433 +LOGO_BASE64=$(base64 < logo.png | tr -d '\n')
434 +curl --fail-with-body -X PATCH https://backend.composio.dev/api/v3.1/custom/toolkits/CUSTOM_ACME \
435 + -H "x-api-key: $COMPOSIO_API_KEY" \
436 + -H "Content-Type: application/json" \
437 + -d '{
438 + "logo_file": {
439 + "content": "'"$LOGO_BASE64"'",
440 + "mime_type": "image/png"
441 + }
442 + }'
443 +```
444 +</Tab>
445 +</Tabs>
446
447 ## Complete setup for your authentication mode
448
@@ -434,7 +556,7 @@ A Custom MCP toolkit can contain at most 500 tools. If the server returns more t
556
557 ## Delete or replace a Custom MCP
558
437 -Re-registering a slug updates mutable fields like the name and logo, but `app_url` and `auth_schemes` can't change after registration. To replace either, delete the toolkit and register it again.
559 +[Update](#update-a-toolkit) changes the name and logo, but `app_url`, `auth_schemes`, and `user_id` can't change. To replace one, delete the toolkit and create it again.
560
561 Call `DELETE /api/v3.1/custom/toolkits/{slug}`:
562
@@ -523,6 +645,8 @@ curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_I
645 </Tab>
646 </Tabs>
647
648 +A session only sees the custom toolkits its `user_id` can use. Naming another user's private toolkit in `toolkits` returns `400`, and executing its tools returns `403`.
649 +
650 With the default search-first session, your agent uses `COMPOSIO_SEARCH_TOOLS` to discover the custom tools and the Tool Router to execute them. If a synced tool is missing from search, see [troubleshooting discovery](#troubleshoot-missing-search-results).
651
652 ### Use an authenticated server
@@ -586,7 +710,7 @@ The pinned account must belong to the custom toolkit and be active. Explicit sel
710
711 ## Technical behavior
712
589 -List your custom toolkits with `GET /api/v3.1/toolkits?type=custom`.
713 +List your custom toolkits with `GET /api/v3.1/toolkits?type=custom`. Add `user_id` to include the toolkits private to that user; each toolkit's `access` is `"all"` or `"user"`.
714
715 Each registered server becomes a custom toolkit scoped to your project:
716
@@ -656,7 +780,7 @@ Reconnects and repeated syncs do not bypass the search-path limit, and there is
780
781 - **Dashboard coming soon:** Custom MCP management isn't available in the dashboard yet.
782 - **Remote servers only:** Composio doesn't host your server. Deploy it at a public HTTPS endpoint; local and STDIO-only servers aren't supported.
659 -- **Immutable `app_url` and `auth_schemes`:** Re-registering an existing slug updates other fields in place, but changing `app_url` or `auth_schemes` returns `409 Conflict`. Delete the toolkit, then register it again. Deletion also removes its auth configurations and connected accounts.
783 +- **Immutable `app_url`, `auth_schemes`, and `user_id`:** Update changes only the name, logo, and API key field label. Delete the toolkit and create it again to change anything else. Deletion also removes its auth configurations and connected accounts.
784 - **500-tool limit:** Split larger servers into smaller MCP servers. If a later sync exceeds the limit, the last successful version stays available.
785
786 </Accordion>
docs/package.json
+1 -1
@@ -91,7 +91,7 @@
91 "@anthropic-ai/sdk": "^0.115.0",
92 "@composio/anthropic": "^0.11.6",
93 "@composio/claude-agent-sdk": "^0.13.0",
94 - "@composio/core": "^0.27.0",
94 + "@composio/core": "^0.28.0",
95 "@composio/google": "^0.12.0",
96 "@composio/langchain": "^0.11.2",
97 "@composio/llamaindex": "^0.11.2",