mcp-server-corpayone

An MCP server for the Corpay One accounts-payable API: read bills and receipts, code them, manage the coding vocabulary, and — when explicitly enabled — approve or decline them.

Reads work out of the box. Every write is refused unless the server is configured to allow it, and each one goes through a prepare/commit ceremony so a change is reviewed before it happens.

What it can do

Read — expenses (bills, receipts, credit notes) with their state, vendor, amounts, attachments and coding; the attachment files themselves; the activity log and approver list for an expense; the coding vocabulary (categories, label lists and labels); vendors; webhook subscriptions. With broader scopes also credit accounts and card transactions, payment methods, team members, departments and items — see below.

Write — code an expense (category and labels, set atomically); split an expense into coded amount lines; create vendors and set their external ids; maintain categories and label lists; manage webhook subscriptions.

Approve — approve or decline an expense awaiting approval. Gated separately; see below.

Start with corpay_search_capabilities to discover the tools and the allowlisted endpoints.

Two things that will bite you

Amounts are in minor units. An amount of 930000 is 9,300.00 DKK. This applies to everything the API returns and everything you send it.

Coding uses Corpay's internal ids, not accounting numbers. A category has both an id and a number; the write takes the id, while the number is what a bookkeeper recognises. Always resolve ids with corpay_list_coding_options before coding, and match on the number or name found there.

Configuration

Copy .env.example and fill it in. Credentials are read from the environment only — never from tool arguments.

CORPAYONE_CLIENT_ID=...
CORPAYONE_CLIENT_SECRET=...
CORPAYONE_REFRESH_TOKEN=...
CORPAYONE_ENV=production

Create an app at https://app.corpayone.com/developers, then run the grant once to capture a refresh token:

npm run auth:grant

What the grant can reach

A standard Corpay app registration can obtain exactly these scopes, and auth:grant requests them: expenses.all, teams.all, teams.categories.all, teams.lists.all, teams.vendors.all, webhooks.all, offline_access.

Some endpoints need more than that, and it is not obtainable self-service: asking for such a scope makes the authorize call fail outright, and adding it to the app in the developer portal is not enough either — verified against the live service, identity.corpayone.com keeps its own client allowlist and still refuses it. Enabling those needs Corpay support.

So the server does not offer tools that cannot work. With a standard grant these are simply absent, rather than present and failing:

If Corpay grants more, list the scopes in CORPAYONE_SCOPE and the matching tools appear — the gate is configuration, not a code change.

Everything central to accounts payable works on a standard grant: expenses and their full detail, activity log, approvers, categories, label lists and labels, vendors, webhooks, coding, and approvals. The scope map is measured against the live API rather than inferred from the OpenAPI documents, because the real behaviour does not follow the obvious pattern — teams.all covers /teams/{id}/modules but not /teams/{id}/departments or /members, and expenses.all covers /expenses/{id}/approvers. Re-run npm run smoke:live after changing a grant; it skips what the grant cannot reach instead of reporting it as a failure.

Scoping the server to one company

One Corpay grant reaches every team the user belongs to, and the team is chosen per request. If you run one instance per company, set:

CORPAYONE_TEAM_ID=<team id>

The team then becomes a hard boundary: it is injected into every path, query and body, and a request naming a different team is rejected rather than quietly redirected. Without it, callers choose the team themselves — appropriate when the grant belongs to the person using it, but not when several people share one endpoint.

Endpoints that address a resource by id alone (/v3/expenses/{id}, /v2/expenses/{id}/…, /v1/webhooks/{id}) are checked too: on a pinned server the resource is read first and its team compared with CORPAYONE_TEAM_ID, both when preparing and again when committing. If the team of a resource cannot be determined the call is refused.

Find team ids with corpay_list_teams.

Write policy

Writes are off by default and are enabled in two independent steps:

CORPAYONE_ENABLE_WRITES=true      # coding, vendors, lists, webhooks
CORPAYONE_ENABLE_APPROVALS=true   # approve / decline an expense

