Skip to content

Commit ead1551

Browse files
viharvihar
committed
docs: sync MCP server docs to plane-mcp-server v0.3.0
Rewrite the MCP server setup guide around the hosted OAuth endpoint with per-client setup (Claude, Claude Code, ChatGPT, Codex, Cursor, VS Code, Windsurf, Zed, Antigravity, mcp-remote), correct the access-token headers (Authorization: Bearer + x-workspace-slug), and add security, permissions, upgrading, troubleshooting and FAQ sections. Rebuild the tool reference for the 28 action-dispatch tools (183 actions, 169 retired-name aliases, 7 unmappable) from the v0.3.0 tool declarations, and update the self-hosting guide with the correct OAuth callback URIs, new environment variables (PLANE_OAUTH_ALLOWED_REDIRECT_URIS, LOG_USER_INFO, Redis/ElastiCache options) and logging notes.
1 parent 81f5fea commit ead1551

6 files changed

Lines changed: 1321 additions & 1057 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -314,7 +314,7 @@ export default extendConfig(
314314
items: [
315315
{ text: "Webhooks", link: "/dev-tools/intro-webhooks" },
316316
{ text: "Build Plane App", link: "/dev-tools/build-plane-app/overview" },
317-
{ text: "MCP Server", link: "/dev-tools/mcp-server" },
317+
{ text: "MCP server", link: "/dev-tools/mcp-server" },
318318
{ text: "Agents", link: "/dev-tools/agents/overview" },
319319
],
320320
},
@@ -1118,12 +1118,12 @@ export default extendConfig(
11181118
},
11191119

11201120
{
1121-
text: "MCP Server",
1121+
text: "MCP server",
11221122
link: "/dev-tools/mcp-server",
11231123
collapsed: false,
11241124
items: [
1125-
{ text: "Self-host MCP Server", link: "/dev-tools/mcp-server-self-host" },
1126-
{ text: "Tool Reference", link: "/dev-tools/mcp-server-tools" },
1125+
{ text: "Self-host the MCP server", link: "/dev-tools/mcp-server-self-host" },
1126+
{ text: "Tool reference", link: "/dev-tools/mcp-server-tools" },
11271127
],
11281128
},
11291129
{ text: "Plane Compose", link: "/dev-tools/plane-compose" },

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

Lines changed: 85 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,33 @@
11
---
2-
title: Self-host MCP Server
3-
description: Deploy your own Plane MCP Server with Docker Compose or Helm. Register an OAuth app, configure credentials, and point AI clients at your own instance.
2+
title: Self-host the MCP server
3+
description: Deploy the Plane MCP server with Docker Compose or Helm, register OAuth callbacks, configure storage and security, and connect AI clients.
44
keywords: plane mcp server, self-hosted mcp, plane mcp deployment, docker compose mcp, helm mcp, plane oauth mcp, mcp server setup
55
---
66

7-
# Self-host MCP Server
7+
# Self-host the MCP server
88

9-
This guide is for teams that want to run their own instance of the Plane MCP Server - either because they're on a self-hosted Plane installation that needs OAuth against their own domain, or because they want full control over the MCP infrastructure.
9+
This guide is for teams that want to run their own instance of the Plane MCP server — either because they use a
10+
self-hosted Plane installation that needs OAuth against their own domain, or because they want full control over the
11+
MCP infrastructure.
1012

11-
If you're a Plane Cloud user connecting to `mcp.plane.so`, you don't need this. Use the [MCP Server setup guide](/dev-tools/mcp-server) instead.
13+
If you're a Plane Cloud user connecting to `mcp.plane.so`, you don't need this. Use the
14+
[MCP server setup guide](/dev-tools/mcp-server) instead.
1215

1316
## Prerequisites
1417

