Concur Expense MCP Server

An HTTP-transport MCP server that lets an AI agent (primarily Cursor) file and manage SAP Concur expense reports on your behalf — discovering expense types and form fields, creating and filling out expenses, attaching receipts and attendees, and reading everything back. It never submits or approves reports; that step is deliberately left to a human in the Concur web UI.

Prerequisites

1. Node.js ≥ 20.
2. Concur app registration (admin-side): a client ID/secret with redirect URI http://127.0.0.1:8765/concur/callback and the scopes your tenant grants (this design was verified against 17 scopes, including the legacy EXPRPT + IMAGE scopes).
3. Credentials in Keeper: a record holding the client ID, client secret, and a company refresh token; note its record UID.
4. Keeper Commander installed (pip install keepercommander) with persistent login enabled, so commands run non-interactively:

   keeper shell
   > this-device register
   > this-device persistent-login on
   

5. Port 8765 free on the machine running the server — the Concur redirect URI pins it.

Setup

npm install
cp .env.example .env

Edit .env. Each secret can be a plain value or a *_COMMAND whose stdout (trimmed) is used as the value — priority is command > plain value > (for the company refresh token only) the persisted store in .secrets/tokens.json:

CONCUR_GEOLOCATION=https://us2.api.concursolutions.com
CONCUR_CLIENT_ID_COMMAND="keeper get <record-uid> --format=json --unmask | jq -r '.custom[]|select(.name==\"client_id\").value'"
CONCUR_CLIENT_SECRET_COMMAND="keeper get <record-uid> --format=json --unmask | jq -r '.custom[]|select(.name==\"client_secret\").value'"
CONCUR_COMPANY_REFRESH_TOKEN_COMMAND="keeper get <record-uid> --format=json --unmask | jq -r '.custom[]|select(.name==\"refresh_token\").value'"
# Plain-value fallbacks also accepted: CONCUR_CLIENT_ID=..., CONCUR_CLIENT_SECRET=..., CONCUR_COMPANY_REFRESH_TOKEN=...

The refresh-token command is bootstrap-only: once the server has run once, it persists token rotations to .secrets/tokens.json and prefers the stored value over the command on every subsequent start.

Setting up the Keeper record

Find an existing record's UID, or create one with the expected custom fields:

keeper search concur        # or: keeper list — note the record UID

keeper record-add --title "Concur MCP" \
  "custom.client_id=<your client id>" \
  "custom.client_secret=<your client secret>" \
  "custom.refresh_token=<your refresh token>"

The *_COMMAND examples above assume custom fields named exactly client_id, client_secret, and refresh_token. If your record uses different names, inspect it and adjust the select(.name==...) filters:

keeper get <record-uid> --format=json --unmask | jq '.custom'

Start the server. The start script does not auto-load .env, so export the variables into the environment first:

set -a; source .env; set +a
npm start

This serves http://127.0.0.1:8765/mcp and prints the bearer-key fallback URL (http://127.0.0.1:8765/auth/login) to the console.

Cursor configuration

Add to ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json:

{ "mcpServers": { "concur-expense": { "url": "http://127.0.0.1:8765/mcp" } } }

First connect: Cursor gets a 401 challenge, discovers the server's authorization metadata, registers itself via Dynamic Client Registration, and opens a browser for you to sign in to Concur once. The session then binds to that Concur user; your user refresh token is stored, so subsequent connects are silent — no repeated logins.

Fallback for clients whose MCP OAuth is broken, using the static bearer key from http://127.0.0.1:8765/auth/login:

{ "mcpServers": { "concur-expense": {
    "url": "http://127.0.0.1:8765/mcp",
    "headers": { "Authorization": "Bearer <key from http://127.0.0.1:8765/auth/login>" } } } }

Tool catalog

21 tools, registered in src/mcp/buildServer.ts, discoveryTools.ts, writeTools.ts, and readTools.ts.

Session/identity

• concur_whoami — profile, expense policies, and who the user may act for as a delegate. Call this first in any session.

Discovery

• concur_list_expense_types — usable (leaf, non-broken) expense types for the acting user's default policy.
• concur_get_expense_form_fields — writable form fields for a specific expense, with per-field guidance.
• concur_get_report_form_fields — report-header form fields (name, business purpose, custom fields) for a policy.
• concur_get_list_values — valid values for a list-type form field, by listId.
• concur_list_payment_types — payment types (e.g. Cash, Company Card) with the v3 ID needed to create an expense.
• concur_list_attendee_types — attendee types configured for the acting user (e.g. Business Guest, Spouse).
• concur_search_locations — search the location catalog (city/venue) to fill the Location field.

Write