Approval is separate because approving a bill releases it for payment. A server can be allowed to code all day without ever being able to approve anything.

Some endpoints are refused regardless: creating or deleting teams, managing members, and payment methods. Deleting a category, department, list or webhook is classified dangerous and is likewise refused. CORPAYONE_POLICY_PATH can point at a JSON file to narrow the policy further (or, deliberately, to widen it) — including maxAmount, compared in minor units.

Set CORPAYONE_AUDIT_LOG to a file path to record one JSON line per write attempt. Idempotency keys are hashed rather than stored.

Preparing and committing

No write tool sends anything. Each corpay_prepare_* tool validates the change against the allowlist and the policy and returns it with an operationHash. Pass that operation back to corpay_commit_prepared_operation — unchanged, with the hash restated and an idempotencyKey — to execute it. Editing the payload in between invalidates the hash.

The operationHash is an HMAC-SHA256 keyed by CORPAYONE_PREPARE_SECRET (a random per-process key when unset — set it when running several replicas, or when a prepare must survive a restart). A prepared operation expires after 15 minutes, and each prepare tool can only target its own endpoints, which is re-checked at commit.

Approvals are committed with corpay_commit_expense_approval instead; the two commit tools will not accept each other's operations.

corpay_prepare_expense_coding reads the expense first and reports its current coding alongside the proposed change, so the difference is visible before anything is committed.

Running it

npm install
npm run build

npm run dev        # stdio, for a desktop MCP client
npm run dev:http   # Streamable HTTP on 127.0.0.1:3000/mcp

A container image is published to ghcr.io/borgels/mcp-server-corpayone. It runs the HTTP transport:

docker run --rm -p 3000:3000 --env-file corpayone.env \
  ghcr.io/borgels/mcp-server-corpayone:latest

The HTTP transport binds to loopback by default and expects to sit behind a reverse proxy that terminates TLS and authenticates callers. MCP_HTTP_TOKEN adds a bearer check (compared in constant time); MCP_ALLOWED_ORIGINS restricts browser origins. If any *_TRUST_FORWARDED_USER variable is true, the HTTP transport refuses to start without MCP_HTTP_TOKEN.

Verifying a deployment

npm run typecheck && npm test        # offline
CORPAYONE_TEAM_ID=<team> npm run smoke:live   # read-only, hits the real API

The live smoke test also asserts that a cross-team read is refused, so it doubles as a check that the boundary is actually in force.

Attachments

corpay_get_expense_attachment returns the invoice or receipt file itself. Corpay has no endpoint that serves the file: /v3/expenses/{id} lists each attachment with a CloudFront URL signed for about an hour — the original upload (isOriginal, usually a PDF) plus one rendered JPG per page. The server downloads from that URL and returns the content:

• format: "file" (default) — the original, as an embedded resource (PDF) or

an image.

• format: "pages" — the rendered pages as images, which every MCP client can

show to the model. Use this to read what an invoice says.

Each result also carries the signed downloadUrl and when it expires. The expense is team-checked first, only https://attachments.corpayone.com is fetched, no credentials are sent to it, redirects are refused, and a call returns at most 15 MB and 10 pages.

Webhooks

validateWebhookSignature (exported from ./gateway) verifies the X-Roger-Signature header — t=<epochSeconds>;v1=<hex>, HMAC-SHA512 of <t>.<rawBody> keyed by CORPAYONE_WEBHOOK_SECRET. Pass the raw, unparsed body.

Notes on the API

Built against the published OpenAPI documents at api.corpayone.com/docs (public-v1, v2 and v3). The endpoint allowlist is generated from them, so an unlisted path fails locally instead of reaching Corpay.

One endpoint is not in those documents: PATCH /v2/expenses/{id} with application/json-patch+json. It is the only way to set category, labels and departments in a single atomic request, so it is used for coding and marked provisional in the catalog. Its writable paths are /categoryId (scalar) and /labels and /departments (plain id arrays); the JSON Patch op must be add when the field is empty and replace when it is not, which is why the expense is read before the patch is built.

Licence

Apache-2.0.