@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 183 lines 6.51 KB
Rendered Raw
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.