docs: Developer home refresh + llms.txt redirect to MCP by johnxie · Pull Request #104 · taskade/docs

johnxie · 2026-09-17T09:44:18Z

What

docs.taskade.com is the human + agent index. The last push was 2026-07-28 (stale 7 weeks). llms.txt pointed at the preview @taskade/sdk (404s on public npm), sdk-quickstart.md led with the SDK, and the hosted MCP at /mcp was buried in a separate section. This PR redirects the developer surface to MCP-first.

Before / After

llms.txt developer surface ordering

BEFORE                                  AFTER
======                                  =====
## Developers                           ## Developers
- Developer Platform                    ### Developer surface (in order of preference)
- Authentication                        1. Hosted MCP server  (/mcp)      <- first
- REST API v1 Reference                 2. OpenAPI v2 (interactive)
- Action API v2 Reference               3. OpenAPI v1 (legacy)
- TypeScript SDK (Preview)  <- mid      4. Stdio MCP fallback (local)
- SDK Cookbook                          5. TypeScript SDK (preview)      <- last
- Webhooks                              ### Quick start (curl one-liner)
- REST API v1 live OpenAPI spec         ### Reference (v2 before v1 Legacy)
- Action API v2 live OpenAPI spec
                                        ## MCP
## MCP                                  - Hosted Taskade MCP (Beta)       <- first
- Workspace MCP           <- stdio first - Workspace MCP
- Hosted Taskade MCP (Beta) <- buried  - Workspace MCP: Advanced
- MCP Connectors                        - MCP Connectors

sdk-quickstart.md page order

BEFORE                                  AFTER
======                                  =====
1. Hint (SDK preview warning)           1. Hint: "Prefer HTTP or MCP"
2. Call the API today (TypeScript)      2. Call the API today (curl first)
3. cURL & Python                        3. cURL & Python
4. What the SDK will look like         4. Connect via MCP (AI agents)     <- new
5. Resources                            5. Generated TypeScript client      <- footnote
                                        6. Resources

QA

#	Acceptance criterion	Status
1	`llms.txt` lists hosted MCP first, OpenAPI v2 second, SDK last	Pass
2	`sdk-quickstart.md` opens with HTTP + MCP, SDK is a footnote	Pass
3	`developer-home.md` is the first developer entry in `SUMMARY.md`	Pass (already first)
4	v1 reference labeled Legacy in the sidebar	Pass
5	"Add to Cursor" / "Add to Claude" blocks match the mcp README	Pass
6	Zero code changes (docs repo only)	Pass

Files

llms.txt - new "Developer surface (in order of preference)" block, curl quick start, hosted MCP first, SDK last.
apis-living-system-development/sdk-quickstart.md - HTTP curl at top, MCP config block added, generated TypeScript client moved to a footnote.
apis-living-system-development/developer-home.md - added "Connect your AI agent (MCP)" with Add to Cursor / Add to Claude blocks and "Make your first call" curl one-liner.
SUMMARY.md - labeled REST API v1 Reference as Legacy.

Notes

v1 docs are NOT removed (Zapier/n8n recipes depend on them). Marked Legacy only.
SDK quickstart page is NOT deleted. Moved down as a footnote.
Copy is coordinated with the taskade/mcp README rewrite (mcp-readme-hosted-hosted-first) so the story matches across GitHub and docs.
Hosted MCP tier is Starter+ (mcp.access feature switch, FALSE only on free), NOT Business+ as the old README claimed.

cc @deanzaka

Made with Cursor

