Brex MCP Server

Instructions

Implementation Reference

• src/tools/getBudgets.ts:35-60 (handler)

  Main execution handler for the 'get_budgets' tool: validates input parameters, calls BrexClient.getBudgets(), formats and returns the paginated budgets as JSON.

  registerToolHandler("get_budgets", async (request: ToolCallRequest) => {
    try {
      const params = validateParams(request.params.arguments);
      const client = getBrexClient();
      const apiParams: BudgetListParams = {
        limit: params.limit,
        cursor: params.cursor,
        parent_budget_id: params.parent_budget_id,
        spend_budget_status: params.spend_budget_status
      };
      const resp = await client.getBudgets(apiParams);
      const items = Array.isArray(resp.items) ? resp.items : [];
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            budgets: items,
            meta: { count: items.length, next_cursor: resp.next_cursor || null }
          }, null, 2)
        }]
      };
    } catch (error) {
      logError(`Error in get_budgets: ${error instanceof Error ? error.message : String(error)}`);
      throw error;
    }
  });

• src/tools/getBudgets.ts:13-32 (schema)

  Input parameter type definition (GetBudgetsParams interface) and validation function used by the tool handler.

  interface GetBudgetsParams {
    limit?: number;
    cursor?: string;
    parent_budget_id?: string;
    spend_budget_status?: SpendBudgetStatus;
  }
  
  function validateParams(input: unknown): GetBudgetsParams {
    const raw = (input || {}) as Record<string, unknown>;
    const out: GetBudgetsParams = {};
    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.cursor !== undefined) out.cursor = String(raw.cursor);
    if (raw.parent_budget_id !== undefined) out.parent_budget_id = String(raw.parent_budget_id);
    if (raw.spend_budget_status !== undefined) out.spend_budget_status = String(raw.spend_budget_status) as SpendBudgetStatus;
    return out;
  }

• src/tools/index.ts:63-63 (registration)

  Registration call that invokes the tool's register function during server initialization.

  registerGetBudgets(server);

• src/tools/index.ts:86-97 (schema)

  Tool schema definition provided in the listTools response, including inputSchema for MCP client validation.

    name: "get_budgets",
    description: "List budgets (read-only). Example: {\"limit\":10}",
    inputSchema: {
      type: "object",
      properties: {
        limit: { type: "number" },
        cursor: { type: "string" },
        parent_budget_id: { type: "string" },
        spend_budget_status: { type: "string", enum: ["ACTIVE","ARCHIVED","DRAFT"] }
      }
    }
  },

• src/services/brex/client.ts:722-730 (helper)

  Brex API client method getBudgets() called by the tool handler to fetch budgets from the Brex /v2/budgets endpoint.

  async getBudgets(params?: BudgetListParams): Promise<BudgetsResponse> {
    try {
      logDebug('Fetching budgets from Brex API', { params });
      return await this.get<BudgetsResponse>('/v2/budgets', params as unknown as Record<string, any>);
    } catch (error) {
      logError(`Error fetching budgets: ${error instanceof Error ? error.message : String(error)}`);
      throw error;
    }
  }