MCP Server

Query the DERO blockchain — and the canonical DERO documentation — from AI assistants. No middlemen, no API keys, no surveillance.

The DERO MCP server implements the Model Context Protocol (opens in a new tab), the open standard for connecting AI models to external tools. Run it as a local stdio process for Claude Desktop / Cursor / OpenCode, or as a streamable-HTTP server behind your own domain (e.g. mcp.derod.org) for ChatGPT Custom Connectors, Cursor hosted mode, and any agent that needs a remote URL instead of a subprocess.

At a Glance

Latest version, install commands, and per-release notes: see npm (opens in a new tab) and the GitHub releases (opens in a new tab).

Tool identifiers, schemas, and behavior are semantically stable — once a tool ships, its name, args, and response shape are preserved across minor and patch releases. Breaking changes only land in majors and are flagged in the release notes.

Why This Matters

AI assistants are powerful research and dev tools, but most blockchain integrations route through centralized APIs that log your queries. This server runs on your machine, talks to your daemon (or a public one you choose), and communicates with your AI over local stdio. No accounts, no analytics, no tracking — just code you can audit. The bundled DERO documentation index (147 pages across derod, tela, hologram, and deropay) is shipped inside the package, so the AI can quote primary sources offline without a single network round-trip beyond the daemon you pointed it at.

Install

npm install -g dero-mcp-server

Requires Node.js 20+. Source code: github.com/DHEBP/dero-mcp-server (opens in a new tab) · npm: dero-mcp-server (opens in a new tab)

Run Your Own Node

When DERO_DAEMON_URL is unset the server is local-first: it uses a local daemon at 127.0.0.1:10102 if one answers, and only falls back to a third-party public RPC when none is found. For real privacy, run your own daemon:

./derod --rpc-bind=127.0.0.1:10102

Then point the MCP server at it via DERO_DAEMON_URL (see below).

Configure Your MCP Client

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "dero": {
      "command": "dero-mcp-server",
      "env": {
        "DERO_DAEMON_URL": "http://127.0.0.1:10102"
      }
    }
  }
}

Omit env to use the default public RPC.

Cursor

Settings → MCP → Add Server

• Command: dero-mcp-server
• Environment: DERO_DAEMON_URL=http://127.0.0.1:10102 (optional)

OpenCode

opencode mcp add dero -- dero-mcp-server

Or with a local node:

opencode mcp add dero -e DERO_DAEMON_URL=http://127.0.0.1:10102 -- dero-mcp-server

Continue · Cline · Zed · others

Any MCP-compatible client works. The server uses stdio transport:

command: dero-mcp-server
env:     DERO_DAEMON_URL=http://127.0.0.1:10102  (optional)

Consult your client's MCP documentation for the exact config format.

Inspect interactively

To explore the full surface without committing to a client config, use the official MCP Inspector:

npx @modelcontextprotocol/inspector dero-mcp-server

It opens a local web UI that lists every tool with its schema and annotations, lets you invoke any tool with form-filled args, and shows the structured response including _meta.error blocks.

HTTP Mode (Self-Hosted)

For clients that can't launch a local subprocess — ChatGPT Custom Connectors, Cursor hosted mode, n8n / Zapier integrations — run the server in streamable-HTTP mode and put it behind your own domain:

DERO_MCP_AUTH_TOKEN=$(openssl rand -base64 48) \
  dero-mcp-server --http
# [dero-mcp-server] HTTP listening on 127.0.0.1:8787 (POST /mcp · GET /health)

For a turnkey deploy with Caddy + auto-TLS + Docker Compose, see the deploy/ (opens in a new tab) reference in the repo. Anyone can fork and run their own mcp.derod.org-style instance.

The stdio transport and the HTTP transport share the same buildServer() factory, so the tool surface, response shapes, and error codes are identical across both.

What You Can Ask

Once connected, talk to your AI naturally — it will pick the right composite or primitive based on your intent:

