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 unchanged as the cursor argument to fetch the next page. Treat cursors as opaque values: do not decode, parse, inspect, or construct them yourself. If the response omits cursor, you have reached the end of the list.

​
Supported workflows

The public MCP surface exposes read-only Plane API workflows. Tool names use the resource and action, such as workers_list or payments_get.
WorkflowTools
Benefit electionsbenefit_elections_get, benefit_elections_list
Benefit enrollmentsbenefit_enrollments_get, benefit_enrollments_list
Benefit eventsbenefit_events_get, benefit_events_list
Benefit plansbenefit_plans_get, benefit_plans_list
Benefit programsbenefit_programs_get, benefit_programs_list
Chargescharges_get, charges_list
Classificationsclassifications_get, classifications_list
Compensationscompensations_get, compensations_list
Employmentsemployments_get, employments_list
Eventsevents_get, events_list
Labor taxeslabor_taxes_get, labor_taxes_list
Leave balance transactionsleave_balance_transactions_get, leave_balance_transactions_list
Leave balancesleave_balances_get, leave_balances_list
Leave entitlementsleave_entitlements_get, leave_entitlements_list
Leave policiesleave_policies_get, leave_policies_list
Leave requestsleave_requests_get, leave_requests_list
Leavesleaves_get, leaves_list
Locationslocations_get, locations_list
Payment requestspayment_requests_get, payment_requests_list
Paymentspayments_get, payments_list
Payrollpayrolls_get, payrolls_list
Positionspositions_get, positions_list
Refundsrefunds_get, refunds_list
Reportingsreportings_get, reportings_list
Rolesroles_get, roles_list
Sandboxessandboxes_get, sandboxes_list
Time entriestime_entries_get, time_entries_list
Worker beneficiariesworker_beneficiaries_get, worker_beneficiaries_list
Worker dependentsworker_dependents_get, worker_dependents_list
Workersworkers_get, workers_list
Workforce calculationsworkforce_calculations_get
Workforce plansworkforce_plans_get, workforce_plans_list
Read-only list tools accept pagination arguments: limit, cursor, starting_after, and ending_before.
Write tools such as payment creation, payment cancellation, worker creation, and charge creation are private MCP tools and are not exposed in the public MCP surface.

​
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; when cursor is absent, there are no more results.
  • 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.