← 返回首页
Updated the MCP Server by danciaclara · Pull Request #276 · makeplane/developer-docs · GitHub
Skip to content

Navigation Menu

Toggle navigation
Sign in
Appearance settings
Search or jump to...

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted
Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Cancel Create saved search
Appearance settings
Resetting focus

Updated the MCP Server#276

Merged
vihar merged 4 commits into
masterfrom
update-mcp-server
May 19, 2026
Merged

Updated the MCP Server#276
vihar merged 4 commits into
masterfrom
update-mcp-server

Conversation

Copy link
Copy Markdown
Collaborator

danciaclara commented May 18, 2026 •
edited by coderabbitai Bot
Loading

Description

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • Feature (non-breaking change which adds functionality)
  • Improvement (change that would cause existing functionality to not work as expected)
  • Code refactoring
  • Performance improvements
  • Documentation update

Screenshots and Media (if applicable)

Test Scenarios

References

Summary by CodeRabbit

  • Documentation
    • Restructured MCP server documentation with transport mode-based organization (HTTP OAuth, PAT token, stdio, legacy SSE)
    • Added client-specific setup instructions for multiple MCP clients including Claude Desktop, Cursor, VS Code, Windsurf, and Zed
    • Enhanced self-hosting configuration guidance with environment variables
    • Introduced identifier system explanation
    • Expanded common workflows and troubleshooting sections

Copy link
Copy Markdown

vercel Bot commented May 18, 2026 •
edited
Loading

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

Project Deployment Actions Updated (UTC)
developer-docs Ready Preview, Comment May 18, 2026 5:12pm

Copy link
Copy Markdown

coderabbitai Bot commented May 18, 2026 •
edited
Loading

📝 Walkthrough

Walkthrough

This PR substantially rewrites docs/dev-tools/mcp-server.md, reorganizing MCP server documentation around transport modes (HTTP OAuth/PAT, stdio, SSE) with authentication models, client-specific setup instructions (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Claude.ai), self-hosted deployment configuration (PLANE_BASE_URL environment variables), expanded tool reference and common workflows, and updated troubleshooting with connectivity verification steps.

Changes

Plane MCP Server Documentation Overhaul

Layer / File(s) Summary
Transport modes and authentication foundation
docs/dev-tools/mcp-server.md		 Overview introduces four transport modes with a comparison table, documents three authentication models (OAuth token validation, header-based PAT, environment-variable stdio), and adds identifier system explanation distinguishing human-readable identifiers from UUIDs.
Claude Desktop and Code setup guides
docs/dev-tools/mcp-server.md		 Provides complete configuration examples for Claude Desktop and Claude Code across CLI and settings-file flows, covering HTTP OAuth, HTTP PAT, stdio, and legacy SSE transports with concrete credential fields and command shapes.
Additional clients and self-hosted deployment
docs/dev-tools/mcp-server.md		 Expands configuration for Cursor (stdio/OAuth/PAT/SSE), Claude.ai web connectors, VS Code (Copilot MCP), Windsurf, and Zed with client-specific config paths; documents PLANE_BASE_URL and PLANE_INTERNAL_BASE_URL environment variables for self-hosted instances with connectivity verification commands.
Tool reference and common workflows
docs/dev-tools/mcp-server.md		 Describes Plane MCP tool modules and parameters (projects, work items, cycles, modules, epics, pages); provides workflow examples showing typical tool-call sequences for lookups, item creation, status updates, sprint/cycle planning, time logging, and workspace search.
Troubleshooting and operational guidance
docs/dev-tools/mcp-server.md		 Updates troubleshooting with scenario mapping for auth/permission/network errors; includes API connectivity curl examples, manual stdio debugging, and HTTP health checks; adds MIT license and source repository link.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A document reborn in structured light,
With transports clear and clients set just right,
From HTTP paths to stdio's gentle stream,
Each workflow, tool, and config shares the dream.
With self-hosted guides and troubleshooting's grace,
The MCP server finds its rightful place! 🚀

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive The title 'Updated the MCP Server' is vague and generic, failing to convey specific details about the substantial documentation rewrite despite being related to the changeset. Consider a more specific title such as 'Rewrite MCP Server documentation with transport modes and client setup instructions' to better convey the scope and nature of the changes.
✅ Passed checks (4 passed) Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
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 update-mcp-server

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 Bot reviewed May 18, 2026
View reviewed changes
Copy link
Copy Markdown

coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Actionable comments posted: 4

