title	Self-host MCP Server
description	Deploy your own Plane MCP Server with Docker Compose or Helm. Create an OAuth app, configure credentials, and connect AI clients to your self-hosted instance.
keywords	plane mcp server, self-hosted mcp, plane mcp deployment, docker compose mcp, helm mcp, plane oauth mcp, plane ai integration, mcp server setup

Self-host MCP Server

Run your own instance of the Plane MCP Server to connect AI clients to a self-hosted Plane installation or to maintain full control over your MCP infrastructure. This guide walks you through creating the required OAuth application in Plane, deploying the server, and connecting your AI tools.

::: info The Plane MCP Server is currently in Beta. Please send any feedback to support@plane.so. :::

Prerequisites

Before you begin, make sure you have:

A running Plane instance (self-hosted or cloud) with workspace admin access
Docker and Docker Compose v2+ (for Docker deployment) or Kubernetes v1.21+ with Helm v3+ (for Helm deployment)

Step 1: Create an OAuth application in Plane

The MCP server authenticates with Plane using OAuth 2.0. You need to register an OAuth application in your Plane workspace to obtain the credentials.

Navigate to Workspace Settings → Integrations.

https://<your-plane-app-domain>/<workspace>/settings/integrations/

Click Build your own.

Fill in the application details:

Field	Value
App Name	A name for your MCP server (e.g., `Plane MCP Server`)
Setup URL	Your MCP server's public URL (e.g., `https://mcp.yourdomain.com`)
Redirect URI	Add all three redirect URIs listed below
Webhook URL	Leave empty unless you need webhook events

::: tip Redirect URIs Add all three of the following redirect URIs to your OAuth app to ensure compatibility across all transports and MCP clients:

Transport	Redirect URI
OAuth Callback	`<MCP_SERVER_URL>/callback`
HTTP with OAuth	`<MCP_SERVER_URL>/http/auth/callback`
SSE (Legacy)	`<MCP_SERVER_URL>/auth/callback`

For example, if your MCP server is at https://mcp.yourdomain.com, add the following URIs space-separated in the Redirect URI field:

https://mcp.yourdomain.com/callback https://mcp.yourdomain.com/http/auth/callback https://mcp.yourdomain.com/auth/callback

:::

Select the read and write scopes from the Scopes & Permissions section. The MCP server requires both to function correctly.
Save and securely store the generated Client ID and Client Secret.

::: warning Never expose your Client Secret in client-side code or commit it to version control. :::

For more details on creating OAuth applications, see Create an OAuth Application.

Step 2: Deploy the MCP server

Option A: Docker Compose

Create a project directory and add the following docker-compose.yaml:

name: plane-mcp

