get_card_transactions
Retrieve and list primary card transactions with filtering options for user IDs, date ranges, and field expansion to access detailed financial data.
Instructions
LIST: Primary card transactions. Returns complete transaction objects. Example: {"limit":10,"posted_at_start":"2025-08-01T00:00:00Z","expand":["merchant"]}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Pagination cursor | |
| expand | No | Fields to expand | |
| limit | No | Items per page (default 50) | |
| posted_at_start | No | ISO timestamp to start from | |
| user_ids | No | Optional filter by user IDs |
Implementation Reference
- src/tools/getCardTransactions.ts:58-119 (handler)Main execution logic for the get_card_transactions tool: validates input, fetches from Brex API, applies field projection and summarization if needed, formats response as JSON.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; } });
- 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)Function that registers the get_card_transactions tool handler with the MCP server.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:56-56 (registration)Invocation of registerGetCardTransactions during overall tools registration in the main index.registerGetCardTransactions(server);
- src/tools/index.ts:208-219 (schema)Input schema definition for get_card_transactions exposed in the listTools MCP response.name: "get_card_transactions", description: "LIST: Primary card transactions. Returns complete transaction objects. Example: {\"limit\":10,\"posted_at_start\":\"2025-08-01T00:00:00Z\",\"expand\":[\"merchant\"]}", inputSchema: { type: "object", properties: { cursor: { type: "string", description: "Pagination cursor" }, limit: { type: "number", description: "Items per page (default 50)" }, user_ids: { type: "array", items: { type: "string" }, description: "Optional filter by user IDs" }, posted_at_start: { type: "string", description: "ISO timestamp to start from" }, expand: { type: "array", items: { type: "string" }, description: "Fields to expand" } } }
- src/services/brex/client.ts:330-355 (helper)BrexClient.getCardTransactions method called by the tool handler to fetch raw transactions from Brex API.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; } }