Add TBNB Faucet MCP Server (Streamable HTTP)

[zzuguofa]

Description

Summary

Adds a TBNB Faucet MCP Server: a server-side Model Context Protocol (MCP) server that disburses testnet BNB (TBNB) on BSC testnet. It runs as a public HTTP service, uses Streamable HTTP transport, and exposes a single disburse_tbnb tool. Any MCP-capable agent can connect via URL (e.g. http://host:8000/mcp) to request TBNB.

What’s included

• Single tool: disburse_tbnb — send TBNB to a BSC testnet address (default 0.1, max 1.0 TBNB).
• Transport: Streamable HTTP (MCP over HTTP).
• Deployment: Public HTTP server; configurable host/port (default 0.0.0.0:8000).
• Blockchain: BSC testnet (Chain ID 97); web3 v6/v7–compatible (including ExtraDataToPOAMiddleware).
• Config: FAUCET_WALLET_PRIVATE_KEY, BSC_TESTNET_RPC_URL, SERVER_HOST, SERVER_PORT.
• Tests: Unit tests with mocked Web3; no live RPC required.

---

How users can connect their agents

Mermaid diagrams below show how agents integrate with the TBNB Faucet MCP Server.

1. Public HTTP faucet – multiple agents via URL

The server runs as an HTTP service. Any agent with the URL connects over Streamable HTTP; no local server process.

flowchart TB
    subgraph "Faucet operator"
        Server["TBNB Faucet MCP Server<br/>Streamable HTTP :8000/mcp"]
    end

    subgraph "Agent A"
        AgentA["AI Agent A"]
        ClientA["MCP Client<br/>url: http://host:8000/mcp"]
    end

    subgraph "Agent B"
        AgentB["AI Agent B"]
        ClientB["MCP Client<br/>url: http://host:8000/mcp"]
    end

    BSC[(BSC Testnet RPC)]

    AgentA -->|"tools"| ClientA
    AgentB -->|"tools"| ClientB
    ClientA -->|"HTTP / MCP"| Server
    ClientB -->|"HTTP / MCP"| Server
    Server -->|"Web3"| BSC

    style Server fill:#e8f5e9
    style AgentA fill:#f3e5f5
    style AgentB fill:#f3e5f5

Loading

2. End-to-end flow: agent requests TBNB

Sequence from user request to on-chain disbursement.

sequenceDiagram
    participant User
    participant Agent
    participant MCP as MCP Client
    participant Faucet as TBNB Faucet MCP Server
    participant BSC as BSC Testnet

    User->>Agent: "Send 0.1 TBNB to 0x..."
    Agent->>MCP: list_tools()
    MCP->>Faucet: GET/POST /mcp (MCP protocol)
    Faucet-->>MCP: [disburse_tbnb]
    MCP-->>Agent: tools

    Agent->>MCP: call_tool("disburse_tbnb", {recipient_address, amount})
    MCP->>Faucet: POST /mcp (MCP call_tool)
    Faucet->>BSC: Sign & send transaction
    BSC-->>Faucet: Transaction receipt
    Faucet-->>MCP: {success, transaction_hash, explorer_url, ...}
    MCP-->>Agent: result
    Agent-->>User: "Sent 0.1 TBNB. Tx: 0x..."

Loading

3. Connection options for agents

Ways to connect an agent to the TBNB Faucet MCP Server.

flowchart LR
    Faucet["TBNB Faucet MCP Server<br/>Streamable HTTP"]

    Faucet --> C1["Claude Desktop<br/>mcpServers.url"]
    Faucet --> C2["Cursor<br/>MCP url config"]
    Faucet --> C3["MCP Inspector<br/>Connect to URL"]
    Faucet --> C4["Python MCP client<br/>sse_client(url)"]
    Faucet --> C5["Custom MCP client<br/>Streamable HTTP"]

    style Faucet fill:#e8f5e9

Loading

4. Architecture overview

flowchart TB
    subgraph "Users' machines"
        A1["Agent (e.g. Claude, Cursor)"]
        A2["MCP Client"]
    end

    subgraph "Your infrastructure"
        S["TBNB Faucet MCP Server<br/>FastMCP + Streamable HTTP"]
    end

    BSC[(BSC Testnet)]

    A1 -->|"use tools"| A2
    A2 -->|"HTTP / MCP<br/>http://host:8000/mcp"| S
    S -->|"Web3"| BSC

    style S fill:#e8f5e9

Loading

---

Configuration

Variable	Description	Default
FAUCET_WALLET_PRIVATE_KEY	Faucet wallet private key	required
BSC_TESTNET_RPC_URL	BSC testnet RPC	https://data-seed-prebsc-1-s1.binance.org:8545/
SERVER_HOST	Bind address	0.0.0.0
SERVER_PORT	Listen port	8000

MCP endpoint: http://<host>:<port>/mcp

Running

pip install -r requirements.txt
export FAUCET_WALLET_PRIVATE_KEY="0x..."
python tbnb_faucet_server.py

Server listens on http://0.0.0.0:8000; MCP at http://localhost:8000/mcp.

Testing

pytest test_tbnb_faucet_server.py -v

All tests use mocked Web3 and run offline.

---

Type of change

• New feature (non-breaking change that adds functionality)
• This change requires a documentation update

How has this been tested?

• Unit tests: pytest test_tbnb_faucet_server.py -v (all pass).
• Manual runs with MCP Inspector connecting to http://localhost:8000/mcp.
• Verified Streamable HTTP handling and disburse_tbnb behavior.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[vivixu-cmd]

Congratulations! You have received a Cookbook reward. Please reply with your BSC wallet address.Thanks

[zzuguofa]

0xCf4376AAf65854d8c32355C599A31DDA8Deed7cc

Glad to be of assistance.

[jdmatiga1-ux]

0x2160010d8d64bb44E347404C3C2AD488C4F0fcC4

…

On Tue, Jan 27, 2026, 2:39 PM zzuguofa ***@***.***> wrote: *zzuguofa* left a comment (bnb-chain/example-hub#194) <#194 (comment)> 0xCf4376AAf65854d8c32355C599A31DDA8Deed7cc Glad to be of assistance. — Reply to this email directly, view it on GitHub <#194 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BVX4NJ36IMG2L35ZR2355QT4I4BYVAVCNFSM6AAAAACSXTUUPOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQMBTGM4DMNJYGU> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>