Plannr MCP server

An MCP server that lets Claude, ChatGPT and other MCP clients work with a financial adviser's Plannr CRM: clients, households, reviews due, tasks, cases, plans and notes, and (when enabled) creating tasks and notes. It is built from Plannr's public documentation: the OpenAPI 3.0.3 spec "Plannr API Documentation" at apidocs.plannrcrm.com/source.json and the API guide at api-how-to.plannrcrm.com (authentication, required headers, pagination, rate limits).

Once it's connected, an adviser or administrator can ask things like:

• "Whose annual review is due in the next month, and who is their adviser?"

• "What's open for the Evans family: tasks, cases and plans?"

• "Which of Sam Evans's pensions are under advice, and with which providers?"

• "What did we last discuss with Sam? Show me the call notes since September."

• With writes enabled: "Create a high-priority task to call Sam about drawdown on Friday, and log a meeting note on his record."

Tools

Not covered on purpose: everything else in an 875-operation API, including contact details and addresses endpoints, documents and files, fact finds, valuations, holdings, transactions, charges and fees, bank feeds, messages, webhooks, and every update and delete. Searching clients by email, phone number, National Insurance number or date of birth (all documented filters) is not offered either.

Related MCP server: Carebit MCP server

Setup

Requires Node 18 or later.

npm install
npm run build

You need a personal access token: in Plannr, go to Settings > Account Details and scroll to Personal Access Tokens. The guide recommends these for personal use and for agencies working on behalf of a Plannr customer. Plannr's OAuth2 authorization code flow (for apps used by many firms; client credentials are issued by emailing integrations@plannrcrm.com) is out of scope for this local version; see Going to production.

Most endpoints need the account to act for in an X-PLANNR-ACCOUNT-UUID header. Set PLANNR_ACCOUNT_UUID to the account.uuid of your employee login (the list_logins tool shows them). If it is not set, the server calls GET /api/v1/logins once and uses the response's preferred_account_uuid if there is one, otherwise your only employee login; if you have several employee logins it refuses and lists them so you can choose.

Claude Desktop: add this to claude_desktop_config.json:

{
  "mcpServers": {
    "plannr": {
      "command": "node",
      "args": ["/absolute/path/to/plannr-mcp/dist/index.js"],
      "env": { "PLANNR_ACCESS_TOKEN": "your-personal-access-token", "PLANNR_ACCOUNT_UUID": "your-employee-account-uuid" }
    }
  }
}

Claude Code:

claude mcp add plannr -e PLANNR_ACCESS_TOKEN=your-personal-access-token -e PLANNR_ACCOUNT_UUID=your-employee-account-uuid -- node /absolute/path/to/plannr-mcp/dist/index.js

Every request carries Accept: application/json and Content-Type: application/json, which the guide lists as required, and every request except GET /api/v1/logins carries X-PLANNR-ACCOUNT-UUID.

Safety defaults

• Read-only unless PLANNR_ALLOW_WRITES=true. Read tools carry the MCP readOnlyHint annotation; the two write tools are marked not read-only, not destructive and not idempotent. There is no update or delete tool.

• Clients and everyone else are identified by UUID and name by default. Only with include_contact_details=true does a tool return email addresses (of accounts, logins, members, assignees, authors and participants), the primary email and phone number, custom field values (only their names are shown by default, because a firm can record income, health or anything else in them), third-party references (platform and provider references) and policy, proposal, linked-policy and sub-account policy numbers.

• Never read from the records: money fields (plan values, valuations, case values, benefit amounts; see Status), bank details, National Insurance numbers, dates of birth and addresses. Every output is built field by field from a list of known fields, so a field of that kind is not copied even if a response carries it (the test suite serves records with date_of_birth, ni_number, bank_accounts, an address, an income and money objects and checks none of them comes back, with or without include_contact_details). The endpoints that hold contact details, addresses, documents and bank data are never called (the suite asserts the exact set of endpoints used). Sorting by value, which the API documents for cases and plans, is not offered, because the order would reveal the relative values the server otherwise withholds. No file is ever downloaded.

• Free text (client, household, task, case, plan and sub-account names; tag, group, status, type, provider, service level, workflow and custom field names; firm names; task descriptions; note contents; the error messages Plannr returns) is redacted by pattern. Always, with or without include_contact_details: a sort code with an account number, a sort code or account number introduced as such ("sort code", "acct", "account no."), a GB IBAN ([bank details redacted]), a 13 to 19 digit number that passes the Luhn check ([card number redacted]), a National Insurance number in the QQ 12 34 56 C shape ([NI number redacted]) and a date written after "DOB", "born", "date of birth" or "birthday" ([date of birth redacted]). By default, and not with include_contact_details: email addresses ([email redacted]), phone-number-like sequences ([phone redacted]) and UK postcodes ([postcode redacted]). Custom field values, returned only on request, go through the always-on part.

