chore: restructure MCP Server docs#278

akhil-vamshi-konam

Description

Restructure MCP Server docs into 3 focused pages, fix incorrect client configs, and document missing env vars.

Pages:

mcp-server.md — client setup (OAuth / PAT / Stdio across 7 clients) + troubleshooting
mcp-server-tools.md — full 136-tool reference across 20 categories + example workflows
mcp-server-self-host.md — deploy your own MCP server (Docker Compose + Helm, OAuth app creation)

Type of Change

Documentation update

Summary by CodeRabbit

Documentation
- Reorganized MCP Server guides for improved navigation and accessibility
- Added comprehensive Tool Reference documenting all 136 tools across 20 categories with parameters and workflows
- Added Self-host Deployment Guide covering Docker Compose and Helm setup options
- Updated Quick Start Guide with OAuth authentication flow and client-specific configuration examples
- Streamlined troubleshooting documentation with common scenarios and debug commands

vercel

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)

developer-docs	Ready	Preview, Comment	May 26, 2026 6:01am

coderabbitai

Warning

Review limit reached

@akhil-vamshi-konam, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 51 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info ⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f6a4755e-c690-48c8-8cc3-8a4042949290

📥 Commits

Reviewing files that changed from the base of the PR and between 9581fb0 and 5fdf93a.

📒 Files selected for processing (1)

docs/dev-tools/mcp-server.md

📝 Walkthrough

Walkthrough

This PR reorganizes Plane's MCP server documentation by splitting a monolithic guide into a cohesive multi-tier structure. It updates navigation, introduces a quick-start OAuth-first flow, provides a comprehensive self-hosted deployment guide, creates a complete tool reference, and removes redundant Claude Code-specific content.

Changes

MCP Server Documentation Reorganization

Layer / File(s) Summary

Navigation Structure Update docs/.vitepress/config.mts	Sidebar entry for "MCP Server" reorganized from a single item to an items array containing "Tool Reference" and "Self-host" links, establishing the new documentation hierarchy.
Quick-Start Guide Restructuring docs/dev-tools/mcp-server.md	Main entry point rewritten to lead with OAuth onboarding (per-client setup examples, browser authentication), add explicit PAT token authentication section, update stdio configuration for multiple clients (VS Code, Zed, Claude Code), introduce mcp-remote bridge support, and condense self-hosted setup and troubleshooting guidance.
Self-Hosted Deployment Guide docs/dev-tools/mcp-server-self-host.md	New comprehensive guide covering prerequisites, OAuth application setup (redirect URIs, scopes), Docker Compose deployment with Valkey service, Helm chart installation with TLS/ingress, client connection instructions (OAuth/PAT/SSE modes with per-client examples), and troubleshooting for startup, Valkey health, OAuth errors, and token persistence.
Complete Tool Reference Documentation docs/dev-tools/mcp-server-tools.md	New reference document listing all 136 tools across 20 categories (users, workspaces, projects, work items, activities, comments, links, relations, properties, types, worklogs, states, labels, cycles, modules, epics, milestones, initiatives, intake, pages) with parameter requirements, scoping details, and example workflows demonstrating common multi-step tool sequences.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

makeplane/developer-docs#276: Parallel overhaul of docs/dev-tools/mcp-server.md restructuring OAuth/PAT/stdio authentication modes and client setup examples.

Suggested reviewers

Prashant-Surya
vihar

Poem

🐰 A rabbit hops through docs so bright,
OAuth flows now lead the way so right!
Self-host and tools in order stand,
Plane's MCP guides, freshly planned!
The sidebar grows, the paths align—
Clean structure makes each feature shine. 🌟

🚥 Pre-merge checks | ✅ 5 ✅ Passed checks (5 passed) Check name Status Explanation

Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change—restructuring MCP Server documentation into three focused pages. It is concise, clear, and directly reflects the primary objective of the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches 🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch chore-update-mcp-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (3) docs/dev-tools/mcp-server.md (1)

391-401: ⚖️ Poor tradeoff

Table rows may exceed Prettier line width limit.

The troubleshooting table contains rows that likely exceed 120 characters when the markdown is formatted on a single line. While markdown tables can be challenging to format within strict line limits, Prettier enforcement may flag these lines.

Consider testing with Prettier to confirm compliance, or consider a different layout (e.g., definition list or separate sections) if the table causes formatting issues.

docs/dev-tools/mcp-server-self-host.md (1)

116-132: ⚡ Quick win

Consider adding MCP_PATH_PREFIX as a commented example.

The configuration reference table (line 162) documents the optional MCP_PATH_PREFIX variable for reverse-proxy scenarios, but it's not shown in the variables.env template. Adding it as a commented example would help users discover this feature when needed.

📝 Suggested addition to template

 # Public URL where MCP clients reach this server
 PLANE_OAUTH_PROVIDER_BASE_URL=https://mcp.yourdomain.com
