Pular para o conteúdo principal

Servidor MCP

Servidor Node.js implementando o Model Context Protocol (MCP) para operações das APIs do Efí Bank.


Demonstração do MCP​



Características​

  • Gestão de cobranças Pix imediatas
  • Pagamentos e transferências Pix
  • Operações de devolução Pix
  • Configuração de webhooks
  • Saldo da conta e configurações
  • Gerenciamento de EVP (Chaves Aleatórias)
  • Tratamento de MED (Mecanismo Especial de Devolução)

Instalação​

Para instalar o MCP, utilize uma das opções abaixo:

Instalação via NPX​

$ npx mcp-server-efi

Instalação via Docker​

docker run -i --rm mcp-server-efi \
  --sandbox=false \
  --client-id=seu_client_id \
  --client-secret=seu_client_secret \
  --certificate=seu_certificado_base64 \
  --validate-mtls=true

Acesse nosso repositório no Github da Efí para consultar o código-fonte.


Configuração​

O servidor requer as seguintes variáveis de ambiente:

  • sandbox: Defina como "false" para produção ou "true" para ambiente sandbox
  • client-id: Seu Client ID da aplicação do Efí Bank
  • client-secret: Seu Client Secret da aplicação do Efí Bank
  • certificate: Seu certificado do Efí Bank em formato Base64
  • validate-mtls: Defina como "true" para validar mTLS nos webhooks (opcional, padrão é true)

API​

Cobranças Pix Imediatas​

  • pix_create_immediate_charge
    • Criar cobrança Pix imediata sem especificar txid
    • Gera cobrança com tempo de expiração, valor, chave Pix e informações opcionais do devedor
  • pix_create_charge
    • Criar cobrança Pix imediata com txid específico
    • Entrada: txid, detalhes da cobrança (valor, chave Pix, info do devedor, etc.)
  • pix_update_charge
    • Atualizar cobrança existente por txid
    • Modificar expiração, info do devedor, valor ou informações adicionais
  • pix_detail_charge
    • Obter detalhes da cobrança por txid
    • Retorna informações completas da cobrança incluindo status e detalhes do pagamento
  • pix_list_charges
    • Listar cobranças com opções de filtro
    • Filtrar por intervalo de datas, CPF/CNPJ, status e paginação

Pagamentos e Transferências Pix​

  • pix_send
    • Enviar pagamento Pix para uma chave Pix ou conta bancária
    • Suporte para chave Pix ou detalhes de conta bancária como destino
  • pix_send_detail
    • Obter detalhes do Pix enviado por e2eId
    • Retorna informações completas da transação
  • pix_send_list
    • Listar transações Pix enviadas com opções de filtro
    • Filtrar por intervalo de datas, status e presença de devolução
  • pix_qr_code_pay
    • Pagar QR Code Pix via API
    • Processar pagamentos de QR Code com informações do pagador

Gestão Pix​

  • pix_detail_received
    • Obter detalhes do Pix recebido por e2eId
    • Retorna informações da transação e devolução
  • pix_received_list
    • Listar transações Pix recebidas
    • Filtrar por data, txid, CPF/CNPJ com suporte a paginação
  • pix_devolution
    • Criar devolução Pix (estorno)
    • Entrada: e2eId, ID da devolução e valor
  • pix_detail_devolution
    • Obter detalhes da devolução por e2eId e ID da devolução

Webhooks​

  • pix_config_webhook
    • Configurar URL do webhook para notificações Pix
    • Definir endpoint do webhook para notificações de transação
  • pix_detail_webhook
    • Obter detalhes da configuração do webhook por chave Pix
  • pix_list_webhook
    • Listar todos os webhooks configurados
  • pix_delete_webhook
    • Excluir configuração de webhook por chave Pix
  • pix_resend_webhook
    • Reenviar notificações de webhook para transações específicas

Gestão de Conta​

  • get_account_balance
    • Obter saldo atual da conta
    • Retorna informações de saldo disponível
  • update_account_config
    • Atualizar configurações PIX da conta
    • Configurar definições de chave PIX, restrições e preferências de webhook
  • list_account_config
    • Listar configurações atuais da conta
    • Retorna todas as configurações PIX e da conta

Gestão de EVP (Chaves Aleatórias)​

  • pix_create_evp
    • Criar nova chave PIX aleatória (EVP)
    • Gera chave aleatória para transações PIX
  • pix_list_evp
    • Listar todas as chaves EVP registradas
  • pix_delete_evp
    • Excluir chave EVP específica

MED​

  • med_list
    • Listar infrações MED abertas contra a conta
    • Filtrar por intervalo de datas com paginação

Funcionalidades Adicionais​

  • pix_get_receipt
    • Obter comprovante da transação (formato PDF)
    • Gerar comprovante por e2eId, txid ou rtrId

Uso com Claude Desktop​

Adicione a seguinte configuração ao arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-efi": {
      "command": "npx",
      "args": [
        "mcp-server-efi",
        "--sandbox=false",
        "--client-id=seu_client_id",
        "--client-secret=seu_client_secret",
        "--certificate=seu_certificado_base64",
        "--validate-mtls=true"
      ]
    }
  }
}

Uso com Docker no Claude Desktop​

{
  "mcpServers": {
    "mcp-server-efi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "mcp-server-efi",
        "--sandbox=false",
        "--client-id=seu_client_id",
        "--client-secret=seu_client_secret",
        "--certificate=seu_certificado_base64",
        "--validate-mtls=true"
      ]
    }
  }
}

Uso com VS Code​

Para instalação manual, adicione o seguinte às configurações do VS Code ou .vscode/mcp.json:

NPX​

{
  "mcp": {
    "servers": {
      "mcp-server-efi": {
        "command": "npx",
        "args": [
          "mcp-server-efi",
          "--sandbox=false",
          "--client-id=seu_client_id",
          "--client-secret=seu_client_secret",
          "--certificate=seu_certificado_base64",
          "--validate-mtls=true"
        ]
      }
    }
  }
}

Docker​

{
  "mcp": {
    "servers": {
      "mcp-server-efi": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "mcp-server-efi",
          "--sandbox=false",
          "--client-id=seu_client_id",
          "--client-secret=seu_client_secret",
          "--certificate=seu_certificado_base64",
          "--validate-mtls=true"
        ]
      }
    }
  }
}

Build​

Desenvolvimento Local​

npm install
npm run build
npm start

Build Docker​

docker build -t mcp-server-efi .

Notas de Segurança​

  • Sempre use credenciais de produção (sandbox=false) para transações reais
  • Mantenha seus certificados e credenciais seguros
  • Habilite a validação mTLS (validate-mtls=true) para segurança do webhook
  • Todas as chamadas da API são autenticadas usando a implementação OAuth 2.0 do Efí Pay
Última atualização em