HODLXXI Read-Only

Official26 tools

by hodlxxi · Python

Public read-only MCP server for HODLXXI agent identity, trust, receipts, and verification.

io.github.hodlxxi/hodlxxi-readonly (MCP)

This public, read-only Model Context Protocol (MCP) server exposes 26 allowlisted, machine-readable “trust surfaces” for the HODLXXI agent identity, trust, receipts, and verification. It includes both a standalone FastMCP package and a remote Streamable HTTP endpoint for compatible MCP hosts.

🛠️ Key Features

Public remote MCP server
Read-only access (no API key or OAuth flow required)
26 allowlisted tools (toolCount: 26)
Machine-readable discovery endpoints provided

🚀 Use Cases

Initialize an MCP session from any MCP host that supports remote servers
Retrieve HODLXXI machine-readable identity, trust, receipts, and verification data
Use standard MCP discovery metadata for client compatibility

⚡ Developer Benefits

Simple remote configuration via a single Streamable HTTP endpoint
Standard discovery URLs for client initialization and capability discovery

⚠️ Limitations

Read-only: designed for public, non-modifying access only
The tool surface is limited to the “exactly 26” allowlisted items described

Captured live from the server via tools/list.

hodlxxi_get_agent_identity

Return the canonical public agent identity document, including capabilities, pricing, endpoints, skills, messaging metadata, and trust-model declarations.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_operator_continuity

Return the public operator-continuity statement, operator and agent public keys, covenant status, rotation policy, and verification references.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_api_catalog

Return the public RFC-style API linkset catalog with service descriptions, documentation links, and status links.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_agent_skills_index

Return the Agent Skills discovery index with skill names, descriptions, URLs, types, and SHA-256 digests.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_mcp_server_card

Return the live MCP discovery server card for https://hodlxxi.com/agent/mcp, which nginx routes to the separate read-only sidecar rather than the Flask monolith.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_nostr_dm_policy

Return public NIP-17/NIP-59 messaging policy metadata, including intake status, custody limitations, accepted kind, and size ceiling.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_openid_configuration

Return OpenID Connect discovery metadata: issuer, authorization and token endpoints, JWKS URI, grants, scopes, PKCE, and signing algorithms.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_oauth_authorization_server

Return OAuth authorization-server metadata, including the HODLXXI agent_auth discovery block and disabled registration endpoint references.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_oauth_protected_resource

Return OAuth protected-resource metadata, including resource issuer, authorization servers, JWKS URI, scopes, and bearer method.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_jwks

Return the public RSA JSON Web Key Set used to verify HODLXXI-issued JWT signatures. No private JWK fields are exposed.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_agent_discovery

Return the signed Agent Protocol discovery document with public endpoint links, trust surfaces, timestamp, and agent signature.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_capabilities

Return the signed capabilities document with job schemas, pricing, limits, endpoint registry, public skills, and messaging metadata.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_capabilities_schema

Return the JSON Schema published for the signed HODLXXI capabilities document.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_skills

Return the checked-in public skill catalog with metadata, repository paths, and installation URLs.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_marketplace_listing

Return the normalized marketplace listing with discovery links, job types, pricing, skills, reputation snapshot, chain health, and trust model.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_reputation

Return aggregate public operating history, evidenced job counts, attestation count, trust and confidence averages, pattern distribution, and rolling trust trend.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_attestations

Return paginated signed receipt attestations. limit must be 1-100 and offset must be non-negative.

Parameters2

limit	integer	optional
offset	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 20,
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "type": "integer"
    }
  },
  "additionalProperties": false
}

hodlxxi_get_trust_events

Return the paginated public trust-event chain with hashes, receipt linkage, timestamps, public key, and signatures.

Parameters2

limit	integer	optional
offset	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 20,
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "type": "integer"
    }
  },
  "additionalProperties": false
}

hodlxxi_get_nostr_announcement

Return the signed Nostr announcement template, advertised NIP-89/NIP-90 kinds, discovery links, and explicit non-goals.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_chain_health

