Skip to main content
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:
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 an additional guardrail to help prevent unintended agent actions. An admin creates one from Developers > Toolsets, chooses the permissions used to filter tools at its endpoint, and reviews the available tools before saving. Its URL has this shape:
At that configured endpoint, Plane filters tool discovery and execution using the current toolset and the caller’s current permissions. A toolset cannot give a caller permissions they do not already have. Edits apply to existing connections; permissions are not frozen when someone signs in. A client’s cached tool list may need refreshing, but each tool call checks current access. A toolset is not a scoped credential or a permission boundary for an untrusted client. It does not bind the client’s OAuth authorization to that URL. If you need a credential-level permission boundary, use a restricted API key with explicit permissions and a client that supports API key headers. Deleting a toolset disables its endpoint. It does not revoke the client’s OAuth authorization. Do not use toolset deletion as a way to revoke that credential.

Connect your client

OAuth is the recommended way to connect. You add Plane as a connector, sign in through the browser, and Plane checks requests against your current permissions. Pick your client below.
1

Open connectors

In Claude, click Customize, then Connectors.
2

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.
3

Sign in to Plane

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

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.
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 page with limit and cursor: pass the next_cursor from the previous response as cursor, alone or with a new limit, to get the next page. The cursor carries the first call’s filters, so a filter required on the first page isn’t sent again. next_cursor is null on the last page. 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 task 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 whose task it is in party. completable says whether your connection can submit the form, and requestable says whether it can ask a person to confirm the submission instead. To answer a frame, call forms_fill with the form ID, the unchanged continuation, and editable field values. A continuation expires after one hour. Each call returns the next frame. If the values are not valid, the same frame comes back with its errors. Correct them before you fill it again. Filling writes nothing. When the last frame is valid, forms_fill returns a submission instead of a frame. It holds every answer from the first frame in values. summary shows the same answers with their field labels, then the read-only facts the last frame shows, such as an amount. consequences says what submitting does beyond the form, such as a charge. Show the summary and the consequences to the person, then send the values unchanged:
  • forms_submit saves the form as if the person had submitted it in Plane. It returns the form with its status, completed or in_review. Plane asks for no further confirmation, so get the person’s confirmation before you call it.
  • forms_submit_request asks a person to confirm the same submission, as a command request under command_requests:write. The form is saved only when they, or someone else who could submit it, confirm it.
Plane checks the values against the form again from its first frame when it saves. If they no longer complete the form, answer a field the form no longer asks for, or the form refuses the save, the submission fails as invalid with the errors. A request is checked the same way when it is confirmed, and fails then with the same code and message. If the form is already complete, a repeated forms_submit, or a request confirmed after it closed, returns it 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. Filling and submitting also require workers:update, which a Workers Write grant includes. Without it, command_requests:write lets you fill a form and ask for its submission when the person you act for could submit it themselves. Neither tasks:write nor forms:* is required. Your connection still needs access to the task and its form. Only company tasks have frames. Worker and Plane tasks cannot be submitted through these tools: forms_get returns their party without a frame. A task that names no party also has no frame; complete it in Plane. Signatures, file uploads, identity verification, and unsupported frames return a product_only reason and a task URL. Complete those steps in Plane. Some forms end in a decision, such as an EOR onboarding’s security deposit. Its field has the type decision, and the option you choose submits the form. An option’s description says what choosing it does, such as a charge. In Plane a person confirms the chosen outcome before it commits, so these forms are always asked for: forms_submit refuses them, even with workers:write, and their completable is false. Fill the form, show the person the submission’s summary and consequences, then ask for the submission with forms_submit_request. The request shows the values you sent, and a person confirms it.

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. With command_requests:write, it can ask to create, send or void an offer through offers_request, offers_send_request and offers_void_request when the person it acts for could do that themselves. That person, or another admin, confirms the request before the offer is created, sent or voided. Whoever confirms an offer that starts onboarding also needs permission to update workers. offers_create returns the whole offer. offers_send and offers_void return the offer’s id and status. Call offers_get to read the whole offer.

Draft and send

  1. Call offers_create with the recipient and proposed terms. The result is a draft, not a delivered offer.
  2. Call offers_get to review the draft.
  3. If the draft needs changes, call offers_update.
  4. Before delivery, confirm the recipient, role, start date, compensation options, benefits, expiration, and whether onboarding starts on acceptance with the user.
  5. Call offers_send with the draft ID.
