Brex MCP Server

Instructions

Implementation Reference

• src/tools/matchReceipt.ts:99-138 (handler)

  Core execution logic for the match_receipt tool: validates input, calls Brex API to create receipt match request, returns pre-signed upload URL and instructions.

  registerToolHandler("match_receipt", async (request: ToolCallRequest) => {
    try {
      // Validate parameters
      const params = validateParams(request.params.arguments);
      logDebug(`Creating receipt match for: ${params.receipt_name}`);
      
      // Get Brex client
      const brexClient = getBrexClient();
      
      try {
        // Create receipt match request to get pre-signed URL
        const matchResult = await createReceiptMatch(brexClient, {
          receipt_name: params.receipt_name,
          receipt_type: params.receipt_type,
          notify_email: params.notify_email
        });
        
        logDebug(`Successfully created receipt match with ID: ${matchResult.id}`);
        
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              status: "success",
              receipt_id: matchResult.id,
              upload_url: matchResult.uri,
              message: "Receipt match created successfully. Use the provided URL to upload the receipt file.",
              instructions: "1. Use this pre-signed URL with a PUT request to upload your receipt.\n2. The URL expires in 30 minutes.\n3. Once uploaded, Brex will automatically try to match the receipt with existing expenses."
            }, null, 2)
          }]
        };
      } catch (apiError) {
        logError(`Error creating receipt match: ${apiError instanceof Error ? apiError.message : String(apiError)}`);
        throw new Error(`Failed to create receipt match: ${apiError instanceof Error ? apiError.message : String(apiError)}`);
      }
    } catch (error) {
      logError(`Error in match_receipt tool: ${error instanceof Error ? error.message : String(error)}`);
      throw error;
    }
  });

• src/tools/index.ts:321-342 (schema)

  MCP-exposed input schema for the match_receipt tool, defining parameters and requirements in the list tools response.

  {
    name: "match_receipt",
    description: "Create a pre-signed URL for uploading a receipt that will be automatically matched with existing expenses",
    inputSchema: {
      type: "object",
      properties: {
        receipt_name: {
          type: "string",
          description: "Name of the receipt file (e.g., 'receipt.jpg')"
        },
        receipt_type: {
          type: "string",
          description: "Type of the receipt (optional)"
        },
        notify_email: {
          type: "string",
          description: "Email address to notify after matching (optional)"
        }
      },
      required: ["receipt_name"]
    }
  },

• src/tools/matchReceipt.ts:98-139 (registration)

  Function that registers the match_receipt tool handler with the internal toolHandlers map.

  export function registerMatchReceipt(_server: Server): void {
    registerToolHandler("match_receipt", async (request: ToolCallRequest) => {
      try {
        // Validate parameters
        const params = validateParams(request.params.arguments);
        logDebug(`Creating receipt match for: ${params.receipt_name}`);
        
        // Get Brex client
        const brexClient = getBrexClient();
        
        try {
          // Create receipt match request to get pre-signed URL
          const matchResult = await createReceiptMatch(brexClient, {
            receipt_name: params.receipt_name,
            receipt_type: params.receipt_type,
            notify_email: params.notify_email
          });
          
          logDebug(`Successfully created receipt match with ID: ${matchResult.id}`);
          
          return {
            content: [{
              type: "text",
              text: JSON.stringify({
                status: "success",
                receipt_id: matchResult.id,
                upload_url: matchResult.uri,
                message: "Receipt match created successfully. Use the provided URL to upload the receipt file.",
                instructions: "1. Use this pre-signed URL with a PUT request to upload your receipt.\n2. The URL expires in 30 minutes.\n3. Once uploaded, Brex will automatically try to match the receipt with existing expenses."
              }, null, 2)
            }]
          };
        } catch (apiError) {
          logError(`Error creating receipt match: ${apiError instanceof Error ? apiError.message : String(apiError)}`);
          throw new Error(`Failed to create receipt match: ${apiError instanceof Error ? apiError.message : String(apiError)}`);
        }
      } catch (error) {
        logError(`Error in match_receipt tool: ${error instanceof Error ? error.message : String(error)}`);
        throw error;
      }
    });
  } 

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

  Top-level call to register the match_receipt tool during overall tools initialization.

  registerMatchReceipt(server);

• src/tools/matchReceipt.ts:20-24 (schema)

  TypeScript interface for input validation of match_receipt parameters.

  interface MatchReceiptParams {
    receipt_name: string;
    receipt_type?: string;
    notify_email?: string;
  }

• src/tools/matchReceipt.ts:76-92 (helper)

  Helper function to validate and type-check input parameters for the tool.

  function validateParams(input: any): MatchReceiptParams {
    if (!input) {
      throw new Error("Missing parameters");
    }
    
    if (!input.receipt_name) {
      throw new Error("Missing required parameter: receipt_name");
    }
    
    const params: MatchReceiptParams = {
      receipt_name: input.receipt_name,
      receipt_type: input.receipt_type,
      notify_email: input.notify_email
    };
    
    return params;
  }