Skip to content

Commit f0f7066

Browse files
danciaclaradanciaclara
committed
formatting fixes
1 parent 6c68757 commit f0f7066

1 file changed

Lines changed: 37 additions & 11 deletions

File tree

‎docs/dev-tools/mcp-server.md‎

Lines changed: 37 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,12 @@ Plane hosts the MCP server for you at **`https://mcp.plane.so`**. If you run you
8383
- Python 3.10+ installed (`python --version`)
8484
- `uv` package manager (recommended). See [Installing uv](https://docs.astral.sh/uv/getting-started/installation/)
8585

86+
| Variable | Required | Description |
87+
| ---------------------- | -------- | --------------------------------------------------------------------- |
88+
| `PLANE_API_KEY` | Yes | API key from your workspace settings |
89+
| `PLANE_WORKSPACE_SLUG` | Yes | Your workspace slug |
90+
| `PLANE_BASE_URL` | No | API URL for self-hosted instances. Defaults to `https://api.plane.so` |
91+
8692
#### Get your API key (required for stdio and PAT token modes)
8793

8894
1. Open Plane and go to your workspace.
@@ -102,6 +108,11 @@ https://app.plane.so/acme-corp/
102108

103109
the slug is `acme-corp`.
104110

111+
::: info Clients that don't support custom headers
112+
**Claude Desktop** — use Stdio instead.<br>
113+
**Claude.ai** — use OAuth instead (the UI doesn't expose arbitrary headers).
114+
:::
115+
105116
### Claude Desktop
106117

107118
Config file: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
@@ -145,6 +156,10 @@ Claude Desktop doesn't support remote HTTP natively. Use `mcp-remote` — a loca
145156

146157
On first launch, `mcp-remote` opens a browser for the Plane OAuth flow.
147158

159+
::: tip No Node.js?
160+
Use the SSE fallback instead: `"url": "https://mcp.plane.so/sse", "type": "sse"`.
161+
:::
162+
148163
#### HTTP with PAT Token
149164

150165
Connects to the PAT endpoint using API key headers. No browser interaction required - suitable for shared team setups where users authenticate via their own API key.
@@ -598,6 +613,10 @@ curl -H "x-api-key: YOUR_API_KEY" \
598613
599614
A `200` response confirms the API key and URL are correct.
600615
616+
::: tip Running your own MCP server?
617+
You can skip `mcp.plane.so` entirely and deploy `plane-mcp-server` yourself — Docker Compose, Helm, OAuth app setup: [Self-host MCP Server](/dev-tools/mcp-server-self-host).
618+
:::
619+
601620
---
602621
603622
## Common workflows
@@ -665,17 +684,19 @@ Model calls `list_modules` to find the UUID, then `add_work_items_to_module` wit
665684
666685
The server propagates errors from the Plane SDK as MCP tool errors.
667686
668-
| Scenario | HTTP Status | Cause | Resolution |
669-
| --------------------------------- | ----------- | --------------------------------------- | --------------------------------------------------- |
670-
| Invalid API key | 401 | `PLANE_API_KEY` is wrong or revoked | Regenerate the token in Plane settings |
671-
| Invalid OAuth token | 401 | Token expired or revoked | Re-authorise through OAuth flow |
672-
| Missing `x-workspace-slug` header | - | Header auth missing workspace | Include `x-workspace-slug` header |
673-
| Wrong workspace slug | 404 | Slug doesn't exist | Check the exact slug in your Plane URL |
674-
| Insufficient permissions | 403 | User role too low | Check your role in the workspace/project |
675-
| Resource not found | 404 | UUID or identifier doesn't exist | Verify the ID; check if resource was deleted |
676-
| Validation error | 400 | Required field missing or invalid value | Check required fields and value constraints |
677-
| Redis unavailable | - | Token storage down | Set `REDIS_HOST`/`REDIS_PORT` or omit for in-memory |
678-
| Network error | - | Cannot reach Plane API | Verify `PLANE_BASE_URL` and connectivity |
687+
| Scenario | HTTP Status | Cause | Resolution |
688+
| ----------------------------------- | -------------------- | ----------------------------------------------- | --------------------------------------------------- |
689+
| Invalid API key | 401 | `PLANE_API_KEY` is wrong or revoked | Regenerate the token in Plane settings |
690+
| Invalid OAuth token | 401 | Token expired or revoked | Re-authorise through OAuth flow |
691+
| Missing `x-workspace-slug` header | - | Header auth missing workspace | Include `x-workspace-slug` header |
692+
| Wrong workspace slug | 404 | Slug doesn't exist | Check the exact slug in your Plane URL |
693+
| Insufficient permissions | 403 | User role too low | Check your role in the workspace/project |
694+
| Resource not found | 404 | UUID or identifier doesn't exist | Verify the ID; check if resource was deleted |
695+
| Validation error | 400 | Required field missing or invalid value | Check required fields and value constraints |
696+
| Redis unavailable | - | Token storage down | Set `REDIS_HOST`/`REDIS_PORT` or omit for in-memory |
697+
| Network error | - | Cannot reach Plane API | Verify `PLANE_BASE_URL` and connectivity |
698+
| Server not listed in Claude Desktop | Wrong transport type | Claude Desktop doesn't support `"type": "http"` | Use `npx mcp-remote@latest` or SSE transport |
699+
| Server config skipped | JSON syntax error | Config file ignored silently | Validate JSON — check for trailing commas |
679700
680701
**Verify connectivity (stdio/PAT):**
681702
@@ -711,6 +732,11 @@ rm -rf ~/.mcp-auth
711732
712733
Restart Claude Code and run `/mcp` to authenticate again.
713734
735+
## See also
736+
737+
- [Self-host MCP Server](/dev-tools/mcp-server-self-host)
738+
- [Tool Reference](/dev-tools/mcp-server-tools)
739+
714740
---
715741
716742
_Plane MCP Server is open source and licensed under MIT. Source at [github.com/makeplane/plane-mcp-server](https://github.com/makeplane/plane-mcp-server)._

0 commit comments

Comments
 (0)