1518
- A running **Plane instance** (self-hosted or Cloud) with workspace admin access
1619
- **Docker** and Docker Compose v2+, _or_ **Kubernetes** v1.21+ with Helm v3+
17-
- A **public URL** for the MCP server (e.g. `https://mcp.yourdomain.com`) - OAuth callbacks must be able to reach it over HTTPS
20+
- A **public URL** for the MCP server (e.g. `https://mcp.yourdomain.com`) — OAuth callbacks must reach it over HTTPS
1821

1922
---
2023

2124
## Register an OAuth app in Plane
2225

2326
The MCP server authenticates users through Plane's OAuth 2.0 system. You need to register an app to get a Client ID and Client Secret.
2427

25-
1. Go to **Workspace Settings → Integrations**:
28+
1. Go to **Workspace settings → Integrations**:
2629

27-
```
30+
```text
2831
https://<your-plane-domain>/<workspace>/settings/integrations/
2932
```
3033

@@ -36,27 +39,28 @@ The MCP server authenticates users through Plane's OAuth 2.0 system. You need to
3639
| ---------------- | ---------------------------------------------------------------- |
3740
| **App Name** | Anything descriptive (e.g. `Plane MCP Server`) |
3841
| **Setup URL** | Your MCP server's public URL (e.g. `https://mcp.yourdomain.com`) |
39-
| **Redirect URI** | All three URIs listed below, space-separated |
42+
| **Redirect URI** | Both URIs listed below, space-separated |
4043
| **Webhook URL** | Leave empty unless you need webhook events |
4144

42-
::: tip Add all three redirect URIs
43-
The server exposes callbacks on three paths to support all transports and MCP clients:
45+
::: tip Add both redirect URIs
46+
FastMCP exposes one callback under the HTTP mount and one under the SSE mount:
4447

45-
| Transport | Redirect URI |
46-
| --------------- | ------------------------------------- |
47-
| OAuth callback | `<MCP_SERVER_URL>/callback` |
48-
| HTTP with OAuth | `<MCP_SERVER_URL>/http/auth/callback` |
49-
| SSE (legacy) | `<MCP_SERVER_URL>/auth/callback` |
48+
| Transport | Redirect URI |
49+
| ---------------- | ------------------------------------- |
50+
| Streamable HTTP | `<MCP_SERVER_URL>/http/auth/callback` |
51+
| SSE (deprecated) | `<MCP_SERVER_URL>/auth/callback` |
5052

5153
For `https://mcp.yourdomain.com`, paste this into the Redirect URI field:
5254

55+
```text
56+
https://mcp.yourdomain.com/http/auth/callback https://mcp.yourdomain.com/auth/callback
5357
```
54-
https://mcp.yourdomain.com/callback https://mcp.yourdomain.com/http/auth/callback https://mcp.yourdomain.com/auth/callback
55-
```
58+
59+
A previously registered `https://mcp.yourdomain.com/callback` URI is harmless but unnecessary.
5660

5761
:::
5862

59-
4. Under **Scopes & Permissions**, select both **read** and **write** scopes.
63+
4. Under **Scopes & permissions**, select both **read** and **write** scopes.
6064

6165
5. Save. Copy the generated **Client ID** and **Client Secret** - you'll need them in the next step.
6266

