listar_bancos
List all Brazilian banks from BACEN: returns name, COMPE code, and ISPB for each institution to help identify bank codes by name.
Instructions
Lista TODOS os bancos brasileiros cadastrados no BACEN via BrasilAPI. Retorna em JSON um array com nome, código COMPE/Febraban e ISPB de cada instituição. Use quando o usuário quiser uma lista completa, buscar banco por nome (você filtra o resultado), ou descobrir o código de um banco específico cujo nome ele forneceu. NÃO use quando o usuário já forneceu o código numérico — nesse caso use consultar_banco que é mais barato. A lista tem ~250 entradas; cite só os relevantes na resposta.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/tools/banco.ts:93-93 (schema)Zod schema for listar_bancos (no input parameters needed).
export const listarBancosSchema = z.object({}); - src/tools/banco.ts:111-135 (handler)Main handler function: fetches all banks from BrasilAPI /banks/v1 endpoint and returns the JSON result.
export async function listarBancosHandler( _input: ListarBancosInput, ): Promise<CallToolResult> { try { const dados = await brasilApi.get<unknown>("/banks/v1"); return { content: [{ type: "text", text: JSON.stringify(dados, null, 2) }], }; } catch (err) { return { content: [ { type: "text", text: traduzirErroBrasilApi(err, { // Não há "404" semântico pra lista — se a API errar, todos // caem no mesmo balde de "indisponível". notFound: "Lista de bancos não disponível no momento.", contextoErro: "Erro ao listar bancos", }), }, ], isError: true, }; } } - src/index.ts:108-115 (registration)Registration of the listar_bancos tool on the MCP server via server.registerTool().
server.registerTool( listarBancosTool.name, { description: listarBancosTool.description, inputSchema: listarBancosSchema.shape, }, wrapHandler(listarBancosTool.name, listarBancosHandler), ); - src/utils/errors.ts:23-49 (helper)Error translation utility used by the handler to produce user-friendly error messages.
export function traduzirErroBrasilApi( err: unknown, mapa: MapeamentoErro, ): string { const ctx = mapa.contextoErro ?? "Erro ao consultar dados"; if (err instanceof BrasilApiError) { if (err.status === 404) return mapa.notFound; if (err.status === 400) { return `${ctx}: dados inválidos enviados ao serviço.`; } if (err.status === 429) { return `${ctx}: limite de requisições temporariamente atingido. Tente novamente em alguns segundos.`; } if (err.status >= 500) { return `${ctx}: serviço temporariamente indisponível. Tente novamente em alguns instantes.`; } // status === 0 é o sinal que usamos no cliente pra erro de rede / abort. if (err.status === 0) { return `${ctx}: falha de rede ao alcançar o serviço.`; } return `${ctx}: o serviço retornou erro inesperado (${err.status}).`; } const msg = err instanceof Error ? err.message : String(err); return `${ctx}: ${msg}`; } - src/clients/brasilapi.ts:172-175 (helper)HTTP client's get method used by the handler to call the BrasilAPI /banks/v1 endpoint.
export const brasilApi = { get<T>(path: string, opts: GetOptions = {}): Promise<T> { return getInterno<T>(path, opts); },