Skip to main content
Use Plane MCP when you want an AI assistant or another MCP-compatible client to read from and act on your Plane workspace through Plane’s programmatic surface. The recommended setup is a remote MCP connection with browser-based OAuth sign-in. Use a manual API key only when your MCP client cannot complete the OAuth flow or when you are debugging the endpoint directly.

​
Prerequisites

  • A Plane account with access to the workspace you want to connect
  • An MCP client that supports remote HTTP MCP servers
  • OAuth support in your MCP client, or a Plane API key if you need the manual fallback
Keep API keys and access tokens secret. Do not paste credentials into public repositories, shared chat logs, client-side code, or other places where people outside your organization can read them.

​
Endpoint

Connect your MCP client to: 
https://api.plane.com/mcp
OAuth-aware clients use Plane’s MCP metadata to discover the authorization server and complete browser sign-in. Plane exposes that metadata at: 
https://api.plane.com/.well-known/oauth-protected-resource
Most clients only ask for the /mcp endpoint. They should discover the metadata automatically.

​
Sign in with OAuth

OAuth is the preferred way to connect Plane MCP. It lets the MCP client send a short-lived bearer access token after you approve access in the browser.
1

Add Plane as a remote MCP server

In your MCP client, add a remote HTTP MCP server or custom connector with this URL:
https://api.plane.com/mcp
2

Complete Plane sign-in

When the client starts the OAuth flow, sign in to Plane in the browser and approve access to the workspace you want the client to use.
3

Verify tools are available

Ask the client to list tools. If authentication is working, it should show Plane tools such as workers_list, payrolls_list, and payments_list.
Use a live OAuth connection only when you intend the client to work with live workspace data. Use a sandbox API key for direct endpoint tests against sandbox data.

​
Configure ChatGPT

ChatGPT uses its Settings flow for custom MCP setup. It does not use a desktop JSON config file.
1

Enable developer mode

In ChatGPT, go to Settings > Apps > Advanced settings and enable developer mode if your workspace allows it.
2

Create a connector

Go to Settings > Connectors > Create. Use a clear name such as Plane, add a short description, and set the connector URL to:
https://api.plane.com/mcp
3

Complete authentication

Complete Plane sign-in in the browser when ChatGPT starts the OAuth flow.
4

Use Plane in a chat

Start a new conversation, click +, choose More, and select the Plane connector. Ask a scoped question such as List the first 10 workers in Plane.

​
Configure Claude

If your Claude plan and client support remote MCP custom connectors with OAuth, add Plane as a custom connector with: 
https://api.plane.com/mcp
Then complete the Plane sign-in flow in Claude.

​
Manual API key fallback for Claude Desktop

Use the local Claude Desktop config file only when you need a manual API-key fallback. On macOS, Claude Desktop stores local MCP configuration in: 
~/Library/Application Support/Claude/claude_desktop_config.json
Open Claude Desktop, go to Settings > Developer, and click Edit Config. Add Plane as an HTTP MCP server: 
{
  "mcpServers": {
    "plane": {
      "type": "http",
      "url": "https://api.plane.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
If the file already contains other MCP servers, add the plane entry inside the existing mcpServers object instead of replacing the whole file. After saving the file, fully quit and restart Claude Desktop. If the connection loads, Claude should show Plane tools such as workers_list in its MCP tools list.

​
Manual API key fallback

Use an API key only when your MCP client does not support OAuth, when you are configuring a client that only supports static headers, or when you are testing the endpoint directly with curl. Create live API keys from Developers > API keys in Plane. For details, see API access. For test keys, create a sandbox first and generate a sandbox key from inside that sandbox; see Your first API call. Configure your client to send the key as a bearer token: 
Authorization: Bearer YOUR_API_KEY
For example, if your key is sk_live_..., configure the header as: 
Authorization: Bearer sk_live_...

​
Advanced: test the endpoint with curl

You can verify the endpoint without a full MCP client by sending a JSON-RPC MCP request with curl. This path uses an API key and is best for debugging. 
curl https://api.plane.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "workers_list",
        "description": "List workers. Results are paginated. If the response includes a `cursor`, pass it back as the `cursor` parameter to fetch the next page of results."
      }
    ]
  }
}

​
Call your first tool

Start with a read-only tool. This example lists up to 10 workers available to your bearer credential. 
curl https://api.plane.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "workers_list",
      "arguments": {
        "limit": 10
      }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"data\": []\n}"
      }
    ]
  }
}
The text value contains the JSON result from the underlying Plane operation. If your workspace has workers, the data array will include worker records. If the response includes a cursor, pass it back as the cursor argument to fetch the next page.

​
Supported workflows

The first public MCP surface exposes a subset of Plane’s API workflows. Tool names use the resource and action, such as workers_list or payments_create.
WorkflowTools
Workersworkers_create, workers_get, workers_invite, workers_list
Payrollpayrolls_get, payrolls_list
Paymentspayments_cancel, payments_create, payments_get, payments_list
Payment requestspayment_requests_create, payment_requests_get
Chargescharges_create, charges_get, charges_list
Compensationscompensations_get, compensations_list
Read-only list tools accept pagination arguments: limit, cursor, starting_after, and ending_before.
Some tools create, invite, cancel, or otherwise change records. Connect to a sandbox or review every write action carefully before approving client actions in live workspaces.

​
Known limitations

  • MCP does not expose every Plane API endpoint yet.
  • Tool calls use the permissions and workspace access of the bearer credential the client sends.
  • OAuth availability depends on MCP client support. Use an API key only if your client cannot complete OAuth discovery and authorization.
  • List results are paginated. Fetch the next page when a response includes a cursor.
  • MCP responses wrap Plane results in MCP content blocks, so your client may show JSON inside a text result.

​
Next steps

Authentication

Review API-key authentication details for manual fallback and direct API use.