+
+# Optional: Path prefix for routes (use when reverse-proxying alongside other apps)
+# MCP_PATH_PREFIX=/mcp

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/dev-tools/mcp-server-self-host.md` around lines 116 - 132, Add a commented example for MCP_PATH_PREFIX to the variables.env template so users discover the reverse-proxy option; specifically insert a commented line like "# MCP_PATH_PREFIX=/mcp # optional: set when hosting behind a reverse proxy" near the other public URL/OAuth vars (e.g., close to PLANE_OAUTH_PROVIDER_BASE_URL) in the env code block so it appears in the template and matches the documented configuration table.

docs/dev-tools/mcp-server-tools.md (1)

17-38: ⚡ Quick win

Consider using Card components for the tool categories overview.

The current markdown table is clear and functional, but the coding guidelines recommend using <Card> components with <CardGroup> for feature showcases. While this is more of a reference index than a feature highlight, cards could provide better visual hierarchy and make the categories more scannable.

♻️ Optional enhancement with Card components

-| Category                 | Count | What you can do                                                |
-| ------------------------ | ----- | -------------------------------------------------------------- |
-| **Projects**             | 20    | Create, update, archive projects; estimates, members, features |
-| **Work Items**           | 14    | Create, search, update, archive; assignees, labels             |
+<CardGroup cols="2">
+  <Card title="Projects (20 tools)" icon="folder">
+    Create, update, archive projects; estimates, members, features
+  </Card>
+  <Card title="Work Items (14 tools)" icon="check-square">
+    Create, search, update, archive; assignees, labels
+  </Card>
+  <!-- Continue for all 20 categories -->
+</CardGroup>

As per coding guidelines, "Use component for feature cards with icon, title, and description; use for responsive grid layouts".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/dev-tools/mcp-server-tools.md` around lines 17 - 38, Replace the markdown table in the docs/dev-tools/mcp-server-tools.md overview with a CardGroup layout using the Card component for each category: create a <CardGroup cols="N"> and render individual <Card> entries for items like "Projects", "Work Items", "Cycles", etc., ensuring each Card includes an icon, title (e.g., "Projects"), and a short description (e.g., "Create, update, archive projects; estimates, members, features") following the coding guideline "Use <Card> component for feature cards with icon, title, and description"; keep the same content and ordering from the table, choose an appropriate cols value for responsiveness, and ensure accessibility and consistent styling with existing Card components.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@docs/dev-tools/mcp-server.md`: - Line 252: The documentation sentence exceeds the 120-character Prettier limit; split the long sentence into shorter sentences or a short paragraph so no line exceeds 120 characters. Edit the paragraph that starts "Runs `plane-mcp-server` locally per-client as a subprocess..." to break it into two or three lines with clear sentences (e.g., state what it does, then list use cases like air-gapped envs/local dev/self-hosted Plane, and finally mention it uses the same API key + workspace slug as the PAT reference) ensuring each resulting line is under 120 characters. - Line 61: The two long markdown lines exceed the 120-char Prettier limit; split or rephrase the sentence "Edit `~/.codeium/windsurf/mcp_config.json`. Windsurf uses `serverUrl` (not `url`) for remote HTTP servers." (and the long line at the other occurrence) into shorter sentences or insert a line break so each line is ≤120 characters, ensuring the exact tokens `~/.codeium/windsurf/mcp_config.json`, `serverUrl`, and `url` remain present and clear. --- Nitpick comments: In `@docs/dev-tools/mcp-server-self-host.md`: - Around line 116-132: Add a commented example for MCP_PATH_PREFIX to the variables.env template so users discover the reverse-proxy option; specifically insert a commented line like "# MCP_PATH_PREFIX=/mcp # optional: set when hosting behind a reverse proxy" near the other public URL/OAuth vars (e.g., close to PLANE_OAUTH_PROVIDER_BASE_URL) in the env code block so it appears in the template and matches the documented configuration table. In `@docs/dev-tools/mcp-server-tools.md`: - Around line 17-38: Replace the markdown table in the docs/dev-tools/mcp-server-tools.md overview with a CardGroup layout using the Card component for each category: create a <CardGroup cols="N"> and render individual <Card> entries for items like "Projects", "Work Items", "Cycles", etc., ensuring each Card includes an icon, title (e.g., "Projects"), and a short description (e.g., "Create, update, archive projects; estimates, members, features") following the coding guideline "Use <Card> component for feature cards with icon, title, and description"; keep the same content and ordering from the table, choose an appropriate cols value for responsiveness, and ensure accessibility and consistent styling with existing Card components.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info ⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: af2530c2-1408-45dc-ad1e-02a086bacea1

📥 Commits

Reviewing files that changed from the base of the PR and between e14f7c1 and 9581fb0.

📒 Files selected for processing (5)

docs/.vitepress/config.mts
docs/dev-tools/mcp-server-claude-code.md
docs/dev-tools/mcp-server-self-host.md
docs/dev-tools/mcp-server-tools.md
docs/dev-tools/mcp-server.md

💤 Files with no reviewable changes (1)

docs/dev-tools/mcp-server-claude-code.md

chore: MCP Server documentation

9581fb0

akhil-vamshi-konam marked this pull request as ready for review May 26, 2026 05:51

coderabbitai Bot reviewed May 26, 2026

View reviewed changes

Comment thread docs/dev-tools/mcp-server.md Outdated Show resolved Hide resolved

Comment thread docs/dev-tools/mcp-server.md Outdated Show resolved Hide resolved

chore: fix line wrapping and formatting

5fdf93a

vercel Bot deployed to Preview May 26, 2026 06:01 View deployment

akhil-vamshi-konam requested a review from Prashant-Surya May 26, 2026 06:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore: restructure MCP Server docs#278