• concur_create_report — create a new expense report header (echoes the created header back).
• concur_update_report — update an existing report's name and/or business purpose.
• concur_create_expense — create an expense inside a report; returns the type's form fields.
• concur_update_expense_fields — fill or change any writable fields on an expense (one or many at once); routes each field to its verified write path and returns a filled-field manifest + web link.
• concur_add_attendees — add one or more attendees to an expense, merge-preserving anyone already associated (Concur's association POST is a replace). Entries take either an email (matched to an employee via their login, else to a guest via externalId, else creates a guest when lastName+attendeeTypeCode are also given) or lastName+attendeeTypeCode; transactionAmount is optional (omitted amounts auto-split evenly).
• concur_remove_attendees — remove specific attendees (attendeeIds) or all of them (all: true); Concur has no per-attendee delete, so removal replace-POSTs the remaining list (amounts re-split evenly).
• concur_attach_receipt — attach a receipt image or PDF to an expense.

Read

• concur_list_reports — list the acting user's expense reports (legacy v3 listing), filterable by status or creation-date floor.
• concur_get_report — a report's header, its expenses, and a web deep link.
• concur_get_expense — a single expense, optionally with a filled/empty field manifest against its type's form.
• concur_get_expense_attendees — attendees currently associated with an expense.
• concur_search_attendees — search the attendee catalog: exact by type and/or externalId (the only filters Concur honors), or fuzzy via search=<fragment> (substring match on name/company/externalId over a short-lived guest cache — the API itself has no name search).

Delegate

• concur_list_delegators — users the session user delegates for, with permission flags (canPrepare, canSubmit, canViewReceipts).
• Every read/write tool above also accepts an optional onBehalfOfUserId, resolved through the delegate permission gate before anything runs on that person's data.

Deliberately absent: there is no submit or approve tool, at any point in the tool list. Filing stops at a complete, reviewable draft.

The guided flow

Every tool result returns {data, nextSteps: [string], warnings?: [string]}, so the calling agent always knows what to call next and why. The intended sequence:

concur_whoami ─► concur_list_expense_types ─► concur_create_report (or pick via concur_list_reports)
      ─► concur_create_expense (v3 POST: type, date, amount, currency, payment type, core fields)
      ─► concur_get_expense_form_fields (formFields?expenseTypeId=…)   ◄── uses the just-created expense as seed
      ─► concur_get_list_values (per listId field; agent picks by code/value)
      ─► concur_update_expense_fields (v3 PUT for core fields; compact v4 PATCH customData for list/custom fields)
      ─► concur_add_attendees (create/search + associate)   [types whose form requires attendees]
      ─► concur_attach_receipt (Image v1 with v3 key)
      ─► concur_get_expense (verify manifest) ─► repeat for next expense ─► done (never submit)

On create/update, the response includes a filled-field manifest (every field set — label, value, and for list fields the chosen item's code/value — assembled from a post-write read-back) and a web deep link (https://us2.concursolutions.com/nui/expense/report/{reportId}) so the agent can tell the user exactly what was filed and hand them a link to review it.

Testing

npm test        # 126 unit tests (vitest)
npm run typecheck

Two smoke suites validate the design end-to-end against the live Concur stage tenant, run as the logged-in user and as a delegate acting for a permitted delegator (plus a negative case for someone who isn't a delegate):

python3 scripts/smoke-preflight.py self       # API-level preflight, as the logged-in user
python3 scripts/smoke-preflight.py delegate   # API-level preflight, on behalf of a permitted delegator

npx tsx scripts/smoke-mcp.ts self             # MCP-tool-level, against the running server, as the logged-in user
npx tsx scripts/smoke-mcp.ts delegate         # MCP-tool-level, on behalf of a delegator + a negative refusal case

smoke-preflight.py proved the underlying Concur routing directly against the API before implementation (5/5 self, 5/5 delegate: 5 distinct leaf expense types × 5 distinct departments each, every writable required+optional field filled, receipts bound, attendees added where required, deep links generated). smoke-mcp.ts is the MCP-level counterpart — it drives the running server as a real MCP client (no raw Concur HTTP), exercising the actual registered tools end to end, and passed 5/5 self, 5/5 delegate, plus the negative delegate case correctly refused.

Security notes

• Localhost-only bind: the server listens on 127.0.0.1:8765 only — never on all interfaces — because that's the address baked into the Concur app's registered redirect URI (http://127.0.0.1:8765/concur/callback).
• Secrets on disk: .secrets/tokens.json (company + per-user tokens) and .secrets/mcp-clients.json (DCR registrations + issued MCP tokens) are written with restrictive permissions (directory 0700, files 0600), atomically, and are git-ignored.
• Token policy: user-scoped reads and writes always use the session user's own token. The company token is used only for two verified exceptions: (1) non-user config/catalog reads, and (2) the compact v4 expense PATCH for list/custom/orgUnit fields, which Concur's API rejects for user tokens outright (401, "only accessible by a valid company") — the server wraps that call so it only ever runs for the session's authenticated user, or for a delegator after a permission check. The company token never performs user activity outside those two exceptions.
• Per-session user binding: no tool call executes without an authenticated Concur user bound to the MCP session — company credentials alone never grant tool access.
• /auth/login reuses the existing session for any local caller: once a Concur user has completed the browser login once, hitting http://127.0.0.1:8765/auth/login again — from any process on the machine — mints a fresh 30-day bearer for that same logged-in user, with no re-authentication. This is deliberate (login-once-reuse UX, not a bug), but it means anyone able to reach 127.0.0.1:8765 can obtain a bearer once a session exists. The mitigation is not to run this server on a shared or multi-user machine.
• Delegate gating with cross-user refusal: acting on behalf of a delegator requires concur_list_delegators to show canPrepare true for that person first; the server refuses with a clear tool error for anyone else (not a delegate at all, or a delegate without canPrepare), so one user's session can never read or write another user's expense data without a verified delegate relationship.
• No submit/approve tools, by design: the tool catalog stops at a complete, filled draft. There is no code path anywhere in this server that submits or approves a report — that action is left to a human in the Concur web UI.