• "Is the DERO daemon healthy and synced?" → diagnose_chain_health
• "What does the contract at SCID […] do?" → explain_smart_contract
• "Look up transaction [txid] and tell me what it is." → trace_transaction_with_context
• "Which DERO docs page should I read to deploy a TELA app?" → recommend_docs_path
• "Estimate the gas cost to deploy this DVM contract." → estimate_deploy_cost
• "Verify the claim that DERO's total supply has been correctly minted at the current tip." → audit_chain_artifact_claim
• "Forge a payload proof showing any amount — to see why 'Verified ✓' on an explorer proves nothing." → dero_forge_demo_proof
• "What's the SCID for vault.tela?" → dero_durl_to_scid
• "What TELA apps exist on DERO? Show me a few." → dero_tela_list_apps
• "Inspect the TELA app at SCID […] — what is it and what files does it have?" → tela_inspect
• "Show me the actual HTML of that app's index.html." → tela_get_doc_content
• "What's the current block height?" → dero_get_info / dero_get_height
• "Show me the source code for contract [SCID]." → dero_get_sc
• "Resolve the name dero to a wallet address." → dero_name_to_address
• "Decode this bech32 proof string and tell me what it represents." → dero_decode_proof_string

Composite Tools

Each composite replaces a multi-step primitive chain with a single call, returns a plain-language narrative summary, and stitches the most relevant bundled docs pages as related_docs citations.

Each composite is fully documented in docs/composites.md (opens in a new tab) (design contract, accepted/rejected designs, failure modes), and every composite ships with a green flow test in CI that runs against a live public daemon.

Primitive Tools

The 21 primitives map 1:1 onto daemon RPC methods (18) plus the bundled docs index (3). Use them when a composite is unavailable or you need raw data.

Daemon RPC

Bundled docs index

Resources and Prompts

Beyond tools, the server exposes 4 resources and 5 prompts so MCP-aware clients can surface them in their UI:

Resources

Prompts

Structured Errors

Every tool wraps failures in a structured _meta.error block so agents can react programmatically instead of parsing error strings:

Every error code carries a hint string with actionable next steps so the agent can recover or explain the failure cleanly to the user.

Read-Only by Design

Every one of the 32 tools carries the MCP read-only annotation block:

{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false
}

This lets MCP hosts safely auto-approve any tool call from this server without prompting on every read. The server cannot:

• Send transactions
• Transfer funds
• Invoke smart contracts (only estimate deploy cost via estimate_deploy_cost — nothing is submitted to chain)
• Submit blocks
• Hold wallet keys or talk to wallet RPC

Wallet RPC methods (transfer, scinvoke, DERO.SendRawTransaction, DERO.SubmitBlock) are explicitly excluded. The full read-only posture, the six AND-gated conditions that would be required to expand the boundary, and the rationale for each are documented in docs/decision-boundary.md (opens in a new tab).

If you need write capabilities in the future, they will be gated behind explicit flags and a separate wallet URL and a distinct annotation block (readOnlyHint: false) and documented escalation — never enabled by default.

Environment

Verify, Don't Trust

• Source code on GitHub (opens in a new tab) — composite design contract in docs/composites.md, read-only posture in docs/decision-boundary.md, agent-ready evidence in docs/mcp-agent-ready-evidence.md
• Bundled with the npm package: SKILL.md is the per-tool agent operating manual (composite-first rule, port reference, structured error contract, workflow recipes, safety rules); POSITIONING.md covers who this server is for vs. who it isn't, with a comparison vs. ACP / Stripe / Crossmint / Skyfire
• Agent-discovery surfaces at /.well-known/agent-card.json (A2A v0.2-draft descriptor for the broader agent ecosystem) and /.well-known/mcp-server-card.json (MCP-specific descriptor)
• Package on npm (opens in a new tab)
• Listed in the official MCP registry (opens in a new tab) as io.github.DHEBP/dero-mcp-server
• CI runs full smoke probes, composite flow tests, primitive flow tests, description / citation drift guards, and HTTP transport smoke tests on every push
• MIT licensed — fork it, audit it, improve it

See Also

• DERO Daemon RPC API — full RPC reference for the methods the primitives wrap
• Running a DERO Node — set up your own daemon
• Smart Contract Fundamentals — DVM concepts the composites cite
• XSWD — browser wallet integration (for write flows the MCP server intentionally excludes)
• SKILL.md (opens in a new tab) — agent operating manual served at the docs origin (mirror of the npm-bundled file)
• agents.md (opens in a new tab) — human-and-LLM-readable operating runbook for the whole DERO docs surface
• llms.txt (opens in a new tab) — curated agent map of the DERO docs corpus