chore: update MCP server docs with latest http transport changes #179
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughDocumentation reworked to present a multi-transport MCP server model (HTTP with OAuth, HTTP with PAT, Local Stdio, SSE legacy). Endpoint references and integration commands updated to use the HTTP MCP endpoint and Changes
Sequence Diagram(s)sequenceDiagram
participant IDE as IDE/Client
participant MCP as Plane MCP (HTTP)
participant Auth as OAuth Provider
participant Local as Local Process (stdio)
participant Ext as External API (model)
rect rgba(0,128,0,0.05)
IDE->>MCP: HTTP request (OAuth) - auth code flow
MCP->>Auth: Redirect / token exchange
Auth-->>MCP: Access token
MCP->>Ext: Forward request with token
Ext-->>MCP: Model response
MCP-->>IDE: Stream/return response
end
rect rgba(0,0,128,0.03)
IDE->>MCP: HTTP request (PAT) with Authorization header
MCP->>Ext: Forward request with PAT
Ext-->>MCP: Model response
MCP-->>IDE: Stream/return response
end
rect rgba(128,0,0,0.03)
IDE->>Local: Spawn `mcp-remote` (stdio)
Local->>IDE: Establish stdio channel
IDE->>Local: Send requests over stdio
Local->>Ext: Local forwards to MCP endpoint or model
Ext-->>Local: Model response
Local-->>IDE: Return responses over stdio
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @dev-tools/mcp-server.mdx:
- Around line 184-197: The example value for PLANE_BASE_URL includes a trailing
/api while the table default does not, causing inconsistency; update the docs by
either (A) removing the /api suffix from the example value so both show plain
base URLs (e.g., use https://your-plane-instance.com) or (B) explicitly state in
the table description for PLANE_BASE_URL that self-hosted instances should
include the /api path (i.e., clarify that the default base implicitly uses /api
or that users must append /api), and then update the example or table text
accordingly; reference the PLANE_BASE_URL example string in the code block and
the PLANE_BASE_URL row in the Environment variables table to make the change.
- Around line 164-171: The docs wrongly instruct users to run "pip install uvx";
change the installation guidance for the uvx tool to explain that uvx is
distributed as part of Astral's "uv" package, not a standalone "uvx" package —
replace "pip install uvx" with installing the "uv" package (e.g., "pip install
uv" or "pipx install uv") and update the accompanying verification block so it
still shows "python --version" and "uvx --version".
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
dev-tools/mcp-server.mdx
🧰 Additional context used
🪛 LanguageTool
dev-tools/mcp-server.mdx
[grammar] ~160-~160: Ensure spelling is correct
Context: ...ct to a self-hosted Plane instance. The Stdio transport runs locally and communicates...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~270-~270: Ensure spelling is correct
Context: ...n 3.10 or later installed for the local Stdio transport. ### Getting help If you co...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Cursor Bugbot
🔇 Additional comments (5)
dev-tools/mcp-server.mdx (5)
21-30: Well-structured transport methods overview.The table provides a clear comparison of transport methods with their use cases and authentication types, making it easy for users to choose the appropriate method.
41-127: LGTM!The IDE-specific configurations are well-documented and consistently use the new HTTP endpoint. The
-yflag usage in Windsurf and Zed configurations is appropriate for those tools.
199-221: LGTM!The legacy SSE transport section appropriately marks it for backward compatibility while directing users to the recommended HTTP transport for new integrations.
223-229: LGTM!Clear activation instructions that appropriately scope the OAuth flow to relevant transport methods.
231-278: LGTM!The troubleshooting section provides comprehensive guidance covering authentication, connectivity, WSL-specific issues, and version requirements across different transport methods.
Prashant-Surya
force-pushed
the
chore/update-mcp-docs
branch
from
9e23c75 to
291b087
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @dev-tools/mcp-server.mdx:
- Around line 141-154: Replace the unsupported "headers" object under the
"mcpServers" -> "plane" entry with repeated "--header" CLI flags in the "args"
array: remove the "headers" key and update the "args" for the "plane" server
(the same block containing "command": "npx" and "args") to include
"mcp-remote@latest", the URL, then pairs of "--header" and "Header-Name: value"
(e.g., "--header", "Authorization: Bearer <YOUR_API_KEY>", "--header",
"X-Workspace-slug: <YOUR_WORKSPACE_SLUG>") so each header is passed as its own
"--header" argument to mcp-remote.
🧹 Nitpick comments (1)
dev-tools/mcp-server.mdx (1)
52-127: Minor inconsistency in-yflag usage across configurations.The
-yflag (auto-confirm) is included for Windsurf (line 105) and Zed (line 122) but omitted for Claude Desktop, Cursor, and VSCode configurations. This may be intentional based on tool-specific requirements, but consider adding a brief note explaining when-yis needed, or standardize usage across all examples for consistency.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
dev-tools/mcp-server.mdx
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-09-15T07:57:58.327Z
Learnt from: Prashant-Surya
Repo: makeplane/developer-docs PR: 143
File: api-reference/byoa/build-plane-app.mdx:629-657
Timestamp: 2025-09-15T07:57:58.327Z
Learning: In documentation files for makeplane/developer-docs, the maintainers prefer to keep code examples simple with placeholder values (like hardcoded credentials) rather than using environment variables or complex setup, as it makes the documentation more readable and easier to understand for users learning the API.
Applied to files:
dev-tools/mcp-server.mdx
🪛 LanguageTool
dev-tools/mcp-server.mdx
[grammar] ~160-~160: Ensure spelling is correct
Context: ...ct to a self-hosted Plane instance. The Stdio transport runs locally and communicates...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~270-~270: Ensure spelling is correct
Context: ...n 3.10 or later installed for the local Stdio transport. ### Getting help If you co...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Cursor Bugbot
🔇 Additional comments (6)
dev-tools/mcp-server.mdx (6)
6-30: LGTM!The introduction and transport methods table are clear and well-organized. The anchor links correctly reference their corresponding sections, and the table provides a good overview of transport options with their use cases.
158-198: LGTM!The Local Stdio transport section is well-documented with clear prerequisites, configuration, and environment variable reference. The static analysis hint about "Stdio" spelling is a false positive—this is standard terminology for standard input/output.
199-222: LGTM!The SSE legacy section appropriately marks this transport as deprecated with a clear recommendation to use HTTP with OAuth for new integrations, while maintaining backward compatibility documentation.
223-230: LGTM!The activation guidance correctly scopes OAuth prompts to applicable transports (HTTP with OAuth and SSE).
231-279: LGTM!The troubleshooting section is comprehensive, covering common issues across all transport types with appropriate solutions. The version requirements align with the prerequisites stated in each transport section.
280-282: LGTM!Appropriate closing for the documentation.
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "plane": { | ||
| "command": "npx", | ||
| "args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"], | ||
| "headers": { | ||
| "Authorization": "Bearer <YOUR_API_KEY>", | ||
| "X-Workspace-slug": "<YOUR_WORKSPACE_SLUG>" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
mcp-remote npm package headers configuration MCP server
💡 Result:
Short answer — mcp-remote supports sending custom HTTP headers to the remote MCP server via CLI flags or environment variables.
How to set headers
- Use the --header flag (repeat for multiple headers) when launching mcp-remote. Example:
args: ["mcp-remote","https://remote.mcp.server/sse","--header","Authorization: Bearer ${AUTH_TOKEN}"] (set AUTH_TOKEN in env). [1][2] - You can pass many different headers by repeating --header for each header. [1][2]
- Note: some clients (Cursor, Claude Desktop on Windows) may mangle spaces in args; workarounds are described in the docs. [1][2]
Related options
- --resource isolates OAuth sessions when running multiple instances with different configs. [2]
- Some alternative remote-MCP projects accept env vars like HTTP_HEADER_ (e.g. HTTP_HEADER_Authorization) — check that project’s README if you use a different client/server implementation. [3]
Sources
- mcp-remote (npm) usage and --header docs. [1]
- mcp-remote GitHub README (custom headers, --resource, multiple instances). [2]
- Remote-MCP project example showing HTTP_HEADER_* env convention. [3]
Replace headers field with --header CLI flags in the args array.
The headers configuration field is not supported by mcp-remote. Headers must be passed via --header flags in the command arguments. The configuration should be:
{
"mcpServers": {
"plane": {
"command": "npx",
"args": [
"mcp-remote@latest",
"https://mcp.plane.so/http/api-key/mcp",
"--header",
"Authorization: Bearer <YOUR_API_KEY>",
"--header",
"X-Workspace-slug: <YOUR_WORKSPACE_SLUG>"
]
}
}
}Repeat --header for each additional header needed.
🤖 Prompt for AI Agents
In @dev-tools/mcp-server.mdx around lines 141 - 154, Replace the unsupported
"headers" object under the "mcpServers" -> "plane" entry with repeated
"--header" CLI flags in the "args" array: remove the "headers" key and update
the "args" for the "plane" server (the same block containing "command": "npx"
and "args") to include "mcp-remote@latest", the URL, then pairs of "--header"
and "Header-Name: value" (e.g., "--header", "Authorization: Bearer
<YOUR_API_KEY>", "--header", "X-Workspace-slug: <YOUR_WORKSPACE_SLUG>") so each
header is passed as its own "--header" argument to mcp-remote.
Description
Type of Change
Note
Overhauls
dev-tools/mcp-server.mdxto document multiple transport options and modernize setup examples.HTTP with OAuth,HTTP with PAT Token,Local Stdio, and SSE (Legacy) with clear prerequisites and auth modelshttps://mcp.plane.so/http/mcpandmcp-remote@latestAuthorizationandX-Workspace-slugheadersuvx(plane-mcp-server stdio) withPLANE_API_KEY,PLANE_WORKSPACE_SLUG,PLANE_BASE_URLWritten by Cursor Bugbot for commit 291b087. This will update automatically on new commits. Configure here.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.