Set up Plane MCP

This guide shows you how to connect an MCP client to your Plane workspace. You can ask questions and perform common tasks in plain English.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets an application call external tools in a consistent way. An app that connects to MCP servers is called an MCP client. Most AI assistants, such as Claude and ChatGPT, act as the MCP client here. Plane provides an MCP server that exposes a set of tools for your workspace, so your MCP client can look up your data on your behalf instead of you clicking through screens. You do not install anything. Plane’s MCP server is remote: you point your MCP client at one URL and sign in.

What is a connector?

A connector is how an MCP client registers an MCP server. Different clients name it differently. Claude calls it a connector, and ChatGPT calls it an app. Either way the setup is the same: you add Plane as a custom connector by entering its URL, the client handles sign-in, and then it discovers the tools Plane exposes.

Plane shows only the tasks available to your connection.

An accepted compensation can flow into payroll. Before you approve a compensations_create call, confirm the worker, earning type, amount, currency, unit, and effective date. Use a sandbox when testing this tool.

Prerequisites

A Plane account with admin or manager access to the workspace
An MCP client that supports remote HTTP MCP servers, such as Claude or ChatGPT
OAuth support in your client, or a Plane API key for the manual fallback

Keep API keys and access tokens secret. Do not paste credentials into public repositories, shared chat logs, client-side code, or anywhere people outside your organization can read them.

Endpoint

Point your MCP client at:

https://api.plane.com/mcp

Most clients handle the rest automatically: they discover Plane’s authorization server and prompt you to sign in with your Plane credentials. You usually only need to provide the /mcp URL. A toolset is a second URL with its own permissions. An admin creates one from Developers > Toolsets, picks what it may read and write family by family, and sees the tools that grant exposes before saving. Its URL has this shape:

https://api.plane.com/mcp/toolset_...

The toolset narrows discovery and execution to its permission grant. Use a toolset with compensations:write to expose compensations_create; the URL still requires normal Plane authentication, and a member never gets more through a toolset than their own role allows. Deleting a toolset revokes every client connected through it.

Connect your client

OAuth is the recommended way to connect. You add Plane as a connector, sign in through the browser, and the client receives a short-lived access token scoped to your Plane permissions. Pick your client below.

Claude
ChatGPT

Open connectors

In Claude, click Customize, then Connectors.

Add a custom connector

Click the + button and choose Add custom connector (not Browse connectors). When prompted, enter a name such as Plane and set the remote MCP server URL to https://api.plane.com/mcp.

Complete the Plane sign-in flow in the browser when Claude prompts you.

Use Plane in a chat

Start a new conversation, make sure the Plane connector is enabled, and try List the first 10 workers in Plane.

Claude calls workers_list and returns the result.

If your Claude Desktop build cannot complete the OAuth flow, use the manual API key fallback below.

Set this up in ChatGPT on the web (chatgpt.com). The desktop apps may not offer custom MCP setup.

Enable developer mode

Go to Settings > Apps > Advanced settings and turn on Developer mode. ChatGPT flags this as elevated risk because it allows custom, unverified connectors; it may also be restricted by your workspace admin.

Create the app

Back on Settings > Apps, click Create app. In the New App dialog, enter a name such as Plane, set Connection to Server URL, and enter https://api.plane.com/mcp. Set Authentication to OAuth.

Confirm and connect

Check I understand and want to continue, click Create, and complete the Plane sign-in flow when prompted.

Use Plane in a chat

Start a new conversation, make sure the Plane app is enabled, and try List the first 10 workers in Plane.

ChatGPT calls workers_list and returns the result.

Connect over OAuth only when you want the client to work with live workspace data. To experiment safely, use a sandbox API key with the manual fallback.

Try it

Once connected, start with prompts that read data:

List the workers we paid in May.
How much did we pay [contractor name] this year?
Show me the most recent payroll and what it totaled.
Which payments are still pending?
Pull a list of contractors hired in the last 90 days.

