@devries-cameron20 / composio Mirror · read-only
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

next
md 87 lines 4.85 KB
Rendered Raw
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.