• These are heuristics. The phone match covers international numbers written with + or 00 (including +44 (0)7700 …), UK numbers with a bracketed area code, and UK-style 0… numbers of 9 to 11 digits with spaces, dots or hyphens between groups; other digit strings starting with 0 are redacted too, and so is any other 13 to 19 digit string that happens to pass the Luhn check (about one in ten), while UUIDs and timestamps are left alone. A bare date of birth, a bare six- or eight-digit number, a street address, an amount such as "salary £85,000" and a health detail are not caught and are returned as written, as is the rest of a note, since calling the notes tool is itself the request for notes. HTML tags in notes (such as the <span> of an @mention) are stripped.

• IDs are checked before any call: every ID must be a UUID. Dates must be real calendar dates in YYYY-MM-DD form, a review window must not end before it starts, and a tag, status, provider or plan name may not contain a comma (the API takes these as comma-separated lists).

• Rate limits: Plannr documents 500 requests per minute per user, an X-Ratelimit-Remaining header on every response and a 429 when the limit is exceeded, with the advice to back off; it does not mention Retry-After. Requests are spaced 150 ms apart (at most 400 a minute). A 429 is retried at most twice, waiting for Retry-After when present (in seconds or as an HTTP-date) and 2 s then 4 s when absent. Each wait is capped at 10 seconds; if Plannr asks for a longer wait the call gives up at once and says how long. Because one tool call can make several requests (the account lookup, then up to 10 pages of a list), every tool call also has a 45 s time budget (PLANNR_TOOL_BUDGET_S), under the MCP SDK's default 60 s request timeout: a retry wait that would end past it is not started and no further page is requested, the call fails at once saying so, and nothing is sent to Plannr after the client has given up. The server does not read X-Ratelimit-Remaining.

• 502, 503 and 504 are retried the same way for GET only; when all three attempts fail the error says the service may be unavailable, without the gateway's page. POST /api/v1/task and POST /api/v1/note are never retried after a gateway error, because the task or note may already exist; the error says to check list_tasks or list_client_notes first.

• A 200 whose body is not JSON (a proxy or login page in the way) is reported as an error naming PLANNR_BASE_URL, described by content type and size without quoting it. From error responses only Plannr's documented message and errors fields are passed on, redacted as above, and the access token is scrubbed from every message.

• Pagination follows the links.next URL Plannr returns. The server never builds a page number itself, re-adds any of its own filters the link leaves out, and refuses to follow a link to another host or another endpoint.

• A rejected token (401) produces a message that says which variable to fix and where tokens are created; a 403 names the account in use and points to PLANNR_ACCOUNT_UUID and list_logins; a 422 is passed on with Plannr's field errors.

Tests

npm test

The test suite:

1. Validates every fixture record against the component schemas in Plannr's published OpenAPI spec (LoginResource, AccountResource, CircleResource, TaskStatusResource, TaskResource, IndexTaskResource, CasesResource, Plans_PlanResource, NoteResource) with Ajv and ajv-formats. Because the schemas set no additionalProperties: false and mark almost nothing as required, every fixture is also walked key by key (following $ref, allOf and items) and a key the schema does not declare fails the check. Negative controls check that a schema still rejects wrong types and that the walk reports undeclared keys at any depth. The spec is downloaded from apidocs.plannrcrm.com/source.json to spec.json on the first run.

2. Starts a local mock of the API that serves those fixtures with the documented filters (every filter the server sends is applied, except filter[is_prospect] and filter[status] on /api/v1/account, since AccountResource declares neither a prospect flag nor a status; their pass-through is still asserted), the include-only relationships of the task index (author and completed_by only when included), per_page and the Links/Meta envelope the guide describes (on /api/v1/task the next link carries only the page number, elsewhere it keeps the query), Bearer auth with the spec's 401 body, a 403 for a missing or unknown X-PLANNR-ACCOUNT-UUID, 404s, 422s in the Plannr_ValidationError shape, an X-Ratelimit-Remaining header, a one-off 429 with Retry-After on GET /api/v1/task-status, and injected failures or replacement records on any endpoint (including a 429 on every other request, so that each page of a list is refused once). The mock's list, detail, created-task and error responses are validated against the response schemas the spec gives for each operation.