When connected through a compensation-enabled toolset, make the consequence and all pay details explicit:

Record a USD 2,500 commission for [worker name] in the pay period containing August 31, 2026, with the reason "Q3 sales commission".

If your connection uses a write-enabled toolset, inspect the leave request before you approve or decline it. For example: List requested leave, then approve lvr_123 with the reason "Coverage confirmed". The same applies to expense reports: review the report and its expenses before you approve or reject it. For example: Show me pending expense reports, then approve exr_123. Rejections require a reason.

What you can do today

When your client connects, Plane advertises the tools available to that connection. Each tool comes with its input schema, and your assistant calls it directly. You do not need to know tool names to ask questions. The catalog also includes feedback. Your assistant uses it to report an unmet request when no available tool can satisfy it. Underlying tool names follow {resource}_{action}, for example workers_list or payments_get. List tools accept pagination arguments: limit, cursor, starting_after, and ending_before.

All available tools

Resource	Tools
API keys	`api_keys_list`
Benefit elections	`benefit_elections_get`, `benefit_elections_list`
Benefit enrollments	`benefit_enrollments_get`, `benefit_enrollments_list`
Benefit events	`benefit_events_get`, `benefit_events_list`
Benefit plans	`benefit_plans_get`, `benefit_plans_list`
Benefit programs	`benefit_programs_get`, `benefit_programs_list`
Benefits marketplace	`benefits_marketplace_get`
Calendar events	`calendar_events_get`, `calendar_events_list`
Calendars	`calendars_get`, `calendars_list`
Charges	`charges_get`, `charges_list`
Chats	`chats_get`, `chats_list`
Classifications	`classifications_get`, `classifications_list`
Compensations	`compensations_create`, `compensations_get`, `compensations_list`
Employments	`employments_get`, `employments_list`
Events	`events_get`, `events_list`
Expense reports	`expense_reports_approve`, `expense_reports_get`, `expense_reports_list`, `expense_reports_mark_paid`, `expense_reports_reject`
Expenses	`expenses_get`, `expenses_list`
Extracts	`extracts_get`, `extracts_list`
Feedback	`feedback`
Labor rules	`labor_rules_get`, `labor_rules_list`
Labor taxes	`labor_taxes_get`, `labor_taxes_list`
Leave balance transactions	`leave_balance_transactions_get`, `leave_balance_transactions_list`
Leave balances	`leave_balances_get`, `leave_balances_list`
Leave entitlements	`leave_entitlements_get`, `leave_entitlements_list`
Leave policies	`leave_policies_get`, `leave_policies_list`
Leave requests	`leave_requests_approve`, `leave_requests_decline`, `leave_requests_get`, `leave_requests_list`
Leaves	`leaves_get`, `leaves_list`
Legal sources	`legal_sources_get`, `legal_sources_list`
Locations	`locations_get`, `locations_list`
Offers	`offers_get`, `offers_list`
Payment requests	`payment_requests_get`, `payment_requests_list`
Payments	`payments_get`, `payments_list`
Payroll	`payrolls_get`, `payrolls_list`
Positions	`positions_get`, `positions_list`
Refunds	`refunds_get`, `refunds_list`
Reportings	`reportings_get`, `reportings_list`
Roles	`roles_get`, `roles_list`
Routines	`routines_get`, `routines_list`
Sandboxes	`sandboxes_get`, `sandboxes_list`
Time entries	`time_entries_get`, `time_entries_list`
Time off settings	`time_off_settings_get`
Time off upcoming	`time_off_upcoming_list`
Worker beneficiaries	`worker_beneficiaries_get`, `worker_beneficiaries_list`
Worker benefits	`worker_benefits_list`, `worker_benefits_history_list`
Worker deductions	`worker_deductions_history_list`
Worker dependents	`worker_dependents_get`, `worker_dependents_list`
Workers	`workers_create`, `workers_get`, `workers_invite`, `workers_list`
Workforce calculations	`workforce_calculations_create`, `workforce_calculations_get`
Workforce plans	`workforce_plans_create`, `workforce_plans_get`, `workforce_plans_list`

Manual API key fallback

Use an API key only when your client cannot complete OAuth, only supports static headers, or you are testing the endpoint directly. Create live API keys from Developers > API keys in Plane; see API access. For test keys, create a sandbox first and generate a key from inside it; see Your first API call. Send the key as a bearer token:

Authorization: Bearer YOUR_API_KEY

Claude Desktop config

On macOS, Claude Desktop stores local MCP configuration at ~/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 servers, add the plane entry inside the existing mcpServers object rather than replacing the file. Fully quit and restart Claude Desktop to load the change.

Advanced: test the endpoint with curl

You can verify the endpoint without a full MCP client by sending a JSON-RPC request with an API key. List the available tools — the response advertises every tool available to your key, each with its input schema:

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": {}
  }'

Then run a read-only tool by name:

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": [],
    "structuredContent": {
      "data": []
    }
  }
}

The Plane result arrives in structuredContent as machine-readable JSON. Treat cursors as opaque: if the response includes a cursor, pass it back unchanged as the cursor argument to fetch the next page. When cursor is absent, you have reached the end of the list. To record compensation, call compensations_create directly through a toolset that grants compensations:write. This example records a one-time commission:

curl https://api.plane.com/mcp/toolset_... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "compensations_create",
      "arguments": {
        "worker": "wr_5yMmVvd6Cz7Ptx",
        "type": "commission",
        "amount": 2500.00,
        "currency": "USD",
        "starts": "2026-08-31",
        "reason": "Q3 sales commission"
      }
    }
  }'

The response is the created compensation object. Its status is accepted when it flows straight into payroll, or pending when Plane must review it first. A regular compensation also requires unit, such as year or hour.

Troubleshooting

The OAuth flow doesn't start

Confirm your client supports remote HTTP MCP servers with OAuth. Some clients only support local stdio servers or static API-key headers. If yours cannot complete OAuth, use the manual API key fallback.

Tools don't appear in my client

Restart the client after adding the connector. If tools still don’t show, confirm the OAuth flow completed and that your account has access to the workspace.

Tool calls return empty results

Empty data arrays are normal in new or empty workspaces. Confirm your credential has access to the workspace you expect. If you are using an API key, verify it is from the right workspace (sandbox keys start with sk_test_, live keys with sk_live_).

I get permission errors on some tools

MCP tools are limited by both the credential and the selected toolset. If a tool fails a permission check, confirm the toolset grants the resource permission and the underlying user or API key has access to it. Review the credential’s role in Members and roles.

I want to test without touching live data

Use a sandbox API key with the manual fallback. Create a sandbox from Developers > Sandboxes, generate a key inside it (prefix sk_test_), and configure your client with that key. See Your first API call.

Next steps

Using Plane Agent

Ask Plane Agent questions about your workspace directly inside Plane.

Your first API call

Make a direct API call without MCP, using cURL, Node.js, or Python.

Authentication

Review API-key authentication for the manual fallback.

API reference

Browse every endpoint and object the API exposes.

Getting Started

CLI

Workers

Payments

What is MCP?

What is a connector?

Prerequisites

Endpoint

Connect your client

Try it

What you can do today

Manual API key fallback

Claude Desktop config

Advanced: test the endpoint with curl

Troubleshooting

Next steps

Using Plane Agent

Your first API call

Authentication

API reference

​What is MCP?

​What is a connector?

​Prerequisites

​Endpoint

​Connect your client

​Try it

​What you can do today

​Manual API key fallback

​Claude Desktop config

​Advanced: test the endpoint with curl

​Troubleshooting

​Next steps

Using Plane Agent

Your first API call

Authentication

API reference

What is MCP?

What is a connector?

Prerequisites

Endpoint

Connect your client

Try it

What you can do today

Manual API key fallback

Claude Desktop config

Advanced: test the endpoint with curl

Troubleshooting

Next steps