dennisonbertram/mcp-brex

Brex MCP Server

A Model Context Protocol (MCP) server for the Brex API. Optimized for safe, small, read-only responses with projection and batching.

What’s New (0.3.2)

• Fix: Tools now include a permissive inputSchema in the tools list so clients like Claude Code properly display and allow calling tools. No behavior changes to handlers.

Installation

Claude Code

# Install the package
npm install -g mcp-brex

# Add to Claude Code with your API key
claude mcp add brex --env BREX_API_KEY=your_brex_api_key -- npx mcp-brex

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "brex": {
      "command": "npx",
      "args": ["mcp-brex"],
      "env": {
        "BREX_API_KEY": "your_brex_api_key"
      }
    }
  }
}

Manual Setup (Development)

git clone https://github.com/dennisonbertram/mcp-brex.git
cd mcp-brex
npm install
npm run build
claude mcp add brex --env BREX_API_KEY=your_key -- node build/index.js

Resources

• brex://expenses | brex://expenses/{id} | brex://expenses/card | brex://expenses/card/{id}
• brex://budgets | brex://budgets/{id}
• brex://spend_limits | brex://spend_limits/{id}
• brex://budget_programs | brex://budget_programs/{id}
• brex://transactions/card/primary | brex://transactions/cash/{id}
• brex://docs/usage (compact usage guide for agents)

Notes:

• Resources accept ?summary_only=true&fields=id,status,... to control payload size.
• Expenses resources auto-expand merchant and budget for readability.

Tools (read-only unless noted)

• Budgets: get_budgets, get_budget
• Spend Limits: get_spend_limits, get_spend_limit
• Budget Programs: get_budget_programs, get_budget_program
• Expenses (single page): get_expenses
• Expenses (paginated): get_all_expenses, get_all_card_expenses
• Expense by ID: get_expense, get_card_expense
• Card Statements: get_card_statements_primary
• Transactions: get_card_transactions, get_cash_transactions (note: no date filter/expand on transactions)
• Cash Statements: get_cash_account_statements
• Accounts: get_all_accounts, get_account_details
• Receipts (write): match_receipt, upload_receipt
• Updates (write): update_expense

How to call tools

Always send parameters under arguments (not input). Keep payloads small with pagination and filtering.

Common parameters:

• Pagination: page_size (<=50), max_items (<=200 recommended)
• Date filtering: start_date, end_date, window_days
• Status filtering: status array for expenses/transactions
• Amount filtering: min_amount, max_amount for expenses
• Merchant filtering: merchant_name for expenses
• Expand control: expand array to include nested objects (e.g., ["merchant", "budget"])

Recommended examples:

{
  "name": "get_all_card_expenses",
  "arguments": {
    "page_size": 10,
    "max_items": 20,
    "start_date": "2025-08-25T00:00:00Z",
    "end_date": "2025-08-26T00:00:00Z",
    "status": ["APPROVED"],
    "min_amount": 100
  }
}

{
  "name": "get_expenses",
  "arguments": {
    "limit": 5,
    "status": "APPROVED"
  }
}

{
  "name": "get_card_transactions",
  "arguments": {
    "limit": 10,
    "summary_only": true,
    "fields": ["id", "posted_at", "amount.amount", "amount.currency", "merchant.raw_descriptor"]
  }
}

{
  "name": "get_all_accounts",
  "arguments": {
    "page_size": 10,
    "max_items": 20,
    "status": "ACTIVE"
  }
}

{
  "name": "get_transactions",
  "arguments": {
    "accountId": "acc_123456789",
    "limit": 10
  }
}

{
  "name": "get_expenses",
  "arguments": {
    "limit": 5,
    "expand": ["merchant", "user"]
  }
}

Pagination and Filtering Best Practices

IMPORTANT: Use pagination, filtering, and sorting to control response sizes instead of relying on summaries.

Key Parameters for Data Control:

• page_size: number — Items per page (recommended: ≤50)
• max_items: number — Maximum total items across all pages (recommended: ≤200)
• start_date/end_date: string — ISO date range filtering
• window_days: number — Split large date ranges into smaller batches
• status: string[] — Filter by status (e.g., ["APPROVED", "PENDING"])
• min_amount/max_amount: number — Amount-based filtering for expenses

Best Practices:

• Always use date ranges for bulk requests to avoid huge responses
• Use small page sizes (≤50) and reasonable max_items (≤200)
• Apply status filters to get only the data you need
• Use window_days (e.g., 7) to batch large date ranges
• Control nested object expansion with the expand parameter:
  • Default: expand: [] returns lean objects (~500-1000 tokens each)
  • With expansion: expand: ["merchant", "budget"] returns full objects (~15K+ tokens each)
  • Available expand options: merchant, budget, user, department, location, receipts
• Test with small limits first before scaling up
• Cash endpoints require additional Brex scopes; handle 403s gracefully

Note: Brex transactions endpoints (card and cash) do not support posted_at_start or expand. Retrieve transactions and, if needed, filter client-side by posted_at/posted_at_date.

Money & Units

All amounts from Brex are in cents. This server annotates money fields in tool outputs by default to prevent unit mistakes:

• amount_cents: integer (e.g., 100000)
• amount_dollars: number in dollars (e.g., 1000.0)
• amount_formatted: human-friendly string (e.g., "$1,000.00")

Example (expense purchased_amount):

{
  "purchased_amount": {
    "amount_cents": 100000,
    "amount_dollars": 1000.0,
    "amount_formatted": "$1,000.00",
    "currency": "USD"
  }
}

Controls:

• format_amounts: "cents" | "dollars" | "both" (default: "both")
• include_formatted: boolean (default: true)
• include_summary: boolean (default: true) adds meta.summary totals/averages

Publishing

Only build/, README.md, and LICENSE are published.

License

MIT — see LICENSE.