MCP Server

Node.js server implementing the Model Context Protocol (MCP) for Efí Bank API operations.

MCP Demonstration

Features

• Immediate Pix payment management
• Pix payments and transfers
• Pix refund operations
• Webhooks configuration
• Account balance and settings
• EVP (Random Keys) management
• MED (Special Return Mechanism) handling

Installation

To install MCP, use one of the options below:

Installation via NPX

$ npx mcp-server-efi

Installation 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

Access our repository on Github at Efí to view the source code.

Configuration

The server requires the following environment variables:

• sandbox: Set to "false" for production or "true" for sandbox environment
• client-id: Your Efí Bank application Client ID
• client-secret: Your Efí Bank application Client Secret
• certificate: Your Efí Bank certificate in Base64 format
• validate-mtls: Set to "true" to validate mTLS in webhooks (optional, default is true)

API

Pix Payments Immediate Charges

• pix_create_immediate_charge
• Create an immediate Pix charge without specifying a txid
• Generates a charge with expiration time, amount, Pix key, and optional debtor information

• pix_create_charge
• Create an immediate Pix charge with a specific txid
• Input: txid, charge details (amount, Pix key, debtor info, etc.)

• pix_update_charge
• Update existing charge by txid
• Modify expiration, debtor info, amount, or additional information

• pix_detail_charge
• Get charge details by txid
• Returns complete charge information including status and payment details

• pix_list_charges
• List charges with filter options
• Filter by date range, CPF/CNPJ, status, and pagination

Pix Payments and Transfers

• pix_send
• Send Pix payment to a Pix key or bank account
• Supports Pix key or bank account details as destination

• pix_send_detail
• Get details of Pix sent by e2eId
• Returns complete transaction information

• pix_send_list
• List sent Pix transactions with filter options
• Filter by date range, status, and presence of return

• pix_qr_code_pay
• Pay with Pix QR Code via API
• Process QR Code payments with payer information

Pix Management

• pix_detail_received
• Get details of Pix received by e2eId
• Returns transaction and return information

• pix_received_list
• List received Pix transactions
• Filter by date, txid, CPF/CNPJ with pagination support

• pix_devolution
• Create Pix return (refund)
• Input: e2eId, return ID and value

• pix_detail_devolution
• Get return details by e2eId and return ID

Webhooks

• pix_config_webhook
• Configure webhook URL for Pix notifications
• Set webhook endpoint for transaction notifications

• pix_detail_webhook
• Get webhook configuration details by Pix key

• pix_list_webhook
• List all configured webhooks

• pix_delete_webhook
• Delete webhook configuration by key Pix

• pix_resend_webhook
• Resend webhook notifications for specific transactions

Account Management

• get_account_balance
• Retrieve the current account balance
• Returns information about available funds

• update_account_config
• Update the account’s PIX settings
• Configure PIX key definitions, restrictions, and webhook preferences

• list_account_config
• List the current account settings
• Returns all PIX and account configuration details

EVP Management (Random Keys)

• pix_create_evp
• Create new random PIX key (EVP)
• Generates random key for PIX transactions

• pix_list_evp
• List all registered EVP keys

• pix_delete_evp
• Delete specific EVP key

MED

• med_list
• List open MED infractions against the account
• Filter by date range with pagination

Additional Features

• pix_get_receipt
• Obtain transaction receipt (PDF format)
• Generate receipt by e2eId, txid or rtrId

Using Claude Desktop

Add the following configuration to the file 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"
      ]
    }
  }
}

Using Docker on 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"
      ]
    }
  }
}

Using with VS Code

For manual installation, add the following to your VS Code settings or .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

Local Development

npm install
npm run build
npm start

Build Docker

docker build -t mcp-server-efi .

Security Notes

• Always use production credentials (sandbox=false) for real transactions
• Keep your certificates and credentials secure
• Enable mTLS validation (validate-mtls=true) for webhook security
• All API calls are authenticated using Efí Pay's OAuth 2.0 implementation