{
  "markdown": "# @xrpl-utilities/mcp\n\n[Model Context Protocol](https://modelcontextprotocol.io) server for the\nXRPL-Utilities™ portfolio. Exposes the read endpoints of all six\nservices as MCP tools so AI agents can discover and use them, either\nlocally via stdio (Claude Desktop, MCP Inspector, etc.) or remotely\nvia the hosted endpoint at `mcp.xrpl-utilities.io`.\n\n## Services covered\n\n| Service       | What it does                                            | Tools |\n|---------------|---------------------------------------------------------|-------|\n| **XR-Sentinel**  | XRPL wallet activity-pattern classifier (0-100 score, 35-signal catalog including account-genesis chain + provenance flags + AI narrative) | `xrpl_sentinel_scan`, `xrpl_sentinel_scan_history` |\n| **XR-Pulse**     | Normalized XRPL signal feed: public-source news, on-chain whale activity, XLS-70/80/81 lifecycle, RWA mint/burn flow, AMM-of-RWA pool snapshots. Also streamable live via `POST /stream/purchase` + WebSocket (1h/6h/24h tiers) directly on the backend; MCP exposes the snapshot endpoints here. | `xrpl_pulse_recent_events`, `xrpl_pulse_events_by_address`, `xrpl_pulse_stream_purchase` |\n| **XR-Telemetry** | XRPL macro snapshot: supply, liquidity, AMM, Active Float, Burst Math utility floor | `xrpl_telemetry_snapshot`, `xrpl_telemetry_get_quote`, `xrpl_telemetry_get_status`, `xrpl_telemetry_get_results` |\n| **XR-Trust**     | Directory + drill-down for XRPL permissioned-asset stack (XLS-70/80/81 + XLS-40 DID) | `xrpl_trust_list_domains`, `xrpl_trust_get_domain`, `xrpl_trust_credential_issuers`, `xrpl_trust_recent_events` |\n| **XR-Vault**     | Real-world asset tracker for XRPL: per-issuer mint/burn flow, daily circulating snapshots, AMM-of-RWA pool exposure across tokenized treasuries, stablecoins, commercial paper, MMFs, and energy commodities | `xrpl_vault_scan` |\n| **XR-Flows**     | ETF AUM vs XRPL exchange-flow correlation across every US-listed XRP-exposure ETF (spot + indirect-basket tiers), including SEC EDGAR filing list and launch-window flow analysis | `xrpl_flows_correlation`, `xrpl_flows_launch_impact`, `xrpl_flows_scan` |\n\n17 tools total, all read-only. Every paid call is settled via x402 v2\non the XRPL mainnet through the t54 facilitator.\n\n## Auth model\n\nThe MCP server is a **stateless passthrough proxy**. It does not hold\nwallets, manage user accounts, or subsidize calls.\n\nFor paid tools (every endpoint at $0.10 USD), the caller supplies a\n`payment_signature` argument: a base64-JSON-encoded x402 v2 payment\nheader signing an XRPL Payment that matches one of the requirements\nreturned by an unauthenticated probe. The server forwards it as the\n`PAYMENT-SIGNATURE` header on the underlying call.\n\nIf you don't supply `payment_signature`, the underlying service\nreturns its real `402 Payment Required` challenge listing three\npayment options: XRP and RLUSD on XRPL via the t54 facilitator, or\nUSDC on Base mainnet via the Coinbase x402 facilitator. The MCP\nserver passes that back to the LLM as a structured error so it can\nsign and retry against whichever rail its wallet supports.\n\nOperators can set `MCP_BYPASS_KEY` on the server to enable an opt-in\nbypass for friendlies / demos. The caller passes the matching key as\n`_bypass_key` in the tool args.\n\nThe hosted endpoint budgets failed `_bypass_key` attempts per caller\nseparately from, and far more tightly than, ordinary requests: a 60\nrequests-per-minute cap is a fair-use limit, not an access control on a\nsecret. The budget is spent per guess, not per HTTP request, so a batched\nJSON-RPC body cannot outrun it, and only requests that actually carry a\n`_bypass_key` are held off once it is exhausted - `tools/list`, free tools\nand paid x402 calls keep working. Batches are capped at 20 messages. Use a key of at least 32 random bytes, and scope or rotate it\nper service rather than sharing one portfolio-wide key. Bucket keying\ndepends on `TRUST_PROXY_HOPS` matching the real number of proxies in\nfront of the container - see `.env.example`.\n\n### H-Seal receipt co-signing (optional)\n\nSet `PROVIDER_IDENTITY` (our CAIP-10, e.g. `xrpl:0:r...`) and\n`PROVIDER_KEY_RAW` (32-byte ed25519 seed, hex) on the server to have every\ntool response co-signed with an [H-Seal](https://h-seal.xr-utilities.com)\nprovider attestation. The attestation rides on the tool result's\n`_meta.hSeal`, so a caller can anchor a tamper-evident, independently\nverifiable on-chain receipt of the interaction. When either var is unset the\nfeature is inert and responses are unchanged. Never hardcode the key — env\nonly.\n\nWhen a backend co-signs its own output, the MCP also builds a 2-party\nreceipt (`_meta.hSealReceipt`). That signs with the operator key, so set\n`HSEAL_ALLOWED_PROVIDERS` to the CAIP-10 identities of the XR-* backends\nyou are willing to vouch for. Without it any provider that proves it holds\nthe key for the identity it names is accepted. The `responseHash` is always\nrecomputed from the delivered body; `requestHash` stays provider-asserted\n(the backends hash a synthetic request object the MCP cannot reproduce) and\nthe result says so via `requestHashBasis`. See `src/hSeal.ts` and the ops runbook\n[`docs/hseal-provider.md`](docs/hseal-provider.md) (current identity, the\ned25519 curve gotcha, and how to rotate/recover the key).\n\n## Use it\n\n### Locally via Claude Desktop (stdio)\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"xrpl-utilities\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@xrpl-utilities/mcp\", \"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The 17 tools should appear with the prefix\n`xrpl_`. Ask Claude to \"scan the wallet rXXX with XR-Sentinel\" or\n\"list permissioned domains on XRPL\" and the tool calls flow through.\n\n### Remotely (HTTP/SSE)\n\nPoint any MCP client at `https://mcp.xrpl-utilities.io/mcp`. Same\ntool list, same auth model.\n\n## What you need to actually pay\n\nTo avoid 402 challenges on every call, your client needs to:\n\n1. Hold a wallet on at least one of the supported rails:\n   an XRPL wallet with XRP (and optional RLUSD trustline) OR\n   an EVM wallet with USDC on Base mainnet.\n2. On each paid tool call, sign a payment matching one of the\n   `accepts` entries from a prior probe. XRPL rails take an\n   XRPL Payment; the Base rail takes an EIP-3009\n   `transferWithAuthorization`.\n3. Pass the base64-JSON-encoded envelope as `payment_signature`.\n\nReference implementations:\n[`x402-xrpl`](https://pypi.org/project/x402-xrpl/) covers the\nXRPL rails. The official [`x402`](https://pypi.org/project/x402/)\npackage (with `[evm]` extras) covers the Base USDC rail. Both are\nuseful as templates in any language.\n\n## Local dev\n\n```bash\nnpm install\nnpm run build\nnode dist/index.js --transport http --port 8080\nnpm test          # builds, then runs the node:test suite in tests/\n```\n\nPoint MCP Inspector at `http://localhost:8080/mcp` to walk through\ntool definitions interactively.\n\nSet `STRICT_VALIDATE=1` to treat a manifest that could not be read as\ndrift instead of a warning. It is off by default because Railway restarts\n`ON_FAILURE`: failing closed on boot would crash-loop the endpoint, and\ntake the other five healthy services' tools down with it, whenever one\nbackend is cold. Either way, a service whose manifest was not read logs\n`NOT CHECKED` - \"could not check\" is never reported as \"all clear\".\n\n## Releases\n\nReleases are cut by tag push. The `Release` workflow builds, validates\nthat `package.json` version matches the tag, publishes to npm with\nsigstore provenance, then mirrors the same version to the official\nMCP Registry via GitHub OIDC (no extra secrets needed).\n\n```bash\nnpm version patch       # or minor / major\ngit push --follow-tags  # pushes commit + tag, CI does the rest\n```\n\nThe published artifact appears at\n[npmjs.com/package/@xrpl-utilities/mcp](https://www.npmjs.com/package/@xrpl-utilities/mcp)\nwithin ~90 seconds. Provenance attestation is visible on the package\npage as a green check. The MCP Registry entry lives at\n[registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.XRPL-Utilities/mcp)\nunder the reverse-DNS name `io.github.XRPL-Utilities/mcp`.\n\n## License\n\nMIT. Full portfolio at [xrpl-utilities.com](https://xrpl-utilities.com).\n",
  "bytes": 8334,
  "sha": "0b18780585f36dfe39c71909bd8a40eac7f7e98f32aa3883d6e5068dc98e476b",
  "repo_slug": "xrpl-utilities/xrpl-utilities-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_xrpl_utilities_mcp_96e4174a/readme"
}