mcp-server-productive
An MCP server exposing twelve generic, registry-backed tools for reading and writing Productive.io project, time, financial and admin data in a single pinned organization.
Discover — search capabilities by subject, describe any of 132 resources (filters, operators, sorts, includes, writable/required attributes, actions), list custom fields with the numeric ids values are written under, and check the connection (token owner, caller identity, allowed tiers).
Read — list any resource with server-side filters (
contains,eq,gt,lt,not_contain,not_eq, plus nested$opgroups), sorts, multi-field includes and paging, returning flattened records withtotal/nextPage; get one record by id with its relationships inlined.Read reports — query all 26
reports/*endpoints with agroupkey for aggregated rows instead of records.Write — create, update (true partial PATCH) and delete records on any permitted resource, with every attribute name and required field validated against the registry first.
Run named actions — ~150 Productive verbs (archive, restore, approve, close, finalize, copy, send, reposition…), including
bulk_*actions that require an explicit filter.Track time — log a time entry with hours auto-converted to minutes, resolving the service from the task and the person from the authenticated caller.
Stage and commit risky writes — financial, admin, delete, outward-facing and bulk operations return a signed, dry-run operation to review, which
productive_commit_operationexecutes only if unaltered, unexpired (15 min) and from the same caller.Authenticate per user (opt-in) — connect, check status and disconnect, storing each person's own AES-256-GCM-encrypted token so Productive applies their permissions and attribution; otherwise everyone shares one token's rights.
Control blast radius — four off-by-default switches gate writes, financials, admin and deletes; allow/deny lists narrow resources (including reads); passwords, sessions, subscriptions, public share links and password resets are never exposed at all.
Stay auditable and single-tenant — optional JSON-line audit log of every mutation attempt, and one instance per organization with the organization id pinned in the environment, never a tool argument.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-productive List our open projects and their statuses."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-server-productive
MCP server for the Productive.io API v2 — projects, tasks, time tracking, resource planning, financials, CRM and reports for one organization.
Productive exposes about 650 operations over 132 resources. Turning those into 650 MCP tools would swamp any client's tool list, so this server is twelve tools driven by a generated registry: the tools are generic, and the registry knows what each resource really accepts.
Tools
Discovery — productive_search_capabilities, productive_describe_resource,
productive_check_connection, productive_describe_custom_fields
Read — productive_list (filters, sorts, includes, paging, and the 26 report endpoints with
grouping), productive_get
Write — productive_create, productive_update, productive_delete, productive_run_action
(150 named verbs: archive, restore, approve, close, copy, finalize, send…),
productive_track_time, productive_commit_operation
Per-user auth (opt-in) — productive_connect, productive_status,
productive_disconnect — see Authentication
Start with productive_search_capabilities. Productive's resource names are its own — a budget is
a deal, a board column is a workflow_status, a timesheet approval lives on time_entries —
and guessing costs calls.
Related MCP server: productive-mcp-rb2
The registry
src/productive/registry.generated.ts is derived from Productive's published OpenAPI document by
scripts/generate-registry.mjs and committed, so CI never needs the network and a spec change
shows up as a reviewable diff. For every resource it records the filter fields, sort keys, report
group keys, includable relationships, the writable attributes for create and update with the
required ones marked, and each named action.
That is what lets twelve tools stay honest. productive_describe_resource hands back the exact
contract for one resource, and every argument is checked against it before a request goes out.
Regenerate with npm run registry:generate (add a path argument to use a local copy of the spec).
The generator fails the build if a hand-written classification — a risk tier, an
outward-facing flag, a blocked operation — no longer matches any path in the spec, so a rename
upstream cannot silently drop a guard.
What the API does, as measured
Everything here was verified against a live organization, because the spec and the API disagree in places that matter.
Time is minutes. Money is minor units. A time entry of 2 is two minutes. Both come back
that way too.
Unknown filters, sorts and includes fail loudly. HTTP 400 with unsupported_filter,
sort_param_unsupported, unsupported_include. So validating those here is a better error, not a
safety net.
Unknown write attributes fail silently. PATCH with a misspelled attribute returns HTTP 200
and changes nothing — indistinguishable from success. This server therefore refuses an attribute
the resource does not declare, rather than reporting a write that did not happen. It is the single
most useful thing the registry does.
There are exactly six filter operators, on every field: contains, eq, gt, lt,
not_contain, not_eq. The spec lists four per field and omits gt/lt, which do work; gte,
lte, in, not_in, starts_with, ends_with, blank and present are all refused with
unsupported_filter_operation. There is no inclusive comparison, so an inclusive range needs
the resource's own after/before or <field>_after/<field>_before filter fields.
page[size] caps at 200 and clamps silently. Asking for 500 returns 200 with no error. Results
carry total and nextPage so a page is not mistaken for the whole answer.
PATCH is genuinely partial. Omitted attributes keep their values; there is no need to resend a whole record.
data.type is not checked. Patching a task with type: "projects" succeeds and applies the
change. This server sends the correct type anyway.
A 403 saying the organization id "has to be provided" may mean it was wrong, not missing. The
same no_organization_id code covers a missing header and an organization the token cannot reach.
A missing feature answers 404, not 403. /boards 404s on an organization without it, which
reads like a broken path.
Deletes may be restorable. A deleted task appears in deleted_items with item_type and
item_id and can be restored through that resource's restore action. Verified for tasks only —
do not assume it holds for every type.
GET /users is the only caller-scoped endpoint. It returns exactly one record — you — and is
how this server identifies a token's owner. There is no /users/me; that path 404s. Beware
/organization_memberships: it is not scoped to the pinned organization, but lists the caller's
memberships across every organization they belong to, so its row count is not a headcount.
No rate-limit headers. Only x-request-id, which errors from this server quote. Back off on
429 rather than probing for the limit.
Permissions
Four switches, all off by default. A read-only server is the useful, safe default.
Switch | Covers |
| Master switch. Nothing is mutated without it. |
| Money, pricing, payroll, documents a customer receives: invoices, line items, payments, bills, expenses, purchase orders, proposals, contracts, prices, rate cards, salaries, overheads, tax rates, bank accounts, subsidiaries. |
| Access and organization-wide configuration: people, memberships, permission sets, teams, invitations, custom fields, webhooks, integrations, approval and time-tracking policies. |
| Deletes, on top of the tier gate. |
One master switch is not enough for Productive: the same API moves a task, issues an invoice and grants a permission set, and those are three different decisions. A server trusted to run project work should not thereby be able to send an invoice.
PRODUCTIVE_ALLOWED_RESOURCES / PRODUCTIVE_DENIED_RESOURCES narrow an instance further, and
apply to reads as well — an instance scoped to time tracking should not read salaries either.
Never exposed at all, regardless of switches: passwords, sessions,
organization_subscriptions, the unauthenticated public/* share links, and
PATCH /users/{id}/update_password. These are absent from the registry rather than gated, so no
policy bug can re-open them.
Two-step writes
Ordinary project work — a task, a time entry, a booking, a comment — is written in one call. Requiring a handshake around every time entry would make the server unusable for the thing people do most.
Everything with a wider blast radius is staged: the tool returns the exact request plus an
HMAC-SHA256 signature and sends nothing, and productive_commit_operation runs it only if the
operation comes back unaltered, within 15 minutes, from the same caller that prepared it. At commit
the HTTP method and path are derived again from the registry for the operation's resource and verb
(the path may differ from the template only by a single, safe id), and every policy check runs
again. The signing key is PRODUCTIVE_PREPARE_SECRET; when unset, a random key is generated at
start-up, so staged operations do not survive a restart and are not valid across replicas. That covers the financial and admin tiers, every delete, anything that leaves the
organization, and every bulk_* action — those act on all records a filter matches, so they also
refuse to run without an explicit filter.
Six operations are flagged outward because they reach somebody outside the organization the
moment they run: invoices.send, invoices.send_einvoice, people.invite, people.resend,
organizations.resend_code, and creating an invitation.
Authentication
Two modes. PRODUCTIVE_ORGANIZATION_ID is required in both, and is never a tool argument.
Per-user tokens (recommended)
Each person links their own Productive token, so Productive applies their permissions and records their name on what they do.
This matters more on Productive than on most systems. Productive attributes work to people: a time
entry belongs to a person_id, and every change is stamped with the token's owner in the activity
log — which is the record a client invoice gets defended with. On one shared token, that log says
the service account did everything.
PRODUCTIVE_PER_USER_AUTH=true
PRODUCTIVE_TRUST_FORWARDED_USER=true
PRODUCTIVE_ENCRYPTION_KEY=<min 16 chars>
PRODUCTIVE_STORE_PATH=/data/store.json
PRODUCTIVE_PUBLIC_BASE_URL=https://productive.example.com
# PRODUCTIVE_API_TOKEN deliberately unsetThe flow:
The caller runs
productive_connectand gets a single-use link, valid 10 minutes, bound to their identity.They open it and paste a token they created in Productive under Settings → API integrations. The token goes from their browser straight to the server, so it never enters the conversation transcript — a Productive token is bearer-equivalent to their whole account, and, as measured below, commonly reaches more than one organization.
Before storing it, the server calls
GET /userswith that token and this organization's id. One call proves three things: the token is valid, it can reach this organization, and who it belongs to. The page then confirms which account was linked.Tokens are encrypted at rest with AES-256-GCM, one row per verified identity.
Sharp edges:
Identity comes only from the gateway.
X-MCP-Useris read only whenPRODUCTIVE_TRUST_FORWARDED_USER=true, never from anything the MCP client controls. Enable it only behind a gateway that sets the header from a validated token and strips a client-supplied copy — otherwise a caller can name any identity and act as them. The HTTP transport refuses to start with this on unlessMCP_HTTP_TOKENis set too.No fallback. An un-enrolled caller gets
NOT_CONNECTED, never the shared token, even ifPRODUCTIVE_API_TOKENhappens to be set. A fallback would hand them borrowed rights, which is the failure this mode exists to remove./productive/enrollmust be reachable by the user's browser, bypassing the MCP gateway — a browser cannot carry the gateway's bearer token. Route/productive/*onPRODUCTIVE_PUBLIC_BASE_URLstraight to the container. Its security is the single-use, identity-bound state token.Persist
PRODUCTIVE_STORE_PATHon a volume, and keepPRODUCTIVE_ENCRYPTION_KEYstable — change it and every stored token becomes undecryptable.If a token's own Productive email differs from the caller's directory address, that is reported loudly on the page and in
productive_status, and connected anyway. SetPRODUCTIVE_REQUIRE_EMAIL_MATCH=trueto refuse instead. It is off by default because whoever pastes another person's token already holds it, so refusing buys little security, while a Productive account under a different address is entirely plausible.Per-user auth separates permissions and attribution, not organizations. The organization pin still applies to everyone.
Shared token
Set PRODUCTIVE_API_TOKEN to one token. Simple, and right for stdio or a single operator — but
every caller then acts as that token's owner, with their permissions, and Productive's activity
log credits every change to them.
PRODUCTIVE_TRUST_FORWARDED_USER still helps here: person-shaped writes (a time entry, a booking)
default to the resolved caller rather than the token's owner, and the server refuses to guess when
the address matches nobody or more than one person. productive_check_connection names the token's
owner either way, so the attribution is never a surprise.
Multi-organization
One instance serves exactly one organization. X-Organization-Id comes from the environment and is
never a tool argument, so no code path — including the generic tools — can reach another tenant.
Run a second instance for a second organization; the image is the same.
This is not theoretical. A single token routinely reaches several organizations: on the account this
was developed against, GET /organizations returned three, and switching only the header moved
between them (the other two answered 403 subscription_expired, not "not found"). The header is the
whole boundary, which is why it is pinned rather than passed in — and why an enrolled per-user token
is verified against this organization before it is stored.
Configuration
See .env.example. The two required variables are PRODUCTIVE_API_TOKEN (Settings → API
integrations in Productive; it inherits the creating user's permissions) and
PRODUCTIVE_ORGANIZATION_ID (the numeric id in your Productive URL).
Set PRODUCTIVE_AUDIT_LOG to append one JSON line per mutation attempt, including the ones policy
refused. Request bodies are deliberately not recorded: they carry salaries, rates and personal
data, and an audit trail that must be guarded as closely as the source system tends not to get
read.
Run
npm install
npm run dev # stdio
npm run dev:http # streamable HTTP on :3000/mcp (stateless), /healthz open
npm test
npm run smoke:live # reads a real organization; stages one write, commits nothingDocker images: ghcr.io/borgels/mcp-server-productive (published on push to main).
Licence
Apache-2.0.
Available Tools
12 toolsproductive_check_connectionCheck connectionARead-only
Verify the token and organization and report what this deployment may do. Also names the person the token belongs to — every change Productive records is credited to them, whoever asked — and the caller identity, when a gateway forwards one.
Inputs: no named parameters.
productive_commit_operationCommit a staged operationA
Execute a write that a prepare step staged. Pass the operation object back exactly as it was returned: it is hashed, and an altered operation is refused rather than run. Show the change to the person who asked for it before committing.
Inputs: operation (required).
productive_createCreate a recordA
Create a record on any writable resource. Required attributes are checked first, and so is every attribute name. On a financial or administrative resource this returns a staged operation to review rather than creating anything — pass it to productive_commit_operation to go through with it.
Inputs: resource (required), attributes, relationships.
productive_deleteDelete a recordADestructive
Delete a record. Needs its own switch beyond ordinary writes, and always returns a staged operation first. Many Productive types are meant to be archived rather than deleted — check productive_describe_resource for an archive action before reaching for this.
Inputs: id (required), resource (required).
productive_describe_custom_fieldsDescribe custom fieldsARead-only
List the organization's custom fields with the id each value is written under, the object it applies to, and its options. Custom-field values are keyed by numeric id, not by display name — a name used as a key is accepted with 200 and stored nowhere.
Inputs: appliesTo.
productive_describe_resourceDescribe a resourceARead-only
The exact contract for one resource, derived from Productive's own OpenAPI document: every filter field, the operators any field accepts, sort keys, report group keys, includable relationships, the writable attributes for create and update with the required ones marked, and any named actions. Read this before writing — it is the difference between a write that lands and a 200 that changed nothing.
Inputs: resource (required).
productive_getGet one recordARead-only
Read one record by id, optionally pulling related records in the same call rather than following relationship stubs one at a time.
Inputs: id (required), resource (required), raw, include.
productive_listList recordsARead-only
List any Productive resource with server-side filtering, sorting, includes and paging. Also how the 26 report endpoints are read: use resource "reports/time_reports" (and the rest) with group to get aggregated rows instead of records. Results are flattened out of JSON:API — attributes hoisted, included records inlined into their relationship — with total and nextPage so a page is never mistaken for the whole answer.
Inputs: resource (required), raw, page, sort, +3 more.
productive_run_actionRun a named actionA
Run one of Productive's named verbs: archive, restore, close, open, approve, reject, copy, finalize, send, reposition and the rest. Actions named bulk_* act on every record the filter matches rather than one, and refuse to run without an explicit filter. productive_describe_resource lists the actions a resource has.
Inputs: action (required), resource (required), id, filters, +1 more.
productive_search_capabilitiesSearch capabilitiesARead-only
Find the right resource, tool or guide for a subject. Start here: Productive names its resources its own way (a budget is a deal, a person is a person, a board column is a workflow_status), and guessing wastes calls. Returns matching tools, workflow guides, and resources with the operations each supports.
Inputs: query (required), limit.
productive_track_timeTrack timeA
Log a time entry without looking up what Productive insists on. Time is stored in MINUTES — pass hours and it converts. The service (the budget line the work bills to, not the task) is resolved from the task when not given, and the person is resolved from the authenticated caller, so time lands on the right person even though the server holds one shared token.
Inputs: date (required), note, hours, taskId, +4 more.
productive_updateUpdate a recordA
Update a record. PATCH semantics, verified live: attributes you omit keep their values, so there is no need to resend the whole record. On a financial or administrative resource this returns a staged operation instead of writing.
Inputs: id (required), resource (required), attributes, relationships.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct operation: reading one record, listing, creating, updating, deleting, running a named action, staging/committing writes, tracking time, or performing a meta/introspection task. Even the closer pairs like get/list and describe_resource/describe_custom_fields are clearly separated by resource scope and purpose.
All tools follow the snake_case productive_<verb> pattern, with most using verb_noun (productive_check_connection, productive_run_action) and a few using bare verbs (productive_get, productive_list). This is consistent and predictable, with no style mixing or vague duplicate verbs.
Twelve tools is well within the ideal scope for a broad API integration server. The set covers generic CRUD, named actions, time tracking, staged writes, and meta/discovery tools without ballooning into redundant or overly granular endpoints.
The server provides full lifecycle coverage: read, list, create, update, delete, run actions, and commit staged operations, plus support for custom fields and resource contracts. The meta tools fill the gaps that typically cause agent failures, such as knowing resource-specific filters, writable attributes, and custom-field keying.
Related MCP Connectors
Agent-complete, permission-scoped product operations for Priorify workspaces.
Permission-aware access to Wayfront clients, orders, projects, billing, tickets, and more.
Read time entries, projects, clients, tasks and invoices; log and update tracked time.
Query and analyze your pylo data. Changes become proposals you approve in the pylo admin UI or API.
Related MCP Servers
- AlicenseAqualityBmaintenanceA Model Context Protocol (MCP) server for accessing Productive.io API endpoints (projects, tasks, comments, todos), tailored for read-only operations, providing streamlined access to essential data while minimizing token consumption18MIT
- AlicenseAqualityDmaintenanceEnables interaction with Productive.io for task management, time tracking, budget monitoring, and project overview through natural language.8321 npmISC
- FlicenseBqualityDmaintenanceEnables AI assistants to interact with a Productive.io workspace for managing projects, tasks, time entries, budgets, and invoices through natural language.33-
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Productive.io task management platform, allowing users to retrieve tasks and filter by assignee, status, or project.30 npmISC