benepass-mcp

Unofficial, read-only MCP server for the Benepass employee-web API.

This project is not affiliated with, endorsed by, or supported by Benepass. It reverse-engineers the public employee-web client. Do not contact Benepass support about this server, login issues, missing endpoints, or anything else related to this unofficial tool.

The package name on the public registry is already taken. This repo sets private: true and is not published there.

Layout

• src/index.ts — stdio entry (serveStdio)

• src/server.ts — McpServer factory

• src/tools.ts — thin MCP adapters (TOOL_NAMES)

• src/app.ts — composition root

• src/accounts.ts — benefits derivation, HSA account selection

• src/hsa.ts — investment GET path walk

• src/api.ts — GET-only Benepass HTTP client

• src/http.ts — ky + host allowlist

• src/cognito.ts — Cognito OTP + token refresh

• src/session.ts — local session file

• src/schemas.ts — Zod models for Benepass JSON

• src/errors.ts — typed errors

• test/ — Vitest (in-process MCP client + unit tests)

Related MCP server: appstoreconnect-codex-mcp

Security model

• Read-only. The ky client for api.benefitsapi.com throws if the method is not GET. There are no tools for deposits, withdrawals, expense submit/update/delete, cards/PIN, payouts, or generic call_api.

• Tokens stay on your machine. After OTP login, the Cognito refresh token is stored at ~/.config/benepass-mcp/session.json (XDG via env-paths), mode 0600. Override with BENEPASS_SESSION_PATH (two P's). Tools never return refresh or access tokens. Tokens are never logged. Session files are gitignored.

• Outbound hosts only: cognito-idp.us-east-1.amazonaws.com, cognito.benefitsapi.com, api.benefitsapi.com.

• Cognito app client id 6l7jeu4r44kgndgeab4aot355m is a public client id (not a secret); it is baked into the employee-web app.

Login flow

1. Call start_login with your Benepass email. Cognito InitiateAuth CUSTOM_AUTH sends an OTP.

2. Call complete_login with the email, OTP, and challenge_session. Cognito RespondToAuthChallenge CUSTOM_CHALLENGE yields a refresh token that is written to the local session file. The tool returns only { ok, email }.

3. Later API calls POST grant_type=refresh_token to the token URL and send the access token as Authorization Bearer. Expiry is honored (expires_in and JWT exp).

4. If workspace_id is omitted, GET /v2/me/workspaces/ and persist the first type=employment workspace.

Tools

Auth: start_login, complete_login, auth_status, logout.

Reads: list_workspaces, list_accounts, list_benefits (derived from accounts enrollment.benefit + available balance), list_transactions, get_hsa_account_details, get_hsa_investments, list_documents, get_document, get_current_user.

list_benefits: Benepass has no /v2/me/benefits/. Benefits are derived from each account enrollment.benefit and the balance key ending in /available.

get_hsa_investments: tries GET only, first 2xx wins:

• /v2/me/accounts/{id}/hsa-investments/

• /v2/me/accounts/{id}/hsa-investments/portfolio/

• /v2/me/accounts/{id}/hsa-investments/portfolio/allocation/

• /v2/me/accounts/{id}/hsa-investments/asset-links/

If account_id is omitted, HSA accounts are selected from Zod-parsed fields (enrollment.benefit.benefit_type, enrollment.benefit.key, account.key, account.account_type, account.type) matching hsa / health_savings / health_savings_account. Account names are not searched. If those fields are absent, the tool falls back to an account id on GET /v2/me/hsa-account-details/. If every candidate 404s, the tool errors and includes that get_hsa_account_details payload. Those investment GET paths are reverse-engineered and may not exist for every account.

License

MIT

Stdio

This server speaks MCP on stdout and writes logs to stderr. Use the start script after build, or the dev script during development.

Cursor

Add a benepass entry to MCP settings (mcp.json) that launches this package's compiled entry. Authenticate with start_login then complete_login.

Example Cursor config is in cursor-mcp.example.json.