@devries-cameron20 / composio-1 / commits / 2cfdd9068
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: document Custom MCP (#3975)

## Summary - add an experimental guide for registering customer-hosted MCP servers - document supported authentication, the registration and sync flow, toolkit behavior, and customer-facing workarounds for known gaps - add the guide to the Extending sessions navigation and cross-link it from the sessions-over-MCP guide ## Why Custom MCP toolkits now have a working platform lifecycle, but customers need one place that clearly distinguishes remote MCP servers from in-process custom tools. The guide also makes the current pilot limitations explicit so customers know which API version, sync flow, account selection, and hosting model to use. ## Validation - `cd docs && bun run lint:links` - `cd docs && bun run types:check` - `git diff --check` Docs-only change, so no changeset is required.

shams haroon committed Jul 29, 2026 at 16:07 UTC 2cfdd90680fb34a613872854526359fdb9945cc4
6 files changed +624 -7
docs/content/docs/extending-sessions/custom-mcp.mdx new
+342
@@ -0,0 +1,342 @@
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>
docs/content/docs/extending-sessions/meta.json
+2 -1
@@ -3,6 +3,7 @@
3 "defaultOpen": true,
4 "pages": [
5 "proxy-execute",
6 - "custom-tools-and-toolkits"
6 + "custom-tools-and-toolkits",
7 + "custom-mcp"
8 ]
9 }
docs/content/docs/sessions-via-mcp.mdx
+4
@@ -8,6 +8,10 @@ By default Composio gives your agent **tools it can call directly**. Composio fo
8
9 If you'd rather connect over the [Model Context Protocol](https://modelcontextprotocol.io), every session also exposes a hosted MCP endpoint. This is useful when you want to plug a session into an MCP-native client like Claude Desktop, Cursor, or any framework's MCP transport. No provider package required.
10
11 +<Callout type="info">
12 +Want to bring tools from your own remote MCP server into Composio instead? See [Custom MCP](/docs/extending-sessions/custom-mcp).
13 +</Callout>
14 +
15 ## The MCP endpoint
16
17 Opt into MCP by passing `mcp: true` when you create the session. The session then exposes its hosted MCP server. Read the URL and headers off `session.mcp`:
docs/content/docs/tools-direct/toolkit-versioning.mdx
+6 -6
@@ -25,18 +25,18 @@ Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions i
25 ## Default version behavior
26
27 <Callout type="warn">
28 -When no version is specified, the API defaults to the base version (`00000000_00`), **not** the latest version. This means the response may contain fewer tools than what's shown on the [platform UI](https://dashboard.composio.dev?utm_source=docs&utm_medium=content&utm_campaign=docs-tools-direct-toolkit-versioning). To get all available tools including ones added in newer versions, explicitly set `toolkit_versions` to `"latest"` or a specific version.
28 +The v3 API defaults to the base version (`00000000_00`) when you don't specify a version. This can return fewer tools than the [platform UI](https://dashboard.composio.dev?utm_source=docs&utm_medium=content&utm_campaign=docs-tools-direct-toolkit-versioning). Pass `toolkit_versions=latest` or a specific version to select a newer version. The v3.1 tools API defaults to the latest version.
29 </Callout>
30
31 -This applies to both the SDK and direct REST API calls:
31 +For example, a v3 tools-list request without `toolkit_versions` returns the base version:
32
33 ```bash
34 -# Without version — returns only tools from the base version
35 -curl 'https://backend.composio.dev/api/v3.1/tools?toolkit_slug=googledrive' \
34 +# Without toolkit_versions: returns tools from the base version
35 +curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive' \
36 -H 'x-api-key: YOUR_API_KEY'
37
38 -# With version=latest — returns all tools including newer ones
39 -curl 'https://backend.composio.dev/api/v3.1/tools?toolkit_slug=googledrive&toolkit_versions=latest' \
38 +# With toolkit_versions=latest: returns tools from the latest version
39 +curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \
40 -H 'x-api-key: YOUR_API_KEY'
41 ```
42
docs/superpowers/plans/2026-07-29-custom-mcp-lifecycle-doc-flow.md new
+183
@@ -0,0 +1,183 @@
1 +# Custom MCP Lifecycle Documentation Flow Implementation Plan
2 +
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4 +
5 +**Goal:** Reorganize the Custom MCP guide into an API-first lifecycle that takes a developer from registration through authenticated setup, syncing, SDK usage, and deletion.
6 +
7 +**Architecture:** Keep the existing `custom-mcp.mdx` route and verified endpoint examples. Reorder its content into one lifecycle, move reference material after the lifecycle, and add a compact operational responsibility boundary without changing platform or SDK contracts.
8 +
9 +**Tech Stack:** MDX, Fumadocs components, cURL, Python SDK examples, TypeScript SDK examples
10 +
11 +## Global Constraints
12 +
13 +- Custom MCP remains marked experimental.
14 +- Registration uses `POST /api/v3/custom/toolkits/upsert` and is insert-only.
15 +- Sync uses `POST /api/v3/custom/toolkits/sync`.
16 +- Delete uses `DELETE /api/v3.1/custom/toolkits/{slug}`.
17 +- No-auth registration performs the initial sync automatically.
18 +- API-key and DCR OAuth toolkits require an active connected account before syncing.
19 +- Later tool changes require manual resync.
20 +- A Custom MCP toolkit contains at most 500 tools.
21 +- Lifecycle operations are not exposed through the Python or TypeScript SDKs.
22 +- The dashboard remains a short alternative callout, not a parallel walkthrough.
23 +- Do not add a changeset for this docs-only change.
24 +
25 +---
26 +
27 +### Task 1: Reflow the Custom MCP lifecycle guide
28 +
29 +**Files:**
30 +- Modify: `docs/content/docs/extending-sessions/custom-mcp.mdx`
31 +
32 +**Interfaces:**
33 +- Consumes: Existing Custom MCP endpoint contracts, SDK examples, versioning guidance, and known gaps.
34 +- Produces: One API-first lifecycle guide at `/docs/extending-sessions/custom-mcp`.
35 +
36 +- [x] **Step 1: Replace the current disconnected section order**
37 +
38 +Reorder the existing content into:
39 +
40 +```text
41 +Introduction
42 +Custom MCP lifecycle
43 +Register a Custom MCP
44 +Complete setup for your authentication mode
45 +Sync and resync tools
46 +Delete or replace a Custom MCP
47 +Authentication types
48 +Use Custom MCP in a session
49 +What you manage and what Composio handles
50 +Technical behavior
51 +Known gaps
52 +Related guides
53 +```
54 +
55 +- [x] **Step 2: Keep registration API-first**
56 +
57 +Place the three existing `POST /api/v3/custom/toolkits/upsert` cURL examples under registration. Follow the response with the existing insert-only warning and a short callout linking to the dashboard Toolkits page as an alternative.
58 +
59 +- [x] **Step 3: Explain the authentication branch**
60 +
61 +Add a compact table immediately after registration:
62 +
63 +```text
64 +No auth -> initial sync happens during registration -> no connected account
65 +API key -> create and activate connected account -> sync with connected_account_id
66 +DCR OAuth -> complete user authorization -> sync with connected_account_id
67 +```
68 +
69 +- [x] **Step 4: Separate ongoing sync behavior**
70 +
71 +Keep the existing sync request and response. State directly that Composio does not continuously watch the server, later tool changes require another sync, each successful sync creates a version, and more than 500 tools causes the sync to fail without replacing the last successful version.
72 +
73 +- [x] **Step 5: Pair deletion with replacement semantics**
74 +
75 +Keep the existing delete request and response. State that the current replacement flow is delete, then register again, and that deletion revokes and removes the toolkit's existing authentication resources and connections.
76 +
77 +- [x] **Step 6: Move SDK usage after lifecycle management**
78 +
79 +Retain the Python and TypeScript examples for no-auth and authenticated sessions. Keep explicit `connected_accounts` and `connectedAccounts` selection for authenticated toolkits.
80 +
81 +- [x] **Step 7: Add the operational responsibility boundary**
82 +
83 +Add a two-column table:
84 +
85 +```text
86 +You manage -> remote server hosting and HTTPS availability; tool implementation; auth-provider behavior; deciding when to resync
87 +Composio handles -> project-scoped toolkit registration; connected-account credential storage; tool-schema sync and versions; proxied execution; session exposure
88 +```
89 +
90 +Use operational wording rather than contractual ownership language.
91 +
92 +- [x] **Step 8: Preserve technical behavior and known gaps**
93 +
94 +Keep toolkit slug behavior, Tool Router discovery, v3 versus v3.1 version selection, and every current known-gap row. Remove only duplicate prose that the lifecycle now explains more clearly.
95 +
96 +### Task 2: Verify the page
97 +
98 +**Files:**
99 +- Test: `docs/content/docs/extending-sessions/custom-mcp.mdx`
100 +
101 +**Interfaces:**
102 +- Consumes: The reflowed MDX page.
103 +- Produces: A buildable page whose rendered order matches the approved lifecycle.
104 +
105 +- [x] **Step 1: Check the diff**
106 +
107 +Run:
108 +
109 +```bash
110 +git diff --check
111 +git diff -- docs/content/docs/extending-sessions/custom-mcp.mdx
112 +```
113 +
114 +Expected: no whitespace errors and no endpoint or SDK contract drift.
115 +
116 +- [x] **Step 2: Validate links and types**
117 +
118 +Run from `docs/`:
119 +
120 +```bash
121 +bun run lint:links
122 +bun run types:check
123 +```
124 +
125 +Expected: zero link errors and successful type generation.
126 +
127 +- [x] **Step 3: Build the docs site**
128 +
129 +Run from `docs/` with Node.js 24:
130 +
131 +```bash
132 +PATH=/Users/shamsharoon/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin:$PATH bun run build
133 +```
134 +
135 +Expected: the production build completes and generates all docs pages.
136 +
137 +- [x] **Step 4: Verify localhost**
138 +
139 +Run:
140 +
141 +```bash
142 +curl --fail http://localhost:3000/docs/extending-sessions/custom-mcp
143 +```
144 +
145 +Expected: HTTP `200`. Inspect the rendered HTML for lifecycle headings, the insert-only warning, manual resync, delete consequences, responsibility boundaries, and the 500-tool limit.
146 +
147 +### Task 3: Commit and update the existing PR
148 +
149 +**Files:**
150 +- Modify: `docs/content/docs/extending-sessions/custom-mcp.mdx`
151 +- Include: `docs/superpowers/specs/2026-07-29-custom-mcp-lifecycle-doc-flow-design.md`
152 +- Include: `docs/superpowers/plans/2026-07-29-custom-mcp-lifecycle-doc-flow.md`
153 +
154 +**Interfaces:**
155 +- Consumes: Verified documentation changes.
156 +- Produces: An updated `codex/docs-custom-mcp-servers` branch and PR #3975.
157 +
158 +- [ ] **Step 1: Commit the implementation**
159 +
160 +Run:
161 +
162 +```bash
163 +git add docs/content/docs/extending-sessions/custom-mcp.mdx docs/superpowers/plans/2026-07-29-custom-mcp-lifecycle-doc-flow.md
164 +git commit -m "docs: reflow custom MCP lifecycle guide"
165 +```
166 +
167 +- [ ] **Step 2: Push the branch**
168 +
169 +Run:
170 +
171 +```bash
172 +git push origin codex/docs-custom-mcp-servers
173 +```
174 +
175 +- [ ] **Step 3: Verify the PR head**
176 +
177 +Run:
178 +
179 +```bash
180 +gh pr view 3975 --repo ComposioHQ/composio --json url,state,isDraft,headRefOid
181 +```
182 +
183 +Expected: the PR is open and its head matches the pushed local commit.
docs/superpowers/specs/2026-07-29-custom-mcp-lifecycle-doc-flow-design.md new
+87
@@ -0,0 +1,87 @@
1 +# Custom MCP lifecycle documentation flow
2 +
3 +## Goal
4 +
5 +Reorganize the Custom MCP guide into an API-first lifecycle that a developer can follow from registration through deletion. Keep the dashboard as a short alternative, preserve the existing endpoint contracts and SDK examples, and surface limitations at the step where they affect the reader.
6 +
7 +## Primary reader
8 +
9 +A developer who already operates a public remote MCP server and wants to register it with Composio, sync its tools, and use the resulting `CUSTOM_*` toolkit in a session.
10 +
11 +## Page structure
12 +
13 +1. **Introduction**
14 + - Define Custom MCP and distinguish it from in-process custom tools.
15 + - Keep the experimental warning.
16 + - Summarize the lifecycle: deploy, register, connect if required, sync, use, resync, and delete.
17 +
18 +2. **Register a Custom MCP**
19 + - State the public HTTPS prerequisite.
20 + - Present `POST /api/v3/custom/toolkits/upsert` examples for no auth, API key, and DCR OAuth.
21 + - Explain that the endpoint adds the `CUSTOM_` prefix.
22 + - Warn that `upsert` is insert-only, returns `409 Conflict` for an existing slug, and cannot update an existing toolkit.
23 + - Keep the dashboard as a short alternative callout rather than a second full workflow.
24 +
25 +3. **Complete setup for the selected authentication mode**
26 + - No auth: registration performs the initial tool sync automatically.
27 + - API key: create and activate a connected account, then sync manually.
28 + - DCR OAuth: complete user authorization for a connected account, then sync manually.
29 +
30 +4. **Sync and resync tools**
31 + - Document `POST /api/v3/custom/toolkits/sync`.
32 + - Explain when `connected_account_id` is required.
33 + - State that Composio does not continuously watch the MCP server for tool changes.
34 + - Explain that each successful sync creates a toolkit version.
35 + - State the 500-tool cap. Reject an oversized sync without partially importing it, and retain the last successful version.
36 +
37 +5. **Delete or replace a Custom MCP**
38 + - Document `DELETE /api/v3.1/custom/toolkits/{slug}`.
39 + - Explain that replacing settings requires delete, then register again.
40 + - Warn that deletion removes the toolkit and its tools, revokes its connections, and removes its auth configurations and connected accounts.
41 +
42 +6. **Authentication types**
43 + - Compare no auth, API key, and DCR OAuth in a compact table.
44 + - Keep implementation constraints, including the required API-key template and DCR authorization-code support, near the relevant mode.
45 +
46 +7. **Use Custom MCP in a session**
47 + - Show the no-auth Python and TypeScript examples.
48 + - Show the authenticated Python and TypeScript examples.
49 + - Require explicit connected-account selection for authenticated Custom MCP toolkits.
50 +
51 +8. **Responsibilities**
52 + - The customer owns the remote server, its public HTTPS availability, tool implementation, auth-provider behavior, and deciding when to resync after tool changes.
53 + - Composio handles project-scoped toolkit registration, connected-account credential storage, tool-schema syncing and versioning, proxied execution, and exposing the toolkit to sessions.
54 + - Avoid contractual language. Present this as an operational responsibility boundary.
55 +
56 +9. **Technical behavior**
57 + - Keep the existing explanation of toolkit slugs, registry versions, Tool Router discovery, and v3 versus v3.1 version selection.
58 +
59 +10. **Known gaps**
60 + - Keep a concise summary of the SDK lifecycle gap, public HTTPS requirement, lack of continuous auto-sync, explicit authenticated account selection, v3 version behavior, insert-only registration, 500-tool limit, and API-key validation limitation.
61 + - Repeat important limitations here even when they also appear in the lifecycle.
62 +
63 +## Content principles
64 +
65 +- Follow one lifecycle instead of presenting dashboard setup, API management, and SDK usage as disconnected guides.
66 +- Explain authentication differences at the point where the lifecycle branches.
67 +- Put destructive or surprising behavior immediately after the operation that triggers it.
68 +- Keep runnable cURL examples and existing response examples.
69 +- Do not document SDK lifecycle methods that do not exist.
70 +- Do not change endpoint paths, request fields, response fields, or current platform limits.
71 +
72 +## Verification
73 +
74 +- Run `bun run lint:links`.
75 +- Run `bun run types:check`.
76 +- Run the full docs production build with the repository-supported Node.js version.
77 +- Confirm the local route returns `200`.
78 +- Inspect the rendered page for the lifecycle headings, insert-only warning, manual-sync explanation, delete consequences, responsibility boundary, and 500-tool limit.
79 +- Confirm the diff only changes the Custom MCP page and this approved design record.
80 +
81 +## Non-goals
82 +
83 +- Adding or changing SDK methods.
84 +- Changing platform endpoint behavior.
85 +- Publishing the experimental endpoints into the generated public API reference.
86 +- Documenting the complete auth-config or connected-account API lifecycle.
87 +- Adding a separate dashboard tutorial.