Servidor MCP Efí

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

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

NPX

npx mcp-server-efi

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

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 isso ao seu 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

Suporte

Para documentação e suporte da API do Efí Pay, visite: https://dev.efipay.com.br/