Brex MCP Server

Instructions

Implementation Reference

• src/tools/getCardTransactions.ts:58-119 (handler)

  Main execution logic for the get_card_transactions tool: parameter validation, API call to Brex client, response projection and summarization if token limit exceeded, formatted JSON output.
  registerToolHandler("get_card_transactions", async (request: ToolCallRequest) => { try { const params = validateParams(request.params.arguments); const client = getBrexClient(); // Do not pass expand parameter to card transactions API // The endpoint doesn't support it and returns 400 errors const resp = await client.getCardTransactions({ cursor: params.cursor, limit: params.limit, user_ids: params.user_ids, posted_at_start: params.posted_at_start // expand is intentionally omitted - not supported by this endpoint }); const items = Array.isArray(resp.items) ? resp.items : []; // Project via limiter infra (wrap items into Expense type-compatible projection path names kept simple) const projectionFields = params.fields && params.fields.length ? params.fields : DEFAULT_TX_FIELDS; const payloadText = JSON.stringify(items); const tooBig = estimateTokens(payloadText) > 24000; const summarized = params.summary_only || tooBig; const outputItems = summarized ? items.map((t: any) => { const out: any = {}; projectionFields.forEach((p) => { const parts = p.split('.'); let cur: any = t; for (const part of parts) { cur = cur?.[part]; if (cur === undefined) break; } if (cur !== undefined) { let o: any = out; for (let i = 0; i < parts.length - 1; i++) { o[parts[i]] = o[parts[i]] ?? {}; o = o[parts[i]]; } o[parts[parts.length - 1]] = cur; } }); return out; }) : items; return { content: [{ type: "text", text: JSON.stringify({ transactions: outputItems, meta: { count: outputItems.length, next_cursor: (resp as any).next_cursor || null, summary_applied: summarized } }, null, 2) }] }; } catch (error) { logError(`Error in get_card_transactions: ${error instanceof Error ? error.message : String(error)}`); throw error; } });
• src/tools/getCardTransactions.ts:26-34 (schema)

  TypeScript interface defining the input parameters for the get_card_transactions tool.
  interface GetCardTransactionsParams { cursor?: string; limit?: number; user_ids?: string[]; posted_at_start?: string; expand?: string[]; // Kept for interface compatibility but not used summary_only?: boolean; fields?: string[]; }
• src/tools/getCardTransactions.ts:57-120 (registration)

  Registration function that adds the get_card_transactions handler to the toolHandlers map, called during server initialization.
  export function registerGetCardTransactions(_server: Server): void { registerToolHandler("get_card_transactions", async (request: ToolCallRequest) => { try { const params = validateParams(request.params.arguments); const client = getBrexClient(); // Do not pass expand parameter to card transactions API // The endpoint doesn't support it and returns 400 errors const resp = await client.getCardTransactions({ cursor: params.cursor, limit: params.limit, user_ids: params.user_ids, posted_at_start: params.posted_at_start // expand is intentionally omitted - not supported by this endpoint }); const items = Array.isArray(resp.items) ? resp.items : []; // Project via limiter infra (wrap items into Expense type-compatible projection path names kept simple) const projectionFields = params.fields && params.fields.length ? params.fields : DEFAULT_TX_FIELDS; const payloadText = JSON.stringify(items); const tooBig = estimateTokens(payloadText) > 24000; const summarized = params.summary_only || tooBig; const outputItems = summarized ? items.map((t: any) => { const out: any = {}; projectionFields.forEach((p) => { const parts = p.split('.'); let cur: any = t; for (const part of parts) { cur = cur?.[part]; if (cur === undefined) break; } if (cur !== undefined) { let o: any = out; for (let i = 0; i < parts.length - 1; i++) { o[parts[i]] = o[parts[i]] ?? {}; o = o[parts[i]]; } o[parts[parts.length - 1]] = cur; } }); return out; }) : items; return { content: [{ type: "text", text: JSON.stringify({ transactions: outputItems, meta: { count: outputItems.length, next_cursor: (resp as any).next_cursor || null, summary_applied: summarized } }, null, 2) }] }; } catch (error) { logError(`Error in get_card_transactions: ${error instanceof Error ? error.message : String(error)}`); throw error; } }); }
• src/tools/index.ts:18-56 (registration)

  Top-level import and registration call for the get_card_transactions tool during registerTools(server). Note: import at line 18, call at line 56.
  import { registerGetCardTransactions } from "./getCardTransactions.js"; import { registerGetCashAccountStatements } from "./getCashAccountStatements.js"; import { registerGetExpenseById } from "./getExpenseById.js"; import { registerGetCardExpenseById } from "./getCardExpenseById.js"; import { registerGetCardStatementsPrimary } from "./getCardStatementsPrimary.js"; import { registerGetCashTransactions } from "./getCashTransactions.js"; import { registerGetBudgets } from "./getBudgets.js"; import { registerGetBudgetById } from "./getBudgetById.js"; import { registerGetSpendLimits } from "./getSpendLimits.js"; import { registerGetSpendLimitById } from "./getSpendLimitById.js"; import { registerGetBudgetPrograms } from "./getBudgetPrograms.js"; import { registerGetBudgetProgramById } from "./getBudgetProgramById.js"; import { logError } from "../utils/logger.js"; import { ExpenseType, ExpenseStatus, ExpensePaymentStatus } from "../services/brex/expenses-types.js"; // Minimal request shape passed to individual tool handlers export type ToolCallRequest = { params: { name?: string; arguments?: Record<string, unknown> } }; // Store tool handlers export const toolHandlers = new Map<string, (request: ToolCallRequest) => Promise<unknown>>(); /** * Registers all tools with the server * @param server The MCP server instance */ export function registerTools(server: Server): void { // Register tool handlers registerGetTransactions(server); registerGetExpenses(server); registerGetAccountDetails(server); registerUploadReceipt(server); registerMatchReceipt(server); registerUpdateExpense(server); // Register pagination-aware tool handlers registerGetAllAccounts(server); registerGetAllExpenses(server); registerGetAllCardExpenses(server); registerGetCardTransactions(server);
• src/tools/getCardTransactions.ts:36-55 (helper)

  Input validation and normalization function for tool parameters, including type coercion, range checks, and date parsing.
  function validateParams(input: unknown): GetCardTransactionsParams { const raw = (input || {}) as Record<string, unknown>; const out: GetCardTransactionsParams = {}; if (raw.cursor !== undefined) out.cursor = String(raw.cursor); if (raw.limit !== undefined) { const n = parseInt(String(raw.limit), 10); if (isNaN(n) || n <= 0 || n > 100) throw new Error("Invalid limit (1..100)"); out.limit = n; } if (raw.user_ids !== undefined) out.user_ids = Array.isArray(raw.user_ids) ? raw.user_ids.map(String) : [String(raw.user_ids)]; if (raw.posted_at_start !== undefined) out.posted_at_start = new Date(String(raw.posted_at_start)).toISOString(); // NOTE: expand parameter is intentionally ignored for card transactions // The Brex card transactions API endpoint does not support expand parameters // and will return 400 "Unsupported entity expansion" if expand is passed. // Merchant information is always included by default in the response. if (raw.expand !== undefined) out.expand = Array.isArray(raw.expand) ? raw.expand.map(String) : [String(raw.expand)]; if (raw.summary_only !== undefined) out.summary_only = Boolean(raw.summary_only); if (raw.fields !== undefined) out.fields = Array.isArray(raw.fields) ? raw.fields.map(String) : [String(raw.fields)]; return out; }
• src/services/brex/client.ts:330-355 (helper)

  Brex API client method that performs the HTTP GET to /v2/transactions/card/primary, handling pagination params and error logging.
  async getCardTransactions(options?: { cursor?: string; limit?: number; user_ids?: string[]; posted_at_start?: string; expand?: string[]; }): Promise<PageCardTransaction> { try { const params: Record<string, unknown> = {}; if (options) { if (options.cursor) params.cursor = options.cursor; if (options.limit) params.limit = options.limit; if (options.user_ids && options.user_ids.length > 0) params.user_ids = options.user_ids; if (options.posted_at_start) params.posted_at_start = options.posted_at_start; if (options.expand && options.expand.length > 0) params['expand[]'] = options.expand; } logDebug('Fetching card transactions from Brex API'); const response = await this.client.get('/v2/transactions/card/primary', { params }); logDebug(`Successfully fetched ${response.data.items.length} card transactions`); return response.data; } catch (error) { this.handleApiError(error, 'GET', '/v2/transactions/card/primary'); throw error; } }