Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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. |