Reorder the developer surface to lead with the hosted MCP server (https://www.taskade.com/mcp), then OpenAPI v2, OpenAPI v1 (legacy), stdio MCP fallback, and the preview SDK last. - llms.txt: new 'Developer surface (in order of preference)' block with hosted MCP first, curl quick start, and SDK demoted to #5. - sdk-quickstart.md: open with HTTP curl + MCP config block; the generated TypeScript client moves to a footnote at the bottom. - developer-home.md: add 'Connect your AI agent (MCP)' with Add to Cursor / Add to Claude blocks and a 'Make your first call' curl one-liner, matching the taskade/mcp README story. - SUMMARY.md: label REST API v1 Reference as Legacy in the sidebar. No code changes; docs repo only. Co-authored-by: Cursor <cursoragent@cursor.com>

johnxie · 2026-09-17T09:45:07Z

Impact

@deanzaka - this reverses the developer docs order: HTTP + MCP first, SDK as a footnote. llms.txt now lists hosted MCP as the primary developer surface, not the preview SDK. docs.taskade.com was last pushed 2026-07-28 (stale 7 weeks). Agents that read docs first land on a stale page that sends them to an unpublished package. This fixes that.

Before/After

BEFORE:                              AFTER:
┌─────────────────────────┐         ┌──────────────────────────────┐
│ llms.txt -> SDK first  │         │ llms.txt -> MCP first         │
│ sdk-quickstart:        │         │ sdk-quickstart:              │
│   1. SDK (preview)     │         │   1. HTTP (curl)             │
│   2. HTTP fallback     │         │   2. MCP config block        │
│                        │         │   3. SDK (footnote)          │
│ v1 reference (no label)│         │ v1 reference (Legacy label)  │
│ No single front door   │         │ developer-home = front door  │
└─────────────────────────┘         └──────────────────────────────┘

QA

Step	Action	Expected
1	Read llms.txt diff	Hosted MCP is listed first
2	Read sdk-quickstart diff	Opens with curl, not import
3	Check SUMMARY.md	developer-home is first in dev section
4	Check v1 reference label	Says "Legacy" in sidebar
5	Verify MCP config block	Matches taskade/mcp README
6	SDK content preserved	Still exists as footnote

Consistent with taskcade#29493 Copilot feedback: stdio MCP is a local wrapper, not an offline-capable client. Co-authored-by: Cursor <cursoragent@cursor.com>

johnxie · 2026-09-17T10:08:52Z

Code review

Found 1 issue:

Stale hosted MCP tool count: new copy says "32 tools" in five places, but Phase A parity is 44 Public API v2 ops plus 4 MCP-native tools (inspect_space, read_project, list_automations, write_file) for 48 registered tools total. Update llms.txt, developer-home.md, and sdk-quickstart.md to match.

docs/llms.txt

Lines 92 to 96 in 27f123e

    
           1. Hosted MCP server: https://www.taskade.com/mcp 
        
              - Auth: Bearer `<personal-access-token>` from https://www.taskade.com/settings/api 
        
              - 32 tools: workspace read/write, app file editing (`inspect_space`, `write_file`), agent chat 
        
              - Gated on Starter+ plans (mcp.access feature switch) 
        
              - Docs: https://docs.taskade.com/developers/workspace-mcp/genesis-app-mcp

Also appears at:

docs/apis-living-system-development/developer-home.md

Lines 81 to 84 in 27f123e

    
           ## Connect your AI agent (MCP) 
        
           Point Cursor, Claude, Windsurf, or any MCP client at the hosted server with your token. This gives the agent 32 tools, including `inspect_space`, `write_file`, `read_project`, and `list_automations` that the v1 stdio wrapper does not expose. Gated on Starter+ plans (`mcp.access`).

docs/apis-living-system-development/sdk-quickstart.md

Lines 9 to 11 in 27f123e

    
           {% hint style="warning" %} 
        
           **Prefer HTTP or MCP.** Every Taskade endpoint is a plain HTTPS request and works from any language or runtime. The hosted MCP server at `https://www.taskade.com/mcp` gives AI agents (Cursor, Claude, Codex) 32 tools including app-file editing (`inspect_space`, `write_file`). The `@taskade/sdk` package below is a generated client that is **not yet on public npm** — use HTTP or MCP until it ships. 
        
           {% endhint %}

docs/apis-living-system-development/sdk-quickstart.md

Lines 125 to 128 in 27f123e

    
           ## Connect via MCP (AI agents) 
        
           For Cursor, Claude, Windsurf, VS Code, or any MCP client, point at the hosted server with your personal token. This gives the agent 32 tools, including `inspect_space`, `write_file`, `read_project`, and `list_automations` that the v1 stdio wrapper does not expose.

docs/apis-living-system-development/sdk-quickstart.md

Lines 172 to 175 in 27f123e

    
           | Resource | Description | 
        
           | --- | --- | 
        
           | [Hosted Taskade MCP (Beta)](genesis-app-mcp.md) | Orchestrate your workspace from any MCP client via `https://www.taskade.com/mcp` — 32 tools incl. app-file editing | 
        
           | [Action API v2 Reference](api-v2-reference.md) | The action-based API the SDK wraps |

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

Replace stale 32-tool copy in llms.txt, developer-home, and sdk-quickstart with 44 Phase A ops + 4 native. Matches taskcade#29494. Co-authored-by: Cursor <cursoragent@cursor.com>

fix(docs): Replace offline with stdio in developer surface copy

27f123e

Consistent with taskcade#29493 Copilot feedback: stdio MCP is a local wrapper, not an offline-capable client. Co-authored-by: Cursor <cursoragent@cursor.com>

johnxie assigned deanzaka Sep 17, 2026

fix(docs): Hosted MCP tool count is 48 after Phase A

771beaf

Replace stale 32-tool copy in llms.txt, developer-home, and sdk-quickstart with 44 Phase A ops + 4 native. Matches taskcade#29494. Co-authored-by: Cursor <cursoragent@cursor.com>

Navigation Menu

docs: Developer home refresh + llms.txt redirect to MCP - #104

docs: Developer home refresh + llms.txt redirect to MCP#104
johnxie wants to merge 3 commits into
mainfrom
docs/developer-home-mcp-first

johnxie commented Sep 17, 2026

Uh oh!

johnxie commented Sep 17, 2026

Uh oh!

johnxie commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

johnxie commented Sep 17, 2026

What

Before / After

llms.txt developer surface ordering

sdk-quickstart.md page order

QA

Files

Notes

Uh oh!

johnxie commented Sep 17, 2026

Impact

Before/After

QA

Uh oh!

johnxie commented Sep 17, 2026

Code review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants