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. One-time earnings use compensation_earnings_create, which checks the pay period.

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. To review onboarding, first find the worker with workers_list. Then call projects_list with the worker ID and status: "all". Call projects_get with the project ID to see all tasks that you can read, including blocked and completed tasks. Without a status, projects_list returns active projects. When a company task in W-2, contractor, or EOR onboarding has a subject with object: "form", pass the subject id to forms_get. The response contains the current frame: instructions, fields, options, values, and validation errors. It also states whether your connection can submit it. To submit a frame, call forms_submit with the form ID, the unchanged continuation, and editable field values. A continuation expires after one hour. Each submission returns the next form state or the resulting task. Correct validation errors before you submit again. If the form is already complete, an authorized repeated submission returns the task without another write. Form tools require an active company member in the task’s workspace, signed in through OAuth. They do not support memberless API keys or routines. Reads require tasks:read and workers:read. Submissions also require workers:write. Neither tasks:write nor forms:* is required. Your connection still needs access to the task and its form. Worker and Plane tasks cannot be submitted through these tools. Signatures, file uploads, identity verification, and unsupported frames return a product_only reason and a task URL. Complete those steps in Plane. Form submissions cannot be proposed as change sets.

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	`compensation_earnings_create`, `compensations_create`, `compensations_get`, `compensations_list`
Contracts	`contracts_create`, `contracts_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`
Features	`features_disable`, `features_enable`, `features_list`
Forms	`forms_get`, `forms_submit`
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`, `leave_requests_update`
Leaves	`leaves_get`, `leaves_list`
Legal sources	`legal_sources_get`, `legal_sources_list`
Locations	`locations_get`, `locations_list`
Offers	`offers_create`, `offers_extend`, `offers_get`, `offers_list`, `offers_resend`, `offers_send`, `offers_update`, `offers_void`
Onboardings	`onboardings_cancel`
Pay schedule assignments	`pay_schedule_assignments_discontinue`
Pay schedules	`pay_schedules_create`, `pay_schedules_get`, `pay_schedules_list`, `pay_schedules_update`
Payment requests	`payment_requests_get`, `payment_requests_list`
Payments	`payments_get`, `payments_list`
Payroll	`payrolls_get`, `payrolls_list`
Positions	`positions_get`, `positions_list`
Projects	`projects_get`, `projects_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_create`, `time_entries_delete`, `time_entries_get`, `time_entries_list`, `time_entries_update`
Time off settings	`time_off_settings_get`
Time off upcoming	`time_off_upcoming_list`
Tasks	`tasks_get`
Vendors	`vendors_create`
Worker beneficiaries	`worker_beneficiaries_get`, `worker_beneficiaries_list`
Worker benefits	`worker_benefits_list`, `worker_benefits_history_list`
Worker contacts	`worker_contacts_create`, `worker_contacts_get`, `worker_contacts_list`, `worker_contacts_update`
Worker deductions	`worker_deductions_history_list`
Worker dependents	`worker_dependents_get`, `worker_dependents_list`
Workers	`workers_create`, `workers_get`, `workers_invite`, `workers_list`, `workers_update_basic_information`, `workers_update_counterparty`, `workers_update_legal_details`
Workforce calculations	`workforce_calculations_create`, `workforce_calculations_get`
Workforce plans	`workforce_plans_create`, `workforce_plans_get`, `workforce_plans_list`

Manage offers

An MCP toolset with offers:write can create, update, send, resend, extend, and void offers. The authenticated member or API key must also have permission to manage offers. Offers must be enabled for the workspace. Use a toolset with offers:read and offers:write for the full workflow. The default /mcp connection is read-only. The built-in Plane Agent cannot execute these writes under its default grant. Offer writes do not have _request tools for approval proposals.

Draft and send

Call offers_create with the recipient and proposed terms. The result is a draft, not a delivered offer.
Call offers_get to review the draft.
If the draft needs changes, call offers_update.
Before delivery, confirm the recipient, role, start date, compensation options, benefits, expiration, and whether onboarding starts on acceptance with the user.
Call offers_send with the draft ID.

Each compensation option can have an optional label, such as Option A or Option B, under terms.compensations. The accepted decision preserves these labels in its terms snapshot. Ask the user whether onboarding should start when the recipient accepts. Pass starts_onboarding: true to offers_create, or to offers_update on a draft, for that: acceptance then creates the worker, sets their compensation, starts their onboarding, and invites them to Plane. Without it, acceptance creates the worker and an admin starts onboarding from the worker page, or you call workers_invite. offers_get returns starts_onboarding, so check it when you review the draft. A template does not copy this choice, so pass it again when you revise an offer. If the recipient’s email matches an existing worker, acceptance links that worker. It starts their onboarding only when the worker has no onboarding, has a personal email, and has the accepted employment type, country, and start date. Otherwise the acceptance is recorded, onboarding stays null, and the offer page in Plane tells the admin why.

Sending an offer delivers an email to the recipient. Voiding an offer prevents acceptance and cannot be undone. Use a sandbox for tests of these tools.

Revise a sent offer

A sent offer cannot be edited with offers_update. Revision requires separate read, void, create, and send calls.

Call offers_get with the original offer ID to read its recipient and terms.
Confirm the revised terms and the reason for replacement with the user.
Call offers_void with the original ID and the reason.
Call offers_create with the original offer ID as template.
Include the recipient and only the terms that changed.
Call offers_get with the new draft ID to review the replacement.
Call offers_send with the new draft ID.

The template copies the proposed terms, benefits, header, footer, and metadata. The supplied non-blank terms override the copied values. The template does not copy the recipient, status, expiration, delivery, or decision. The new draft has no stored link to the original offer. For example:

Read offer ofr_123. Prepare a replacement with a November 15 start date and the same compensation options. Confirm the changes before you void the original or send the replacement.

Retries and delivery

Each offers_create call creates a new draft. After an uncertain result, use offers_list and offers_get to confirm the result before another create call.
A repeated offers_send call for an already sent offer returns it without another delivery email.
Each offers_resend call sends another email. Repeat it only when the user wants another delivery.
A repeated offers_update call with the same values leaves the draft in the same state. A repeated offers_extend call with the same future expiration leaves that expiration unchanged.
After an uncertain offers_void result, call offers_get to confirm the current status before the next step.

Follow projects and tasks

Starting an onboarding creates a project of tasks, and the event feed reports each step. A client with its own schedule, such as an agent framework or a cron job, can follow every hire from the feed without polling each project.

Call events_list with type set to the events you follow, such as project.created, task.opened, task.completed, and project.completed, and created_after set to the created of the newest event from the last complete run, exactly as returned. It carries microseconds, and a shortened copy returns that event again. Page with cursor until it is empty. Events come newest first, so keep the created of the first event on the first page, and save it only after the last page. If a run stops early, the next run starts from the old value and returns some events again, so handle each event ID once.
For each event, read the project with projects_get. For a project event, the project ID is the event’s subject. For a task event, it is data.project. The project’s subject and worker say which hire it concerns. Each task carries party: company tasks are yours to complete, worker tasks wait on the hire, and plane tasks wait on Plane.
Call projects_list, filtered by a worker or a status, to see every hire at once. Each item carries task_counts by party and status.

Every event carries actor and via, so a run can tell its own changes from a person’s. A client that holds request permission sees changeset.applied when an approved proposal is applied. The built-in Plane Agent reads the same feed under its default grant.

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

Manage offers

Draft and send

Revise a sent offer

Retries and delivery

Follow projects and tasks

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

​Manage offers

​Draft and send

​Revise a sent offer

​Retries and delivery

​Follow projects and tasks

​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

Manage offers

Draft and send

Revise a sent offer

Retries and delivery

Follow projects and tasks

Manual API key fallback

Claude Desktop config

Advanced: test the endpoint with curl

Troubleshooting

Next steps