🤖 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`: - Around line 99-101: The fenced code block containing the example URL "https://app.plane.so/acme-corp/" is missing a language tag; update the triple-backtick fence to include a plaintext language (e.g., change ``` to ```text) so the block becomes ```text ... ``` to satisfy markdown linting and Prettier formatting checks. - Line 15: The phrase uses the incorrect single-word "usecase"; update the sentence that currently reads "The server supports four transport modes. The right one depends on your deployment and usecase." to use the two-word form "use case" so it reads "...depends on your deployment and use case." Ensure the documentation text in docs/dev-tools/mcp-server.md is replaced accordingly. - Line 308: The emphasis marker contains an extra space — update the string "Go to **Customize → Connectors ** in Claude.ai." to remove the space before the closing emphasis marker so it reads "Go to **Customize → Connectors** in Claude.ai.", ensuring the bold emphasis markers (`**`) directly enclose the text to satisfy Prettier formatting checks. - Around line 1384-1435: Several fenced code blocks in the "Common workflows" examples are missing language tags causing Prettier/markdown-lint failures; update each example code fence that contains natural-language prompts (e.g., the blocks starting with "What is work item ENG-42 about?", "Create a high-priority bug in the ENG project called \"Login times out on Safari\".", "Mark ENG-88 as done and add a comment…", the "Sprint 15" cycle example, "Log 90 minutes on ENG-42…", "Show me all high-priority bugs assigned to me…", and "Add ENG-55, ENG-56, and ENG-57 to the \"Checkout Redesign\" module.") to use a plain text language tag by changing ``` to ```text (or ```plaintext) so all seven blocks use consistent language tags and pass formatting checks.
🪄 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: 9f83720e-4708-4dcb-9695-8ec3ffe32650

📥 Commits

Reviewing files that changed from the base of the PR and between 92279d1 and 39bfb3c.

📒 Files selected for processing (1)
  • docs/dev-tools/mcp-server.md

Comment thread docs/dev-tools/mcp-server.md
## Transport modes

## Transport methods
The server supports four transport modes. The right one depends on your deployment and usecase.
Copy link
Copy Markdown

coderabbitai Bot May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix grammar: "use case" should be two words.

"usecase" should be "use case" for correct English grammar.

📝 Proposed fix
-The server supports four transport modes. The right one depends on your deployment and usecase. +The server supports four transport modes. The right one depends on your deployment and use case.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The server supports four transport modes. The right one depends on your deployment and usecase.
The server supports four transport modes. The right one depends on your deployment and use case.
🧰 Tools 🪛 LanguageTool

[grammar] ~15-~15: Ensure spelling is correct
Context: ...ight one depends on your deployment and usecase. | Transport | For ...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 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.md` at line 15, The phrase uses the incorrect single-word "usecase"; update the sentence that currently reads "The server supports four transport modes. The right one depends on your deployment and usecase." to use the two-word form "use case" so it reads "...depends on your deployment and use case." Ensure the documentation text in docs/dev-tools/mcp-server.md is replaced accordingly.

Comment thread docs/dev-tools/mcp-server.md
Comment on lines +99 to +101
```
https://app.plane.so/acme-corp/
```
Copy link
Copy Markdown

coderabbitai Bot May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add language tag to fenced code block.

Fenced code blocks should specify a language for proper syntax highlighting and to comply with markdown linting rules. For this URL example, use text or plaintext.

🔧 Proposed fix
-``` +```text https://app.plane.so/acme-corp/
</details> As per coding guidelines, Prettier formatting checks must pass in CI. <!-- suggestion_start --> <details> <summary>📝 Committable suggestion</summary> > ‼️ **IMPORTANT** > Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements. ```suggestion
🧰 Tools 🪛 markdownlint-cli2 (0.22.1)

[warning] 99-99: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 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.md` around lines 99 - 101, The fenced code block containing the example URL "https://app.plane.so/acme-corp/" is missing a language tag; update the triple-backtick fence to include a plaintext language (e.g., change ``` to ```text) so the block becomes ```text ... ``` to satisfy markdown linting and Prettier formatting checks.

Comment thread docs/dev-tools/mcp-server.md

#### HTTP with OAuth

1. Go to **Customize → Connectors ** in Claude.ai.
Copy link
Copy Markdown

coderabbitai Bot May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove extra space in emphasis markers.

There's an extra space before the closing emphasis marker: ** in Claude.ai. should be ** without the trailing space.

🔧 Proposed fix
-1. Go to **Customize → Connectors ** in Claude.ai. +1. Go to **Customize → Connectors** in Claude.ai.

As per coding guidelines, Prettier formatting checks must pass in CI.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
1. Go to **Customize → Connectors ** in Claude.ai.
1. Go to **Customize → Connectors** in Claude.ai.
🧰 Tools 🪛 markdownlint-cli2 (0.22.1)

[warning] 308-308: Spaces inside emphasis markers

(MD037, no-space-in-emphasis)

🤖 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.md` at line 308, The emphasis marker contains an extra space — update the string "Go to **Customize → Connectors ** in Claude.ai." to remove the space before the closing emphasis marker so it reads "Go to **Customize → Connectors** in Claude.ai.", ensuring the bold emphasis markers (`**`) directly enclose the text to satisfy Prettier formatting checks.

