Skip to content

chore: update MCP server docs with latest http transport changes #179

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danciaclara merged 1 commit into from
Jan 13, 2026
Merged

chore: update MCP server docs with latest http transport changes #179

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 154 additions & 49 deletions dev-tools/mcp-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,77 +5,86 @@ description: Use the Plane MCP server to integrate with Plane

The [Model Context Protocol](https://modelcontextprotocol.io/overview) (MCP) is a
standardized interface that enables AI models to communicate with external tools and
services. When combined with Server-Sent Events (SSE), it provides a powerful
mechanism for real-time data transfer between AI models and external systems.
services. The Plane MCP Server enables AI agents to interact with Plane's project
management capabilities through multiple transport methods.

<Note>
The Plane MCP Server is open source and available on [GitHub](https://github.com/makeplane/plane-mcp-server).

<Note>
Beta
The Plane MCP Server is currently in **Beta**. Some aspects of the API may change.
While MCP is standardized, it is also rapidly evolving. The Plane MCP Server aims to
provide a stable implementation for developers to build robust AI-powered
applications. Please send any issues to support@plane.so.
</Note>

## Prerequisites
## Transport methods

Before setting up the Plane MCP Server, ensure you have the following installed:
The Plane MCP Server supports multiple transport methods to accommodate different deployment scenarios:

### Node.js and npm
- **Node.js**: Version 20 or later (LTS recommended)
- **npm**: Comes bundled with Node.js
- **npx**: Comes bundled with npm

You can verify your installation by running:
```bash
node --version
npm --version
npx --version
```
| Transport | Best for | Authentication |
|-----------|----------|----------------|
| [HTTP with OAuth](#remote-http-with-oauth) | Cloud users, simplest setup | Browser-based OAuth |
| [HTTP with PAT Token](#remote-http-with-pat-token) | Automated workflows, CI/CD | API key in headers |
| [Local Stdio](#local-stdio-transport) | Self-hosted Plane instances | Environment variables |
| [SSE (Legacy)](#sse-transport-legacy) | Existing integrations | Browser-based OAuth |

If you don't have Node.js installed, download it from [nodejs.org](https://nodejs.org/).
## Remote HTTP with OAuth

<Note>
The MCP server uses `npx` to run the `mcp-remote` package, which handles the connection to Plane's MCP server. This is why Node.js and npx are required.
</Note>
The recommended method for connecting to Plane Cloud. Uses browser-based OAuth for authentication.

## Using the Plane MCP Server
### Prerequisites

Follow these steps to integrate with the Plane MCP Server.
- **Node.js**: Version 22 or later
- **npx**: Comes bundled with npm

### Claude.ai

- Open **Settings** from the sidebar on the web or desktop app.
- Scroll to the **Integrations** section and click **Add more**.
- Enter the Integration URL: `https://mcp.plane.so/sse`
- Click **Connect** to link your Plane workspace.
1. Open **Settings** from the sidebar on the web or desktop app.
2. Scroll to the **Integrations** section and click **Add more**.
3. Enter the Integration URL: `https://mcp.plane.so/http/mcp`
4. Click **Connect** to link your Plane workspace.

### Claude Desktop

Add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) by
updating your `claude_desktop_config.json`:
Add to your `claude_desktop_config.json`:

```json
{
"mcpServers": {
"plane": {
"command": "npx",
"args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
}
}
}
```

### Cursor

Add to your Cursor MCP configuration:

```json
{
"mcpServers": {
"plane": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.plane.so/sse"]
"args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
}
}
}
```

### VSCode

Connect Plane to [VSCode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server)
by editing your `.vscode.json` or `mcp.json` file:
Add to your `.vscode/mcp.json` file:

```json
{
"servers": {
"plane": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.plane.so/sse"]
"args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
}
}
}
Expand All @@ -93,7 +102,7 @@ by editing your `.vscode.json` or `mcp.json` file:
"mcpServers": {
"plane": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.plane.so/sse"]
"args": ["-y", "mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
}
}
}
Expand All @@ -110,61 +119,157 @@ by editing your `.vscode.json` or `mcp.json` file:
"plane": {
"source": "custom",
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.plane.so/sse"],
"args": ["-y", "mcp-remote@latest", "https://mcp.plane.so/http/mcp"],
"env": {}
}
}
}
```

## Remote HTTP with PAT Token

Use this method when you need header-based authentication, such as in automated workflows or CI/CD pipelines.

### Prerequisites

- **Node.js**: Version 22 or later
- **npx**: Comes bundled with npm
- **Plane API Key**: Generate from your Plane workspace settings

### Configuration

```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>"
}
}
}
}
```
Comment on lines +141 to +154
Copy link

@coderabbitai coderabbitai bot Jan 13, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical

🧩 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.


Replace `<YOUR_API_KEY>` with your Plane API key and `<YOUR_WORKSPACE_SLUG>` with your workspace slug.

## Local Stdio transport

Use this method to connect to a self-hosted Plane instance. The Stdio transport runs locally and communicates directly with your Plane API.

### Prerequisites

- **Python**: Version 3.10 or later
- **uvx**: Comes bundled with [uv](https://docs.astral.sh/uv/getting-started/installation/)

You can verify your installation by running:
```bash
python --version
uvx --version
```

### Configuration

```json
{
"mcpServers": {
"plane": {
"command": "uvx",
"args": ["plane-mcp-server", "stdio"],
"env": {
"PLANE_API_KEY": "<YOUR_API_KEY>",
"PLANE_WORKSPACE_SLUG": "<YOUR_WORKSPACE_SLUG>",
"PLANE_BASE_URL": "https://your-plane-instance.com/api"
}
}
}
}
```

### Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PLANE_API_KEY` | Yes | Your Plane API key |
| `PLANE_WORKSPACE_SLUG` | Yes | Your workspace slug |
| `PLANE_BASE_URL` | No | API URL for self-hosted instances (defaults to `https://api.plane.so`) |

## SSE transport (Legacy)

<Note>
The SSE transport is maintained for backward compatibility. For new integrations, we recommend using the [HTTP with OAuth](#remote-http-with-oauth) transport.
</Note>

### Prerequisites

- **Node.js**: Version 22 or later
- **npx**: Comes bundled with npm

### Configuration

```json
{
"mcpServers": {
"plane": {
"command": "npx",
"args": ["mcp-remote@latest", "https://mcp.plane.so/sse"]
}
}
}
```

## Activating the Plane MCP Server

After setup, when activating the server, you will be prompted in your browser to
connect your Plane workspace to the MCP server.
After setup, when activating the server with OAuth-based transports (HTTP with OAuth or SSE), you will be prompted in your browser to connect your Plane workspace to the MCP server.

When prompted to authorize, click **Approve**.

Next, choose the workspace you want to connect, review the permissions, and click
**Accept**.
Next, choose the workspace you want to connect, review the permissions, and click **Accept**.

## Troubleshooting

### Common Issues
### Common issues

**Authentication Errors**
**Authentication errors**

If you encounter authentication issues, clear saved auth tokens:
If you encounter authentication issues with OAuth transports, clear saved auth tokens:

```bash
rm -rf ~/.mcp-auth
```

**Connection Timeouts**
**Connection timeouts**

- Ensure you have a stable internet connection
- Check if your firewall or proxy is blocking MCP connections
- Try using the HTTP endpoint instead of SSE if available
- Verify your Plane instance is accessible

**WSL on Windows**

If you're using WSL on Windows and encountering errors, use this configuration:
If you're using WSL on Windows and encountering errors with remote transports:

```json
{
"mcpServers": {
"plane": {
"command": "wsl",
"args": ["npx", "-y", "mcp-remote", "https://mcp.plane.so/sse", "--transport sse-only"]
"args": ["npx", "-y", "mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
}
}
}
```

**Node.js Version**
**Node.js version**

Ensure you have Node.js 22 or later installed for remote transports.

**Python version**

Ensure you have a recent version of Node.js installed. MCP servers require Node.js 18 or later.
Ensure you have Python 3.10 or later installed for the local Stdio transport.

### Getting Help
### Getting help

If you continue to experience issues:

Expand All @@ -174,4 +279,4 @@ If you continue to experience issues:

## Congrats!

You have successfully connected your Plane workspace to the MCP server!
You have successfully connected your Plane workspace to the MCP server!
Loading