Return attestation-chain continuity status, event count, latest event hashes, and latest timestamp when available.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_covenant_countdown

Return the machine-readable covenant countdown with chain height, spend paths, estimated unlocks, funding status, and conservative trust interpretation.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

hodlxxi_get_trust_summary

Return the compact trust summary for a validated public agent identifier.

Parameters1

agent_id

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "default": "hodlxxi-herald-01",
      "type": "string"
    }
  },
  "additionalProperties": false
}

hodlxxi_get_covenant

Return a declared covenant artifact by validated covenant identifier, including descriptor, policy, funding status, public keys, and non-claims.

Parameters1

covenant_id

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "covenant_id": {
      "default": "hodlxxi-herald-covenant-v1",
      "type": "string"
    }
  },
  "additionalProperties": false
}

hodlxxi_get_report

Return a public machine-readable trust or readiness report by validated report identifier, including its canonical SHA-256 field when present.

Parameters1

report_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string"
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false
}

hodlxxi_verify_receipt

Verify a previously issued receipt by job identifier and return verification status, validity, attestation, signed receipt, event hash, and QR pointer non-claims. This does not poll /agent/jobs and cannot mint a receipt.

Parameters1

job_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string"
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}

hodlxxi_get_receipt

Return a previously issued signed receipt by job identifier. Optional requester-proof fields depend on the historical receipt.

Parameters1

job_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string"
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}

packages/hodlxxi_mcp/README.md3 KBView on GitHub

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:

text

https://hodlxxi.com/agent/mcp

No API key or OAuth flow is required. The server is public and read-only.

Machine-readable discovery:

text

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_discovery
hodlxxi_get_capabilities
hodlxxi_get_chain_health
hodlxxi_get_reputation
hodlxxi_get_attestations
hodlxxi_get_operator_continuity
hodlxxi_get_receipt
hodlxxi_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:

text

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

bash

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"
pytest -q

Run over stdio

bash

hodlxxi-mcp

Equivalent:

bash

python -m hodlxxi_mcp

For local client configuration, point the MCP host at the virtual-environment executable and use stdio transport.

Run the sidecar over localhost Streamable HTTP

bash

hodlxxi-mcp-http

The sidecar endpoint is fixed at:

text

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.

Install

Tools (26)

hodlxxi_get_agent_identityhodlxxi_get_operator_continuityhodlxxi_get_api_cataloghodlxxi_get_agent_skills_indexhodlxxi_get_mcp_server_cardhodlxxi_get_nostr_dm_policyhodlxxi_get_openid_configurationhodlxxi_get_oauth_authorization_server

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://hodlxxi.com/agent/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "hodlxxi-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://hodlxxi.com/agent/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.hodlxxi/hodlxxi-readonly (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

hodlxxi_get_agent_identity

hodlxxi_get_operator_continuity

hodlxxi_get_api_catalog

hodlxxi_get_agent_skills_index

hodlxxi_get_mcp_server_card

hodlxxi_get_nostr_dm_policy

hodlxxi_get_openid_configuration

hodlxxi_get_oauth_authorization_server

hodlxxi_get_oauth_protected_resource

hodlxxi_get_jwks

hodlxxi_get_agent_discovery

hodlxxi_get_capabilities

hodlxxi_get_capabilities_schema

hodlxxi_get_skills

hodlxxi_get_marketplace_listing

hodlxxi_get_reputation

hodlxxi_get_attestations

hodlxxi_get_trust_events

hodlxxi_get_nostr_announcement

hodlxxi_get_chain_health

hodlxxi_get_covenant_countdown

hodlxxi_get_trust_summary

hodlxxi_get_covenant

hodlxxi_get_report

hodlxxi_verify_receipt

hodlxxi_get_receipt

HODLXXI Read-Only MCP

Public remote server

Security boundary

Independent validation

Development

Run over stdio

Run the sidecar over localhost Streamable HTTP

Install

Remote endpoint

Related servers