BaaS MCP (Model Context Protocol)

Introdução

O BaaS MCP é uma interface alternativa ao uso de APIs REST, permitindo que Agentes de IA (como ChatGPT, Gemini, Claude e outros) interajam diretamente com o Banking as a Service da Aarin por meio do protocolo MCP (Model Context Protocol).

O protocolo MCP permite que agentes de IA tenham acesso a ferramentas, que executam ações em sistemas externos ao modelo (como criar boletos, consultar extratos, gerar cobranças Pix) a partir de prompts escritos em linguagem natural. Isso reduz o tempo de integração e simplifica o onboarding de parceiros.

Pré-requisitos

Para utilizar o BaaS MCP, é necessário ter:

Credenciais de acesso ao BaaS da Aarin e certificado para conexão mTLS;
Um agente de IA com suporte ao protocolo MCP;
Conhecimento básico de como criar prompts estruturados.
Node.js instalado com a versão 22 ou superior.

Como configurar o MCP Server

Antes de iniciar a configuração, é importante entender que o MCP Server é o componente que conecta o agente de IA ao BaaS da Aarin e é executado na infraestrutura do cliente.

Abaixo estão os passos para configurar o MCP Server e estabelecer essa conexão de forma segura e funcional.

Dados necessários:

Pacote NPM do MCP Server: @aarintech/baas-mcp
Variáveis de ambiente:
    BAAS_USERNAME: Credencial de acesso ao BaaS
    BAAS_PASSWORD: Credencial de acesso ao BaaS
    BAAS_API_URL: Host que define o ambiente do BaaS, podendo ser https://baas-sandbox.aarin.dev (Ambiente de homologação) ou https://baas.aarin.com.br (Ambiente produtivo)
    MTLS_PUBLIC_CERT: Certificado assinado para validação mTLS
    MTLS_PRIVATE_KEY: Chave privada para validação mTLS
    LOG_LEVEL: Variável opcional para configurar log do MCP Server

Primeiramente instale o pacote do Bass MCP:

  npm install -g @aarintech/baas-mcp

Em seguida configure o acesso ao Baas MCP como no exemplo abaixo:

{
    "mcpServers": {
        "aarinBaaS": {
            "command": "npx",
            "type": "stdio",
            "args": [
                "-y",
                "@aarintech/baas-mcp"
            ],
            "env": {
                "BAAS_USERNAME": "your_username",
                "BAAS_PASSWORD": "your_password",
                "BAAS_API_URL": "https://baas-sandbox.aarin.dev",
                "MTLS_PUBLIC_CERT": "-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----",
                "MTLS_PRIVATE_KEY": "-----BEGIN PRIVATE KEY----- -----END PRIVATE KEY-----",
                "LOG_LEVEL": "debug"
            }
        }
    }
}

Ferramentas Disponíveis (MCP Tools)

Após conectar um agente ao BaaS MCP, é possível explorar as ferramentas que permitem criar, consultar e gerenciar informações financeiras no ecossistema da Aarin. Tudo isso via linguagem natural.

Essas ferramentas funcionam de forma integrada: com um único prompt, o agente pode consultar uma conta, criar uma cobrança Pix e acompanhar o status dessa cobrança.

O verdadeiro poder do MCP está em combinar múltiplas ferramentas dentro de uma mesma interação.

Abaixo está uma listagem das funcionalidades habilitadas para uso nesse momento.

Contas

| Tool MCP | Descrição | Exemplos de Prompt para uso | | ---------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | ConsultarConta | Recupera dados cadastrais e informações básicas de uma conta. | • “Mostre os dados cadastrais da conta cd8ed314-dcf0-4eb1-b9d2-b515078dad68” • “Quais informações estão registradas na conta do CPF 123.456.789-00?” | | ConsultarSaldo | Exibe o saldo atual disponível de uma conta. | • “Qual é o saldo da conta cd8ed314-dcf0-4eb1-b9d2-b515078dad68?” • “Quanto tem disponível na conta 1234?” | | ConsultarExtrato | Lista as últimas transações realizadas em uma conta, com filtro opcional por número de dias. | • “Mostre as movimentações dos últimos 7 dias da conta 9876” • “Liste as transações do mês passado da conta de CPF 123.456.789-00” |

