Skip to main content

Set up the BILL Spend & Expense MCP server

The BILL Spend & Expense MCP server gives AI agents read access to your company's spend data: budgets and their members, physical and virtual cards, card transactions, and reimbursement requests. This guide covers generating an API token in BILL, installing the connector in MintMCP, and pointing it at production or BILL's sandbox.

Prerequisites​

  • A MintMCP admin account
  • A BILL Spend & Expense account with the ADMIN role

Generate a Spend & Expense API token​

The token is company-scoped rather than personal, so one token covers the whole organization and every connector user sees the same company-wide data.

  1. Sign in to BILL Spend & Expense at login.us.bill.com with a user that has the ADMIN role.
  2. Follow BILL's Generate an API token in BILL Spend & Expense to create the token.
  3. Copy the token. You enter it in MintMCP in the next step.

To test against BILL's sandbox instead of live data, request a sandbox company through BILL's Sandbox Access Form, which returns its own API token and a pre-populated test company.

Add BILL Spend & Expense to MintMCP​

  1. In MintMCP, go to MCP store > Manage store > Recommended servers.

  2. Find BILL Spend & Expense and click to install it.

  3. Set the environment variables:

    VariableRequiredDescription
    BILL_API_TOKENYesThe Spend & Expense API token from the previous step. Stored encrypted.
    BILL_ENVIRONMENTNoproduction (default) queries live data at gateway.prod.bill.com. Set to sandbox for BILL's test environment at gateway.stage.bill.com.

  4. Click Install.

Both variables are organization-wide. BILL restricts token creation to ADMIN users, so per-user tokens are not workable: a member without the ADMIN role has no way to produce one.

Available tools​

All tools are read-only and carry readOnlyHint, so clients can distinguish them from tools that change state. Nothing in this connector moves money, issues a card, or modifies a budget.

AreaTools
Budgetslist_budgets, get_budget, list_budget_members, get_budget_member
Cardslist_cards, get_card
Transactionslist_transactions, get_transaction, list_transaction_custom_fields, list_transaction_custom_field_values
Reimbursementslist_reimbursements, get_reimbursement
Userslist_users, get_user, get_current_user

Security considerations​

  • The token is company-scoped, so every connector user reads the same organization-wide data: all budgets, all cards, all users, and every user's transactions. Scope access with tool customization and gateway permissions rather than expecting BILL to filter per user.
  • Card numbers are never returned. Card records expose only the last four digits, expiry, and status.
  • Transaction and user records contain financial and personal data (merchant names, amounts, email addresses, phone numbers), so treat the connector as a sensitive data source when granting access.
  • BILL restricts token generation to ADMIN users, which means the credential carries administrator-level read access to spend data.
  • To revoke access, regenerate or delete the token in BILL, then update BILL_API_TOKEN in MintMCP.
  • BILL rate-limits the Spend & Expense API to 60 calls per token per minute across the whole organization, so heavy concurrent agent use shares one budget.

Troubleshooting​

  • BILL API 401 (INVALID_TOKEN): Request contains invalid access token. The token reached BILL and was rejected. Confirm you copied a Spend & Expense API token rather than a BILL AP & AR developer key, and that BILL_ENVIRONMENT matches the environment the token came from. Sandbox tokens do not authenticate against production.
  • Tools return a 401 saying the connector is not configured. No token reached the server. Check that BILL_API_TOKEN is set in the connector's environment variables.
  • A user cannot generate a token in BILL. Only ADMIN users can create Spend & Expense API tokens. Ask a BILL administrator to generate one for the connector.
  • Reimbursement or custom field tools return empty results. Those tools return what BILL holds, and a company with no reimbursements submitted or no transaction custom fields configured returns an empty list rather than an error.
  • The AP & AR API is separate. BILL's Accounts Payable and Receivable product uses different credentials (a developer key plus username, password, and organization ID) and a session that expires after 35 minutes of inactivity. This connector covers Spend & Expense only.

Next steps​