HODLXXI Read-Only MCP
Public remote MCP server and standalone FastMCP package wrapping 26 allowlisted HODLXXI machine-readable trust surfaces.
Public remote server
Use this Streamable HTTP endpoint in any MCP host that supports remote servers:
https://hodlxxi.com/agent/mcp
No API key or OAuth flow is required. The server is public and read-only.
Machine-readable discovery:
https://hodlxxi.com/.well-known/mcp.json
https://hodlxxi.com/.well-known/agent.json
https://hodlxxi.com/agent/capabilities
A compatible client can initialize a session, list exactly 26 tools, and call tools such as:
hodlxxi_get_agent_discoveryhodlxxi_get_capabilitieshodlxxi_get_chain_healthhodlxxi_get_reputationhodlxxi_get_attestationshodlxxi_get_operator_continuityhodlxxi_get_receipthodlxxi_verify_receipt
The canonical MCP Registry metadata is stored at the repository root in server.json under the name io.github.hodlxxi/hodlxxi-readonly.
Security boundary
- fixed upstream origin:
https://hodlxxi.com
- fixed endpoint enum; no generic URL tool
- GET-only access to allowlisted upstream runtime surfaces
- redirects disabled
- 10-second upstream timeout
- 2 MiB response ceiling
- JSON and
application/linkset+json only
- strict identifier and pagination validation
- no Flask imports, database access, wallet access, LND access, keys, secrets, environment reads, payment initiation, receipt creation, or write calls
- dedicated systemd sidecar; the Flask monolith does not execute MCP tools
- public nginx route proxies only to the loopback sidecar
GET /agent/jobs/<job_id> and GET /agent/readiness/self-scan are intentionally excluded because they may mutate server state.
Independent validation
The remote production path has been validated from an external macOS client and through a Claude custom connector:
external client -> HTTPS -> nginx -> loopback MCP sidecar -> public HODLXXI runtime surfaces
The validation completed MCP initialization, tools/list, and live calls to capabilities, chain health, and reputation. See docs/MCP_CLIENT_VALIDATION.md.
Development
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"
pytest -q
Run over stdio
Equivalent:
For local client configuration, point the MCP host at the virtual-environment executable and use stdio transport.
Run the sidecar over localhost Streamable HTTP
The sidecar endpoint is fixed at:
http://127.0.0.1:8765/mcp
The sidecar transport is intentionally locked to loopback, stateless JSON responses, Host/Origin protection, and the same 26 read-only tools. Public exposure is handled separately by the hardened production reverse proxy.