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.
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
Endpoint
Point your MCP client at:/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:
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.- Claude
- ChatGPT
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.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.
Record a USD 2,500 commission for [worker name] in the pay period containing August 31, 2026, with the reason "Q3 sales commission".
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 includesfeedback. 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_submitsaves the form as if the person had submitted it in Plane. It returns the form with its status,completedorin_review. Plane asks for no further confirmation, so get the person’s confirmation before you call it.forms_submit_requestasks a person to confirm the same submission, as a command request undercommand_requests:write. The form is saved only when they, or someone else who could submit it, confirm it.
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.
All available tools
All available tools
Manage offers
An MCP toolset withoffers: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
- Call
offers_createwith the recipient and proposed terms. The result is a draft, not a delivered offer. - Call
offers_getto 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_sendwith the draft ID.
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.
Revise a sent offer
A sent offer cannot be edited withoffers_update. Revision requires separate
read, void, create, and send calls.
- Call
offers_getwith the original offer ID to read its recipient and terms. - Confirm the revised terms and the reason for replacement with the user.
- Call
offers_voidwith the original ID and the reason. - Call
offers_createwith the original offer ID astemplate. - Include the recipient and only the terms that changed.
- Call
offers_getwith the new draft ID to review the replacement. - Call
offers_sendwith the new draft ID.
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_createcall without anidempotency_keycreates 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, useoffers_listandoffers_getto confirm the result before another create call. - A repeated
offers_sendcall for an already sent offer returns it without another delivery email. - Each
offers_resendcall sends another email. Repeat it only when the user wants another delivery. - A repeated
offers_updatecall with the same values leaves the draft in the same state. A repeatedoffers_extendcall with the same future expiration leaves that expiration unchanged. - After an uncertain
offers_voidresult, calloffers_getto 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_listwithtypeset to the events you follow, such asproject.created,task.opened,task.completed, andproject.completed, andcreated_afterset to thecreatedof the newest event from the last complete run, exactly as returned. It carries microseconds, and a shortened copy returns that event again. Page withcursoruntil it is empty. Events come newest first, so keep thecreatedof 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’ssubject. For a task event, it isdata.project. The project’ssubjectandworkersay which hire it concerns. Each task carriesparty:companytasks are yours to complete,workertasks wait on the hire, andplanetasks wait on Plane. - Call
projects_list, filtered by a worker or a status, to see every hire at once. Each item carriestask_countsby party and status.
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.newsfollows 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.newsfollows 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.openedorworker.created, with an optionalsubjectfilter, and an optionalprojectfilter on task types. A connection withoutworkspaces: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.
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 anAuthorization 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 provideAuthorization: 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: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:
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
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
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
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
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
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.