Comment thread docs/dev-tools/mcp-server.md
Comment on lines +1384 to +1435
```
What is work item ENG-42 about?
```

Model calls `retrieve_work_item_by_identifier` with `project_identifier="ENG"` and `work_item_identifier="42"`.

### Create a work item

```
Create a high-priority bug in the ENG project called "Login times out on Safari".
Description: The OAuth callback redirects to a blank page on Safari 17+.
Assign it to me.
```

Model calls `list_projects` → `retrieve_work_item_by_identifier` (or `get_me` to resolve "me") → `create_work_item`.

### Update work item state

```
Mark ENG-88 as done and add a comment: "Fixed in commit abc1234, needs QA."
```

Model resolves the UUID, calls `list_states` to find the Done state UUID, calls `update_work_item` and `create_work_item_comment`.

### Sprint planning

```
Create a cycle called "Sprint 15" in ENG starting 2025-06-02, ending 2025-06-15.
Then move all incomplete issues from Sprint 14 into it.
```

Model calls `create_cycle` then `list_cycles` to find Sprint 14's UUID, then `transfer_cycle_work_items`.

### Log time

```
Log 90 minutes on ENG-42: "Implemented retry logic for the upload endpoint."
```

### Search across the workspace

```
Show me all high-priority bugs assigned to me that are still in progress.
```

Model calls `list_work_items` with filters `priorities=["high"]`, `state_groups=["started"]`, and the current user's UUID as `assignee_ids`.

### Manage a module

```
Add ENG-55, ENG-56, and ENG-57 to the "Checkout Redesign" module.
```
Copy link
Copy Markdown

coderabbitai Bot May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add language tags to workflow example code blocks.

All fenced code blocks in the Common workflows section lack language tags. For these natural language user prompt examples, use text or plaintext to comply with markdown linting rules.

🔧 Proposed fix for all workflow examples

Apply this pattern to all 7 code blocks in lines 1384, 1392, 1402, 1410, 1419, 1425, and 1433:

-``` +```text What is work item ENG-42 about?
```diff -``` +```text Create a high-priority bug in the ENG project called "Login times out on Safari". Description: The OAuth callback redirects to a blank page on Safari 17+. Assign it to me.
Apply the same change to the remaining 5 code blocks. </details> As per coding guidelines, Prettier formatting checks must pass in CI. <!-- suggestion_start --> <details> <summary>📝 Committable suggestion</summary> > ‼️ **IMPORTANT** > Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements. ```suggestion
🧰 Tools 🪛 markdownlint-cli2 (0.22.1)

[warning] 1384-1384: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

[warning] 1392-1392: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

[warning] 1402-1402: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

[warning] 1410-1410: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

[warning] 1419-1419: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

[warning] 1425-1425: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

[warning] 1433-1433: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 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.md` around lines 1384 - 1435, Several fenced code blocks in the "Common workflows" examples are missing language tags causing Prettier/markdown-lint failures; update each example code fence that contains natural-language prompts (e.g., the blocks starting with "What is work item ENG-42 about?", "Create a high-priority bug in the ENG project called \"Login times out on Safari\".", "Mark ENG-88 as done and add a comment…", the "Sprint 15" cycle example, "Log 90 minutes on ENG-42…", "Show me all high-priority bugs assigned to me…", and "Add ENG-55, ENG-56, and ENG-57 to the \"Checkout Redesign\" module.") to use a plain text language tag by changing ``` to ```text (or ```plaintext) so all seven blocks use consistent language tags and pass formatting checks.

Hide details View details vihar merged commit f4817ee into master May 19, 2026
8 checks passed
vihar deleted the update-mcp-server branch May 19, 2026 19:17
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

coderabbitai[bot] coderabbitai[bot] left review comments

vihar vihar approved these changes

Prashant-Surya Awaiting requested review from Prashant-Surya

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

Footer

© 2026 GitHub, Inc.