@@ -146,15 +150,45 @@ The container listens on plain HTTP at `:8211`. Put it behind a reverse proxy (n
146150

147151
#### Environment variable reference
148152

149-
| Variable | Required | Description |
150-
| ------------------------------------ | -------- | ------------------------------------------------------------------------------ |
151-
| `APP_RELEASE_VERSION` | No | Image tag to deploy. Defaults to `latest`. Pin in production. |
152-
| `PLANE_BASE_URL` | No | Plane API URL. Defaults to `https://api.plane.so`. |
153-
| `PLANE_INTERNAL_BASE_URL` | No | Internal Plane URL for server-to-server calls. Falls back to `PLANE_BASE_URL`. |
154-
| `PLANE_OAUTH_PROVIDER_CLIENT_ID` | Yes | OAuth Client ID from Step 1. |
155-
| `PLANE_OAUTH_PROVIDER_CLIENT_SECRET` | Yes | OAuth Client Secret from Step 1. |
156-
| `PLANE_OAUTH_PROVIDER_BASE_URL` | Yes | Public URL of **this MCP server** - not your Plane instance. |
157-
| `MCP_PATH_PREFIX` | No | Path prefix for all routes. Use when reverse-proxying alongside other apps. |
153+
| Variable | Required | Description |
154+
| ------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
155+
| `APP_RELEASE_VERSION` | No | Image tag to deploy. Defaults to `latest`. Pin in production. |
156+
| `PLANE_BASE_URL` | No | Public Plane API URL. Defaults to `https://api.plane.so`. |
157+
| `PLANE_INTERNAL_BASE_URL` | No | Internal Plane URL for server-to-server calls. Falls back to `PLANE_BASE_URL`. |
158+
| `PLANE_OAUTH_PROVIDER_CLIENT_ID` | Yes | OAuth Client ID from Step 1. |
159+
| `PLANE_OAUTH_PROVIDER_CLIENT_SECRET` | Yes | OAuth Client Secret from Step 1. |
160+
| `PLANE_OAUTH_PROVIDER_BASE_URL` | Yes | Public URL of **this MCP server**, not your Plane instance. |
161+
| `PLANE_OAUTH_PROVIDER_ENABLE_CIMD` | No | Enables client ID metadata documents. Defaults to `false`. |
162+
| `PLANE_OAUTH_ALLOWED_REDIRECT_URIS` | No | Comma-separated extra client redirect patterns. `*` can match a port, path segment, or subdomain; keep hosts pinned. |
163+
| `MCP_PATH_PREFIX` | No | Prefix for every route. For example, `/plane` serves MCP at `/plane/http/mcp`. |
164+
| `REDIS_HOST` | No | Redis or Valkey host for persistent OAuth token storage. Without it, tokens use in-memory storage. |
165+
| `REDIS_PORT` | No | Redis or Valkey port. |
166+
| `REDIS_PASSWORD` | No | Static Redis or Valkey password. |
167+
| `REDIS_SSL` | No | Enables TLS for Redis or Valkey when set to `true`. |
168+
| `ELASTICACHE_SECRET_ARN` | No | AWS Secrets Manager ARN containing a rotating ElastiCache authentication token. |
169+
| `AWS_REGION` | No | AWS region for `ELASTICACHE_SECRET_ARN`. |
170+
| `REDIS_AUTH_TOKEN_KEY` | No | JSON key that contains the rotating token in the AWS secret. |
171+
| `LOG_USER_INFO` | No | Logs the user's display name when `true`. Defaults to `false`; the display name is PII. |
172+
173+
#### Onboard a new MCP client
174+
175+
The built-in redirect allowlist contains:
176+
177+
- `http://localhost:*`, `http://localhost:*/*`, `http://127.0.0.1:*`, and
178+
`http://127.0.0.1:*/*`
179+
- `cursor://anysphere.cursor-mcp/oauth/*` and `https://www.cursor.com/*`
180+
- `https://vscode.dev/redirect` and `https://insiders.vscode.dev/redirect`
181+
- `https://antigravity.google/oauth-callback`
182+
- `https://claude.ai/*`
183+
- `https://chatgpt.com/connector/oauth/*` and `https://chatgpt.com/connector_platform_oauth_redirect`
184+
185+
Append new client callbacks without releasing a new server version:
186+
187+
```env
188+
PLANE_OAUTH_ALLOWED_REDIRECT_URIS=https://newclient.com/cb,https://other.app/oauth/*
189+
```
190+
191+
The `*` wildcard can match any port, path segment, or subdomain. Keep the host pinned to a domain you trust.
158192

159193
#### Upgrading
160194

@@ -224,6 +258,9 @@ helm install plane-mcp plane/plane-mcp-server \
224258
| `services.redis.local_setup` | `true` | Deploy Valkey in-cluster |
225259
| `services.redis.external_redis_url` | `""` | External Valkey/Redis URL (if not using in-cluster) |
226260

261+
Environment variables that have no Helm value — for example `PLANE_OAUTH_ALLOWED_REDIRECT_URIS` or `LOG_USER_INFO` —
262+
must be set as environment variables on the MCP server deployment.
263+
227264
#### Upgrading
228265

229266
```bash
@@ -240,17 +277,25 @@ helm uninstall plane-mcp --namespace plane-mcp
240277

241278
---
242279

280+
## Logging and observability
281+
282+
The server emits structured JSON logs with the tool name, duration, status, opaque user ID, and workspace slug.
283+
284+
`LOG_USER_INFO` defaults to `false`. Setting it to `true` also logs the user's display name, which is personally
285+
identifiable information.
286+
243287
## Connect AI clients
244288

245289
Once the server is running, your available endpoints are:
246290

247-
| Endpoint | Auth | Description |
248-
| --------------------------------------------- | ---------- | ----------------------------------- |
249-
| `https://mcp.yourdomain.com/http/mcp` | OAuth | Recommended for most clients |
250-
| `https://mcp.yourdomain.com/http/api-key/mcp` | PAT header | For CI/CD, scripts, headless setups |
251-
| `https://mcp.yourdomain.com/sse` | OAuth | Legacy SSE transport (deprecated) |
291+
| Endpoint | Auth | Description |
292+
| --------------------------------------------- | --------------------------------------------------------- | -------------------------------- |
293+
| `https://mcp.yourdomain.com/http/mcp` | OAuth | Recommended for most clients |
294+
| `https://mcp.yourdomain.com/http/api-key/mcp` | `Authorization: Bearer <PAT>`, `x-workspace-slug: <slug>` | CI, scripts, and headless setups |
295+
| `https://mcp.yourdomain.com/sse` | OAuth | Deprecated HTTP+SSE transport |
252296

253-
Client configuration is identical to the [MCP Server setup guide](/dev-tools/mcp-server) - replace `https://mcp.plane.so` with your server's URL in every config snippet.
297+
Client configuration is identical to the [MCP server setup guide](/dev-tools/mcp-server). Swap
298+
`https://mcp.plane.so` for your server's host in each configuration.
254299

255300
---
256301

@@ -273,9 +318,12 @@ If Valkey is unhealthy, tokens are stored in-memory and lost on restart. Verify
273318

274319
**OAuth errors:**
275320

276-
- Confirm all three redirect URIs are registered in your Plane OAuth app: `/callback`, `/http/auth/callback`, `/auth/callback`.
321+
- Confirm both redirect URIs are registered in your Plane OAuth app: `/http/auth/callback` and `/auth/callback`. An
322+
existing `/callback` registration is harmless but unnecessary.
277323
- Check that `PLANE_OAUTH_PROVIDER_CLIENT_ID` and `PLANE_OAUTH_PROVIDER_CLIENT_SECRET` match what Plane generated.
278324
- Check that `PLANE_OAUTH_PROVIDER_BASE_URL` is the publicly reachable `https://` URL of this MCP server - not your Plane instance URL.
325+
- If the client reports `redirect_uri is not allowed`, add its exact callback or a host-pinned pattern to
326+
`PLANE_OAUTH_ALLOWED_REDIRECT_URIS`, then restart the deployment.
279327
- Clear any cached auth tokens on the client side:
280328

281329
```bash
@@ -297,5 +345,5 @@ docker compose up -d
297345

298346
---
299347

300-
→ For client configuration details, see the [MCP Server setup guide](/dev-tools/mcp-server).
301-
→ For the full list of available tools, see the [MCP Server Tool Reference](/dev-tools/mcp-server-tools).
348+
→ For client configuration details, see the [MCP server setup guide](/dev-tools/mcp-server).
349+
→ For the full list of available tools, see the [tool reference](/dev-tools/mcp-server-tools).

0 commit comments

Comments
 (0)