Brasil API MCP

Instructions

Implementation Reference

• src/tools/bank/index.ts:18-41 (handler)

  The handler function for the "bank-search" tool. It takes a bank code, fetches data from the Brasil API, handles errors, and formats the response with bank details including code, name, full name, and ISPB.

      async ({ code }) => {
        console.error(`Finding bank by code: ${code}`);
        
        const result = await getBrasilApiData(`/banks/v1/${code}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error finding bank: ${result.message}`);
        }
        
        // Format the response data
        const bank = result.data;
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Bank Information:
  Code: ${bank.code}
  Name: ${bank.name}
  Full Name: ${bank.fullName}
  ISPB: ${bank.ispb}
  ` 
          }]
        };
      }

• src/tools/bank/index.ts:15-17 (schema)

  Zod input schema defining the 'code' parameter as a string for the bank-search tool.

    code: z.string()
      .describe("Bank code to search for")
  },

• src/tools/bank/index.ts:11-42 (registration)

  Registers the "bank-search" tool on the MCP server inside the registerBankTools function, specifying name, description, schema, and handler.

    server.tool(
      "bank-search",  
      "Find information about a Brazilian bank by its code",
      {
        code: z.string()
          .describe("Bank code to search for")
      },
      async ({ code }) => {
        console.error(`Finding bank by code: ${code}`);
        
        const result = await getBrasilApiData(`/banks/v1/${code}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error finding bank: ${result.message}`);
        }
        
        // Format the response data
        const bank = result.data;
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Bank Information:
  Code: ${bank.code}
  Name: ${bank.name}
  Full Name: ${bank.fullName}
  ISPB: ${bank.ispb}
  ` 
          }]
        };
      }
    );

• src/utils/api.ts:11-40 (helper)

  Helper function used by bank-search to fetch bank data from https://brasilapi.com.br/api/banks/v1/{code}, returning structured success or error response.

  export async function getBrasilApiData(endpoint: string, params: Record<string, any> = {}) {
    try {
      const url = `${BASE_URL}${endpoint}`;
      console.error(`Making request to: ${url}`);
      
      const response = await axios.get(url, { params });
      return { 
        data: response.data,
        success: true
      };
    } catch (error: any) {
      console.error(`Error in API request: ${error.message}`);
      
      // Handle API errors in a structured format
      if (error.response) {
        return {
          success: false,
          statusCode: error.response.status,
          message: error.response.data?.message || error.message,
          error: error.response.data
        };
      }
      
      return {
        success: false,
        message: error.message,
        error
      };
    }
  }

• src/utils/api.ts:47-55 (helper)

  Helper function used by bank-search to format error responses in MCP-compatible format.

  export function formatErrorResponse(message: string) {
    return {
      content: [{ 
        type: "text" as const, 
        text: message 
      }],
      isError: true
    };
  }