Pix

| Tool MCP | Descrição | Exemplo de Prompt | | -------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ConsultarChaveDICT | Busca informações de uma chave Pix (CPF, CNPJ, e-mail ou telefone) diretamente no DICT. | • “Verifique a quem pertence a chave Pix 123.456.789-00” • “Qual é o tipo da chave Pix [email protected]?” | | CriarCobrancaPix | Cria uma cobrança Pix com valor, vencimento e mensagem personalizados, retornando o QR Code. | • “Crie uma cobrança Pix de R$150,00 com vencimento em 5 dias para o CPF 123.456.789-00” • “Gere um QR Code Pix de R$200,00 com a mensagem ‘mensalidade novembro’” | | ConsultarCobrancaPix | Retorna o status atual de uma cobrança Pix (pendente, paga, vencida etc.). | • “A cobrança Pix com ID aZ9vL2kQmT5rXb1YwN8eJcHdUs foi paga?” • “Verifique o status da cobrança Pix gerada ontem” |

Boletos

| Tool MCP | Descrição | Exemplo de Prompt | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CriarBoleto | Emite um boleto bancário com valor, vencimento, pagador e mensagem definidos, retornando linha digitável e instruções de pagamento. | • “Crie um boleto de R$350,00 com vencimento em 10 dias para o CPF 123.456.789-00” • “Gere um boleto para pagamento de R$500,00 com a mensagem ‘mensalidade de novembro’” | | ConsultarBoleto | Consulta o status e os dados bancários associados a um boleto previamente criado. | • “Qual o status do boleto ID 89f7a1f0-cb3d-4f22-b7a1-9d1a2b7d5e91?”• “O boleto do CPF 123.456.789-00 já foi pago?” |

💡 Combinando ferramentas

As ferramentas MCP podem ser usadas em conjunto dentro de um mesmo prompt. Por exemplo:

• “Liste as contas com saldo acima de R$1.000,00 e crie uma cobrança Pix de 10% desse valor para cada uma;”

• “Consulte a conta do CPF 123.456.789-00 e gere um boleto de R$200,00 com vencimento para amanhã;”

• “Verifique o saldo da conta 1234, crie uma cobrança Pix e me envie o QR Code para pagamento.”

Glossário do MCP

| Termo | Definição | | ----------------- | ------------------------------------------------------------------------------------------ | | MCP | Model Context Protocol – protocolo que permite que agentes de IA interajam com APIs. | | LLM | Large Language Model – modelo de IA que interpreta linguagem natural (ex: GPT-4). | | Tool MCP | “Ferramenta” definida no protocolo MCP que executa uma ação concreta. | | Agente de IA | Interface que usa LLMs + ferramentas + base de conhecimento. | | Prompt | Comando textual dado pelo usuário para a IA executar os comandos. | | Linguagem natural | Linguagem comum humana conversacional, sem a complexidade de uma linguagem de programação. |

FAQ (Perguntas Frequentes)

Preciso saber escrever código para usar o BaaS MCP?

Não, basta ter as credenciais do Baas e conectar o agente ao MCP Server para iniciar o uso.

A LLM consegue usar dados de uma operação anterior?

Sim. O contexto da conversa é mantido, e ela consegue encadear ações com base em histórico.

O que acontece se eu encontrar algum erro quando usar o MCP?

A LLM pode tentar corrigir automaticamente, usar um caminho alternativo ou avisar que houve falha.

Estou com problemas ao configurar o MCP Server, o que eu faço?

Verifique se seu agente de IA suporta uso de ferramentas por meio de MCP, através do método de comunicação STDIO. Verifique também se as credenciais do BaaS e o certificado mTLS estão válidos.

Qual a LLM/Agente IA que devo usar?

A escolha e configuração do agente IA é de responsabilidade do cliente, mas recomendamos o uso de LLMs que tenham ao menos dois níveis de proteção de dados.