3. Starts the built server and drives it over stdio with the official MCP client: 31 checks covering tools/list and annotations, every read tool, pagination across two pages to the point where links.next is null (and a max_results cut reported as incomplete), a next link without the filters (they are re-added) and requests on one call spaced at least 140 ms apart, every documented filter each tool offers passed through exactly, the reviews-due operator filter, redaction of emails, phone numbers, custom field values, references and policy numbers by default and their return on request, contact details typed into client, household, tag, group, service level and custom field names and descriptions redacted, a fact-find note whose NI number, date of birth, bank details and card number are redacted in both modes and its postcode by default only, planted records served in place of every read (and of the created task and note, and of a 422) with those details and contact details in every free-text field and undeclared date_of_birth, ni_number, bank_accounts, address, income and money fields, none of which comes back, HTML stripped from notes, no money fields in plan and case output, a detail answer and a created task or note wrapped in {"data": …} unwrapped, the POST /api/v1/task and POST /api/v1/note bodies validated against the spec's request schemas (StoreTaskRequest, StoreNoteRequest), a 422 passed on with field errors, an empty 204 on a note handled, writes absent with PLANNR_ALLOW_WRITES unset and set to false, bad UUIDs, dates, reversed review windows and comma-containing names rejected before any request, the 404 message, the 429 retry waiting for Retry-After in the seconds and HTTP-date forms and 2 s then 4 s without it, giving up after three attempts and at once above the cap, a 429 on POST /api/v1/note retried once, a 429 on the first GET /api/v1/logins with two calls at once resolving the account once, the per-call time budget (lowered to 3 s) stopping a list whose pages each get a 429 with a clean error and no later request, a 502 retried for GET, a GET failing three times with 503 reported without the HTML, a 502 on POST /api/v1/task and a 503 on POST /api/v1/note not retried, a non-JSON 200 reported as an error, next links to another host or another endpoint refused, an error message passed on with its email, phone number and the token redacted, the account resolved from /api/v1/logins (the only employee login, preferred_account_uuid, and a refusal listing the choices when ambiguous), list_logins showing the account it acts for with PLANNR_ACCOUNT_UUID unset (or that none was chosen), the 401 message for a wrong token (pasted with a Bearer prefix, not doubled), the 403 message for a wrong account, and that every request used the Bearer token, the required headers, a documented method and path and only query parameters that operation documents (apart from the page number taken from Plannr's next link), with the exact set of 15 endpoints used.

Status

This is a working prototype. It has not yet been run against the live API, because it was built without a Plannr account (no public trial or sandbox was found; personal access tokens come from customers' own accounts). Everything below is taken from the published documentation and should be confirmed on a real account:

• Pagination. The spec documents only per_page (default 15, max 500) and declares only data in its list responses; the guide describes a Links block with four page links and a Meta block (per page, total, current and last page) in a screenshot. The key names used here (links.first/last/prev/next, meta.current_page/last_page/per_page/total) are the Laravel convention that description matches. Whether links.next keeps the filters is not documented; both cases are handled. Whether per_page=100 is accepted everywhere this server uses it.

• Get-by-UUID and create responses. The spec types them as the resource itself; if the live API wraps them in {"data": …} they are unwrapped.

• POST /api/v1/note: the spec documents no success response (only 401 and 422). The mock answers 201 with a NoteResource; the tool also accepts an empty answer.

• The account header: what status a missing or wrong X-PLANNR-ACCOUNT-UUID gets (the mock answers 403), whether GET /api/v1/account/{uuid} and the notes endpoints need it (the spec does not declare it there; the guide says every endpoint but the logins list does, so it is always sent), and where preferred_account_uuid sits in the GET /api/v1/logins response (the guide names it but it is not in the spec; the server looks at the top level and on each login).

• Filter encoding and semantics: booleans are sent as true/false; the operator filter filter[next_review_date]=>=2026-10-01,<=2026-10-31 is sent URL-encoded; whether filter[client_uuid] on tasks includes tasks on the client's cases and plans (the mock matches tasks on the client only); whether filter[status] on accounts matches what the UI calls a client status (the AccountResource schema has no status field); which relationships the index routes return without an include (the mock returns only those included).

• Relationship shapes: the spec types a case's participants and plans as single objects and every *_Summary relationship without property types; the fixtures follow the spec, and the server reads either an object or an array.

• Money: the spec's money objects (value, total_benefit_amount, valuations) describe example and description as properties of amount, formatted and currency, so no real money value can pass the schema. This version therefore returns no money fields at all (amounts typed into free text are returned as written, see Safety defaults); valuations are the first thing to add once the live shape is known.

• Dates: task due dates follow the spec's example format 2021-01-01 00:00:00; review dates are ISO 8601 with an offset. The server passes both through as given.

• The wording of Plannr's 404 and 422 messages for these endpoints (the mock uses the forms the spec documents for other endpoints) and of a 429 body (not documented; the mock uses Laravel's "Too Many Attempts.").

• Visibility: the spec says task lists are constrained by the user's role; the server returns whatever the token's login may see.

• How the API reacts to requests at the spaced rate here; the documented limit is 500 a minute per user.

Going to production

This version runs locally over stdio with the user's own personal access token. For advisers to connect from claude.ai or ChatGPT without handling tokens, the next step is a remote server (Streamable HTTP) that uses the OAuth2 authorization code flow Plannr already offers, hosted by Plannr, so each user's own login and permissions apply, and then a listing in the Claude and ChatGPT connector directories. Valuations and other amounts can follow once the money shape is confirmed on a live account, and more write tools (completing tasks, updating review dates) once they can be tested on a test firm.

Licence

MIT. Built by Alexandru Dragoș (alexandru.dragos96@gmail.com) with an AI agent (Claude) working under his direction.