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]
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.
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.
12
+</Callout>
13
+
14
+This is different from [Custom Tools and Toolkits](/docs/extending-sessions/custom-tools-and-toolkits). Custom tools run inside your application. A custom MCP server runs outside Composio and exposes its tools over a public HTTPS endpoint.
15
+
16
+## Custom MCP lifecycle
17
+
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.
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. For authenticated servers, explicitly select the connected account.
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. They aren't included in the public API reference or SDKs yet, and their contracts may change. Dashboard management is coming soon for customers who prefer a UI.
28
+</Callout>
29
+
30
+## Register a Custom MCP
31
+
32
+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.
33
+
34
+<Tabs items={['No auth', 'API key', 'DCR OAuth']}>
35
+<Tab value="No auth">
36
+```bash
37
+curl --request POST \
38
+ --url https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
39
+ --header "x-api-key: $COMPOSIO_API_KEY" \
40
+ --header "Content-Type: application/json" \
41
+ --data '{
42
+ "slug": "ACME",
43
+ "toolkit_config": {
44
+ "name": "Acme",
45
+ "app_url": "https://mcp.example.com/mcp",
46
+ "auth_schemes": [
47
+ {
48
+ "mode": "NO_AUTH"
49
+ }
50
+ ]
51
+ }
52
+ }'
53
+```
54
+</Tab>
55
+<Tab value="API key">
56
+```bash
57
+curl --request POST \
58
+ --url https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
59
+ --header "x-api-key: $COMPOSIO_API_KEY" \
60
+ --header "Content-Type: application/json" \
61
+ --data '{
62
+ "slug": "ACME",
63
+ "toolkit_config": {
64
+ "name": "Acme",
65
+ "app_url": "https://mcp.example.com/mcp",
66
+ "auth_schemes": [
67
+ {
68
+ "mode": "API_KEY",
69
+ "headers": {
70
+ "Authorization": "Bearer {{generic_api_key}}"
71
+ }
72
+ }
73
+ ]
74
+ }
75
+ }'
76
+```
77
+
78
+`generic_api_key` is replaced with the credential stored on the connected account. You can use a different header name or value format, but at least one header value must contain `{{generic_api_key}}`.
79
+</Tab>
80
+<Tab value="DCR OAuth">
81
+```bash
82
+curl --request POST \
83
+ --url https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \
84
+ --header "x-api-key: $COMPOSIO_API_KEY" \
85
+ --header "Content-Type: application/json" \
86
+ --data '{
87
+ "slug": "ACME",
88
+ "toolkit_config": {
89
+ "name": "Acme",
90
+ "app_url": "https://mcp.example.com/mcp",
91
+ "auth_schemes": [
92
+ {
93
+ "mode": "DCR_OAUTH",
94
+ "discovery_url": "https://mcp.example.com/.well-known/oauth-authorization-server"
95
+ }
96
+ ]
97
+ }
98
+ }'
99
+```
100
+</Tab>
101
+</Tabs>
102
+
103
+Composio adds the `CUSTOM_` prefix and returns the normalized toolkit slug:
104
+
105
+```json
106
+{
107
+ "slug": "CUSTOM_ACME"
108
+}
109
+```
110
+
111
+<Callout type="warn" title="This endpoint only registers new toolkits">
112
+Despite `upsert` in the route name, this endpoint does not update or replace an existing toolkit. If the slug already exists, the request returns `409 Conflict`.
113
+
114
+To change the server URL, name, or authentication scheme, [delete the existing toolkit](#delete-or-replace-a-custom-mcp), then register it again. Deletion also revokes and removes the toolkit's auth configurations and connected accounts.
115
+</Callout>
116
+
117
+## Complete setup for your authentication mode
118
+
119
+Choose the mode that matches your server, then complete any required connection:
120
+
121
+| Authentication | Use it when | After registration |
122
+| --- | --- | --- |
123
+| No auth | The server accepts requests without credentials. | No connection is required. Initial sync runs automatically. |
124
+| API key | Each connected account supplies an API key. | Create an active connection. Initial sync then starts in the background. |
125
+| DCR OAuth | The server supports OAuth Dynamic Client Registration. | Authorize a connection. Initial sync starts when it becomes active. |
126
+
127
+For DCR OAuth, the server must support the standard authorization-code flow. Other OAuth grant types aren't supported.
128
+
129
+## Sync and resync tools
130
+
131
+Call `POST /api/v3.1/custom/toolkits/sync` to fetch the server's current tools:
132
+
133
+```bash
134
+curl --request POST \
135
+ --url https://backend.composio.dev/api/v3.1/custom/toolkits/sync \
136
+ --header "x-api-key: $COMPOSIO_API_KEY" \
137
+ --header "Content-Type: application/json" \
138
+ --data '{
139
+ "slug": "CUSTOM_ACME",
140
+ "connected_account_id": "ca_custom_acme"
141
+ }'
142
+```
143
+
144
+For an API-key or DCR OAuth server, `connected_account_id` must identify an active account from the same toolkit and project. For a no-auth server, omit it:
145
+
146
+```bash
147
+curl --request POST \
148
+ --url https://backend.composio.dev/api/v3.1/custom/toolkits/sync \
149
+ --header "x-api-key: $COMPOSIO_API_KEY" \
150
+ --header "Content-Type: application/json" \
151
+ --data '{
152
+ "slug": "CUSTOM_ACME"
153
+ }'
154
+```
155
+
156
+A successful sync returns the toolkit version and the number of tools discovered:
157
+
158
+```json
159
+{
160
+ "slug": "CUSTOM_ACME",
161
+ "version": "20260728_00",
162
+ "synced_count": 12
163
+}
164
+```
165
+
166
+<Callout type="info" title="When to sync manually">
167
+Composio starts the initial sync automatically:
168
+
169
+- **No auth:** during registration
170
+- **API key or DCR OAuth:** when the first connected account becomes active
171
+
172
+Call the sync endpoint only if the initial sync fails or the server's tool definitions change. Later connections don't resync a toolkit that already has tools.
173
+</Callout>
174
+
175
+A Custom MCP toolkit can contain at most 500 tools. If the server returns more than 500, the sync fails without importing a partial tool list. The last successful version stays available.
176
+
177
+## Delete or replace a Custom MCP
178
+
179
+The registration endpoint cannot update an existing toolkit. To replace its URL, name, or authentication scheme, delete the toolkit and register it again.
180
+
181
+Call `DELETE /api/v3.1/custom/toolkits/{slug}`:
182
+
183
+```bash
184
+curl --request DELETE \
185
+ --url https://backend.composio.dev/api/v3.1/custom/toolkits/CUSTOM_ACME \
186
+ --header "x-api-key: $COMPOSIO_API_KEY"
187
+```
188
+
189
+```json
190
+{
191
+ "slug": "CUSTOM_ACME",
192
+ "deleted": true,
193
+ "revoke_job_ids": ["job_123"],
194
+ "auth_configs_soft_deleted": 1,
195
+ "connected_accounts_soft_deleted": 1
196
+}
197
+```
198
+
199
+<Callout type="warn" title="Deletion also removes connections">
200
+Deletion removes the custom toolkit and its tools. It also revokes and removes the toolkit's auth configurations and connected accounts. Any replacement starts with new connections.
201
+</Callout>
202
+
203
+## Use Custom MCP in a session
204
+
205
+Once the toolkit is synced, add its `CUSTOM_*` slug to a session.
206
+
207
+### Use a no-auth server
208
+
209
+Pass the toolkit slug when you create the session:
210
+
211
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
212
+<Tab value="Python">
213
+```python
214
+from composio import Composio
215
+
216
+composio = Composio(api_key="your_api_key")
217
+
218
+session = composio.sessions.create(
219
+ user_id="user_123",
220
+ toolkits=["CUSTOM_ACME"],
221
+)
222
+
223
+tools = session.tools()
224
+```
225
+</Tab>
226
+<Tab value="TypeScript">
227
+```typescript
228
+import { Composio } from "@composio/core";
229
+
230
+const composio = new Composio({ apiKey: "your_api_key" });
231
+
232
+const session = await composio.sessions.create("user_123", {
233
+ toolkits: ["CUSTOM_ACME"],
234
+});
235
+
236
+const tools = await session.tools();
237
+```
238
+</Tab>
239
+</Tabs>
240
+
241
+With the default search-first session, your agent can discover the custom tools through `COMPOSIO_SEARCH_TOOLS` and execute them through the Tool Router.
242
+
243
+### Use an authenticated server
244
+
245
+For API-key and DCR OAuth servers, explicitly select the connected account in the session config. Don't rely on automatic account matching for Custom MCP toolkits yet.
246
+
247
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
248
+<Tab value="Python">
249
+```python
250
+from composio import Composio
251
+
252
+composio = Composio(api_key="your_api_key")
253
+
254
+session = composio.sessions.create(
255
+ user_id="user_123",
256
+ toolkits=["CUSTOM_ACME"],
257
+ connected_accounts={
258
+ "CUSTOM_ACME": ["ca_custom_acme"],
259
+ },
260
+)
261
+```
262
+</Tab>
263
+<Tab value="TypeScript">
264
+```typescript
265
+import { Composio } from "@composio/core";
266
+
267
+const composio = new Composio({ apiKey: "your_api_key" });
268
+
269
+const session = await composio.sessions.create("user_123", {
270
+ toolkits: ["CUSTOM_ACME"],
271
+ connectedAccounts: {
272
+ CUSTOM_ACME: ["ca_custom_acme"],
273
+ },
274
+});
275
+```
276
+</Tab>
277
+</Tabs>
278
+
279
+The pinned account must belong to the custom toolkit and be active. Explicit selection ensures tool calls use its credentials.
280
+
281
+## What you manage and what Composio handles
282
+
283
+| Area | You manage | Composio handles |
284
+| --- | --- | --- |
285
+| Server | Deploying and operating the remote MCP server at a public HTTPS URL. | Connecting to the URL for tool discovery and execution. Composio does not host the server. |
286
+| Tools | Implementing tools and deciding when later definition changes are ready to sync. | Starting the initial sync, importing tool schemas, versioning them, and exposing them to sessions. |
287
+| Authentication | Implementing the server's API-key or DCR OAuth behavior and completing each required connection. | Storing connected-account credentials and sending them when discovering or calling tools. |
288
+| Lifecycle | Choosing when to resync, delete, or replace the toolkit. | Providing the project-scoped registration, sync, and deletion operations. |
289
+
290
+## Technical behavior
291
+
292
+Each registered server becomes a custom toolkit scoped to your project:
293
+
294
+- The toolkit has `type: "custom"` and the `CUSTOM` category.
295
+- Its slug starts with `CUSTOM_`, such as `CUSTOM_ACME`.
296
+- Its tools are available through Tool Router search and toolkit-filtered tool listing.
297
+- Tool execution is proxied to your MCP server with the selected connected account's credentials.
298
+
299
+Custom toolkits use dated registry versions. The v3.1 tools API selects the latest version by default. If you use v3 directly, select the latest version for each operation:
300
+
301
+| v3 operation | Select the latest version |
302
+| --- | --- |
303
+| List tools | Add the `toolkit_versions=latest` query parameter. |
304
+| Retrieve one tool | Add the `version=latest` query parameter. |
305
+| Execute one tool | Set `"version": "latest"` in the request body. |
306
+
307
+See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more examples.
308
+
309
+## Known gaps
310
+
311
+<Accordions>
312
+<Accordion title="Setup and lifecycle">
313
+
314
+- **API-only setup:** The SDKs don't expose registration, sync, update, or deletion methods yet. Use the lifecycle endpoints on this page, then use the toolkit slug through the SDK.
315
+- **Dashboard coming soon:** Custom MCP management isn't available in the dashboard yet.
316
+- **Remote servers only:** Composio doesn't host your server. Deploy it at a public HTTPS endpoint; local and STDIO-only servers aren't supported.
317
+- **Insert-only registration:** The `upsert` endpoint returns `409 Conflict` for an existing slug. Delete the toolkit, then register it again. Deletion also removes its auth configurations and connected accounts.
318
+- **500-tool limit:** Split larger servers into smaller MCP servers. If a later sync exceeds the limit, the last successful version stays available.
319
+
320
+</Accordion>
321
+<Accordion title="Sync and authentication">
322
+
323
+- **No continuous sync:** Auto-sync only populates an empty toolkit during registration or the first active connection. If it fails, call the sync endpoint with an active connected account. Sync again whenever tool definitions change.
324
+- **API-key validation is limited:** Setup checks that a key was provided, not that the remote server accepts it. Run a safe tool after connecting to verify the credential end to end.
325
+
326
+</Accordion>
327
+<Accordion title="Sessions and tool APIs">
328
+
329
+- **Select authenticated accounts explicitly:** Custom MCP sessions don't reliably match a connected account automatically. Pass its ID through `connected_accounts` in Python or `connectedAccounts` in TypeScript.
330
+- **Prefer the v3.1 tools API:** The v3 tools API pins a default version that doesn't contain custom tools. If you must use v3, explicitly select `latest` as described above.
331
+
332
+</Accordion>
333
+</Accordions>
334
+
335
+## Related guides
336
+
337
+<Cards>
338
+<Card title="Using sessions via MCP" href="/docs/sessions-via-mcp" description="Connect an MCP client to a Composio-hosted session" />
339
+<Card title="Custom Tools and Toolkits" href="/docs/extending-sessions/custom-tools-and-toolkits" description="Run your own tools inside your application process" />
340
+<Card title="Configuring Sessions" href="/docs/configuring-sessions" description="Configure toolkit and tool filtering" />
341
+<Card title="Managing Multiple Connected Accounts" href="/docs/managing-multiple-connected-accounts" description="Select a connected account explicitly" />
342
+</Cards>