To create and send an offer in one call, pass send: true to offers_create. Confirm every term with the user first, because Plane emails the recipient at once. A request through offers_request with send: true creates and sends the offer when an admin confirms it, so the admin confirms it once. 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.
  1. Call offers_get with the original offer ID to read its recipient and terms.
  2. Confirm the revised terms and the reason for replacement with the user.
  3. Call offers_void with the original ID and the reason.
  4. Call offers_create with the original offer ID as template.
  5. Include the recipient and only the terms that changed.
  6. Call offers_get with the new draft ID to review the replacement.
  7. 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 without an idempotency_key creates a new offer. Reuse the key with the same arguments to retry an uncertain result: the retry returns the offer the first call created. Without a key, 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.
  1. 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.
  2. 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.
  3. 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.

Receive events as they happen

Clients that support MCP Events, such as ChatGPT, can follow what happens in Plane instead of polling the feed. The client gives an HTTPS callback URL of at most 2,048 bytes and a signing secret, and Plane sends each piece of news to that URL. Plane offers three kinds of event, all with webhook delivery:
  • project.news follows one project: its tasks opening and completing, and the project completing or being cancelled. It takes the project’s ID. A member who can read the project can follow it.
  • offer.news follows one offer: the candidate accepting or declining it, and the offer expiring or being voided. It takes the offer’s ID. Once the offer is accepted and its onboarding starts, the same follow carries the onboarding project’s news. An admin can follow an offer.
  • Each feed type, such as task.opened or worker.created, with an optional subject filter, and an optional project filter on task types. A connection without workspaces:read, or a member who is not an admin, sees none of these.
events/list returns the kinds your connection can follow. events/subscribe starts a follow. Before the first follow on a URL, Plane sends a signed verification request with a challenge, and the callback must return the challenge. Plane applies the rules the built-in Plane Agent applies to its own follows:
  • A change your connection made through MCP is not sent to it. A change made in the app, or by someone else, is.
  • A change your connection has already read through MCP, in a tool result that showed the record after the change, is not sent either.
  • A follow ends without a delivery when you lose access to what it follows, or when the project or offer closes and you have read it closed.
Each delivery is one event, signed with Standard Webhooks headers. webhook-id and eventId name the event’s delivery to that follow, so a repeated delivery has the same ID and two follows on one URL get different IDs. X-MCP-Subscription-Id is the follow’s ID. name is the kind you subscribed to, data is the feed event as events_get returns it, and timestamp is when the change happened. A follow lasts at most 24 hours. The client renews it before refreshBefore by subscribing again with the same kind, filters, and URL. A renewal finds the same follow even after an offer’s follow has moved to the onboarding project, and events/unsubscribe with the offer’s ID ends it. A new secret replaces the old one, and both sign deliveries for 10 minutes. An active follow continues from where it is. A follow that lapsed starts again from the renewal. Plane does not replay events: cursor is always null, so to read events that happened while a follow was not active, use events_list. Plane retries a failed delivery for about two hours. A 410 response ends that follow. A workspace holds up to 100 active follows. Each follow reads through the toolset of the request that last subscribed or renewed it, and deleting that toolset ends the follow.

Manual API key fallback

Use a restricted API key when you need a credential-level permission boundary. API keys also support clients that use static headers and direct endpoint testing. Your client must support sending an Authorization header. Create a key from Developers > API keys > New secret key. Choose Access > Restricted, select the permissions it needs, and click Create secret key. Copy the secret once and store it securely; 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:

Client support

In Claude’s custom connector setup, use Request headers to provide Authorization: Bearer YOUR_API_KEY and No sign in for a key-only connection. Availability and organization controls depend on your plan; follow Claude’s current custom connector instructions. Everyone using a shared-key connector receives that key’s access, rather than their individual Plane user’s access. ChatGPT’s documented custom MCP setup offers OAuth or no authentication, not a static API-key header field. Do not put a key in its OAuth client-secret field or choose no authentication for Plane. If you need a restricted key, use a client that supports bearer headers. Check ChatGPT’s current setup options before choosing a client.

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:
Then run a read-only tool by name:
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:
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

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.
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.
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_).
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.
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.