services:
  mcp:
    image: makeplane/plane-mcp-server:${APP_RELEASE_VERSION:-latest}
    restart: always
    ports:
      - "8211:8211"
    env_file:
      - variables.env
    environment:
      REDIS_HOST: valkey
      REDIS_PORT: "6379"
    depends_on:
      valkey:
        condition: service_healthy

  valkey:
    image: valkey/valkey:8-alpine
    restart: always
    volumes:
      - valkey-data:/data
    healthcheck:
      test: ["CMD", "valkey-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  valkey-data:

Create a variables.env file with the OAuth credentials from Step 1:

# Image tag (pin to a specific version for production)
APP_RELEASE_VERSION=latest

# Plane API URL (use your self-hosted Plane API URL if applicable)
PLANE_BASE_URL=https://api.plane.so

# Internal URL for server-to-server calls (optional, for same-network setups)
# PLANE_INTERNAL_BASE_URL=

# OAuth credentials from Step 1
PLANE_OAUTH_PROVIDER_CLIENT_ID=your-client-id
PLANE_OAUTH_PROVIDER_CLIENT_SECRET=your-client-secret

# Public URL where MCP clients reach the server
PLANE_OAUTH_PROVIDER_BASE_URL=https://mcp.yourdomain.com

Start the server:
```
docker compose up -d
```
Verify the server is running:
```
docker compose logs -f mcp
```

Configuration reference

Variable	Required	Description
`APP_RELEASE_VERSION`	No	Image tag to deploy (default: `latest`)
`PLANE_BASE_URL`	No	Plane API URL (default: `https://api.plane.so`)
`PLANE_INTERNAL_BASE_URL`	No	Internal API URL for server-to-server calls
`PLANE_OAUTH_PROVIDER_CLIENT_ID`	Yes	OAuth Client ID from your Plane app
`PLANE_OAUTH_PROVIDER_CLIENT_SECRET`	Yes	OAuth Client Secret from your Plane app
`PLANE_OAUTH_PROVIDER_BASE_URL`	Yes	Public URL where MCP clients reach the server

Upgrading

docker compose pull
docker compose up -d

Option B: Helm chart

Add the Plane Helm repository:

helm repo add plane https://helm.plane.so
helm repo update

Create a values.yaml with your configuration:

ingress:
  enabled: true
  host: mcp.yourdomain.com
  ingressClass: nginx
  ssl:
    enabled: true
    issuer: cloudflare # cloudflare | digitalocean | http
    email: you@yourdomain.com

services:
  api:
    plane_base_url: "https://api.plane.so"
    plane_oauth:
      enabled: true
      client_id: "<your-oauth-client-id>"
      client_secret: "<your-oauth-client-secret>"
      provider_base_url: "https://mcp.yourdomain.com"

Install the chart:

helm install plane-mcp plane/plane-mcp-server \
  --namespace plane-mcp \
  --create-namespace \
  -f values.yaml

Helm values reference

Value	Default	Description
`dockerRegistry.default_tag`	`latest`	Image tag to deploy
`ingress.enabled`	`true`	Enable ingress
`ingress.host`	`mcp.example.com`	Public hostname
`ingress.ingressClass`	`nginx`	Ingress class name
`ingress.ssl.enabled`	`false`	Enable TLS via cert-manager
`ingress.ssl.issuer`	`cloudflare`	ACME issuer (`cloudflare`, `digitalocean`, `http`)
`services.api.replicas`	`1`	Number of MCP server replicas
`services.api.plane_base_url`	`""`	Plane API URL
`services.api.plane_oauth.enabled`	`false`	Enable OAuth endpoints
`services.api.plane_oauth.client_id`	`""`	OAuth Client ID
`services.api.plane_oauth.client_secret`	`""`	OAuth Client Secret
`services.api.plane_oauth.provider_base_url`	`""`	Public URL the server is reachable on
`services.redis.local_setup`	`true`	Deploy Valkey in-cluster
`services.redis.external_redis_url`	`""`	External Valkey/Redis URL (if not using in-cluster)

Upgrading

helm upgrade plane-mcp plane/plane-mcp-server \
  --namespace plane-mcp \
  -f values.yaml

Uninstalling

helm uninstall plane-mcp --namespace plane-mcp

Step 3: Connect your AI tools

Once the server is running, configure your AI tools to connect to it. Replace https://mcp.yourdomain.com with your actual MCP server URL.

Available endpoints

Endpoint	Auth	Description
`https://mcp.yourdomain.com/http/mcp`	OAuth	OAuth-based MCP endpoint
`https://mcp.yourdomain.com/http/api-key/mcp`	PAT header	Personal Access Token endpoint
`https://mcp.yourdomain.com/sse`	OAuth	Legacy SSE endpoint (deprecated)

Claude Desktop / Cursor / Windsurf

Use mcp-remote to connect via the HTTP OAuth endpoint:

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

Claude Code

claude mcp add --transport http plane https://mcp.yourdomain.com/http/mcp

VSCode

Add to your .vscode/mcp.json:

{
  "servers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.yourdomain.com/http/mcp"]
    }
  }
}

HTTP with PAT token

For automated workflows or CI/CD pipelines, use the PAT endpoint with a Plane API key:

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.yourdomain.com/http/api-key/mcp"],
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>",
        "X-Workspace-slug": "<YOUR_WORKSPACE_SLUG>"
      }
    }
  }
}

Troubleshooting

Server not starting?

Check the MCP server logs for errors:

docker compose logs mcp

Valkey connection issues?

Verify Valkey is healthy:

docker compose exec valkey valkey-cli ping

OAuth authentication errors?

Verify all three Redirect URIs are added to your Plane OAuth app: <MCP_SERVER_URL>/callback, <MCP_SERVER_URL>/http/auth/callback, and <MCP_SERVER_URL>/auth/callback.
Confirm PLANE_OAUTH_PROVIDER_CLIENT_ID and PLANE_OAUTH_PROVIDER_CLIENT_SECRET in your environment match the values from Plane.
Ensure PLANE_OAUTH_PROVIDER_BASE_URL is the publicly accessible URL of your MCP server.
Clear cached auth tokens on the client side:
```
rm -rf ~/.mcp-auth
```

Reset and start fresh (Docker Compose):

docker compose down -v
docker compose up -d

Getting help

If issues persist:

Verify your OAuth credentials and workspace settings
Check the Plane MCP Server repository for known issues
Contact support at support@plane.so

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Self-host MCP Server

Prerequisites

Step 1: Create an OAuth application in Plane

Step 2: Deploy the MCP server

Option A: Docker Compose

Configuration reference

Upgrading

Option B: Helm chart

Helm values reference

Upgrading

Uninstalling

Step 3: Connect your AI tools

Available endpoints

Claude Desktop / Cursor / Windsurf

Claude Code

VSCode

HTTP with PAT token

Troubleshooting

FilesExpand file tree

mcp-server-self-hosted.md

Latest commit

History

mcp-server-self-hosted.md

File metadata and controls

Self-host MCP Server

Prerequisites

Step 1: Create an OAuth application in Plane

Step 2: Deploy the MCP server

Option A: Docker Compose

Configuration reference

Upgrading

Option B: Helm chart

Helm values reference

Upgrading

Uninstalling

Step 3: Connect your AI tools

Available endpoints

Claude Desktop / Cursor / Windsurf

Claude Code

VSCode

HTTP with PAT token

Troubleshooting