@telegraph/mcp-server

MCP server exposing Telegraph Protocol AI inference APIs as tools with automatic x402 micropayments.

Connects any MCP-compatible agent (Claude Desktop, Cursor, ElizaOS, LangChain, OpenClaw, Goose, etc.) to Telegraph's network of AI miners — weather forecasting, deepfake detection, LLM inference, AI-text detection, signal monitoring — with zero crypto code in the agent. The MCP server handles private key custody, payment signing, and transaction settlement internally.

Miners can be Bittensor subnets, hosted models, or any private API integrated via YAML. Some tool and field names still say subnet for legacy reasons — read it as "miner".

Documentation

Document	Description
Architecture	MCP protocol, tool categories, x402 auto-payment, client integrations
Troubleshooting	Common issues and solutions

Quick Start

Option A — npx (no clone, recommended once published)

TELEGRAPH_NODE_URL=http://13.237.89.59:7044 \
TELEGRAPH_ENGINE_URL=http://13.237.89.59:8080 \
TELEGRAPH_DAEMON_URL=http://13.237.89.59:8081 \
TELEGRAPH_EVM_PRIVATE_KEY=0xyour_key_here \
npx -y telegraph-protocol-mcp

Option B — from source

# 1. Clone and enter
git clone https://github.com/telegraphprotocol/telegraph-mcp
cd telegraph-mcp

# 2. Copy and edit .env
cp .env.example .env
# Edit: set TELEGRAPH_EVM_PRIVATE_KEY=0xyour_key_here

# 3. Install and build
npm install && npm run build

# 4. Run
npm start

Published to npm as telegraph-protocol-mcp and listed on the MCP Registry as io.github.telegraphprotocol/telegraph. Maintainers: see PUBLISHING.md.

Architecture

Agent (Claude / Cursor / Eliza / etc.)
       │
       │ MCP protocol (JSON-RPC over stdio)
       │
┌──────▼─────────────────────────────────────────┐
│  Telegraph MCP Server (runs locally)            │
│                                                 │
│  ┌─────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Node    │  │ Engine   │  │ Daemon        │  │
│  │ :7044   │  │ :8080    │  │ :8081         │  │
│  ├─────────┤  ├──────────┤  ├───────────────┤  │
│  │ Status  │  │ Subnets  │  │ Health        │  │
│  │ Health  │  │ Ask      │  │ Categories    │  │
│  │ Subnets │  │ Direct   │  │ Questions     │  │
│  │ Dynamic │  │          │  │               │  │
│  └─────────┘  └──────────┘  └───────────────┘  │
│                                                 │
│  X402 payment handled transparently:            │
│    request → 402 → sign EIP-3009 → retry        │
└─────────────────────────────────────────────────┘

Configuration

All via environment variables (.env file or inline):

Variable	Required	Default	Description
TELEGRAPH_NODE_URL	Yes	http://localhost:7044	Telegraph node URL
TELEGRAPH_ENGINE_URL	Yes	http://localhost:8080	Engine server URL
TELEGRAPH_DAEMON_URL	Yes	http://localhost:8081	Daemon API URL
TELEGRAPH_EVM_PRIVATE_KEY	Yes*	—	EVM private key (0x-prefixed hex)
TELEGRAPH_SOLANA_PRIVATE_KEY	No*	—	Solana private key (base58)
EVM_NETWORK	No	eip155:*	EVM CAIP-2 network
SVM_NETWORK	No	solana:*	Solana CAIP-2 network
REFRESH_INTERVAL_MS	No	300000	Miner-tool refresh interval (ms). 0 to disable.

*At least one private key required.

Available Tools

Node Tools (no payment)

Tool	Description
tg_node_status	Node status, public key, chain info
tg_node_subnets_health	Miner integration health check
tg_node_list_subnets	Full miner catalog with metadata, schemas, endpoints

Engine Tools

Tool	Payment	Description
tg_engine_list_subnets	Free	List the miners the Engine can route to
tg_engine_ask	x402	Auto-routed inference (LLM picks the best miner for your query)
tg_engine_ask_subnet	x402	Direct inference through a specific miner by ID

Daemon Tools (no payment)

Tool	Description
tg_daemon_health	Daemon health check
tg_daemon_categories	Signal categories (POLITICS, ECONOMICS, TECHNOLOGY, CLIMATE, HEALTH, CRYPTO, SPORTS, …)
tg_daemon_questions	Query collected signals with filters (category, source, time, interest)

Dynamic Miner Tools (auto-discovered, x402 payment)

Tools for each miner endpoint are auto-generated from the Telegraph node's live integration registry. The live set changes on-chain, so treat this as a snapshot, not the source of truth (call tg_node_list_subnets for the current catalog):

Miner	Tools
Zeus (18) — Weather	tg_zeus_predict
ItsAI (32) — AI text detection	tg_itsai_text_detector_detect
Sapling (33) — AI content detection	tg_sapling_ai_detector_detect
BitMind (34) — Deepfake	tg_bitmind_detect_image, tg_bitmind_detect_video, tg_bitmind_preprocess_video, tg_bitmind_get_video_upload_url
OpenAI (102) — LLM / images	tg_openai_chat, tg_openai_responses, tg_openai_embed, tg_openai_images_generate, tg_openai_moderate

These update automatically. New miners registered on-chain appear within 5 minutes. Deregistered miners are cleaned up. The agent always sees only currently valid tools.

Some tool and field names contain subnet for legacy reasons — Telegraph began by integrating Bittensor subnets. Today a miner is any provider integrated via YAML, subnet or not.

How x402 Payments Work

When an agent calls a paid tool (e.g., tg_engine_ask):

1. MCP server sends request to Telegraph
2. Telegraph returns HTTP 402 with payment requirements in response header
3. @x402/fetch intercepts the 402, signs an EIP-3009 TransferWithAuthorization using your private key, attaches the signature as a PAYMENT header, and retries
4. Telegraph verifies the payment on-chain via the PayAI facilitator and returns the result

The agent and LLM never see the payment flow, private key, or blockchain transaction. It's fully transparent — the agent just sees a tool that returns results.

Integration Guides

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Using npx (simplest — no clone or build):

{
  "mcpServers": {
    "telegraph": {
      "command": "npx",
      "args": ["-y", "telegraph-protocol-mcp"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

Or pointing at a local build:

{
  "mcpServers": {
    "telegraph": {
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

Restart Claude Desktop. The Telegraph tools will appear in the tool list. Try asking "What's the weather in Lahore?" or "Use the Telegraph engine to explain what Bitcoin is."

Cursor

Add to Cursor Settings → MCP → Add new MCP server:

{
  "mcpServers": {
    "telegraph": {
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

ElizaOS

In your Eliza character file or MCP plugin config:

{
  "mcp": {
    "telegraph": {
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

ElizaOS v0.25+ supports MCP via the @elizaos/plugin-mcp package. Enable it in your character's plugin list:

{
  "plugins": ["@elizaos/plugin-mcp"]
}

LangChain / LangGraph

LangChain supports MCP through langchain-mcp-adapters:

pip install langchain-mcp-adapters

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "telegraph": {
        "command": "node",
        "args": ["/path/to/telegraph-mcp/dist/index.js"],
        "env": {
            "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
            "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
            "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
            "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here",
        },
        "transport": "stdio",
    }
})

tools = client.get_tools()
# Use tools with your LangChain agent

TypeScript/Node.js:

npm install @langchain/mcp-adapters

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
  telegraph: {
    command: "node",
    args: ["/path/to/telegraph-mcp/dist/index.js"],
    env: {
      TELEGRAPH_NODE_URL: "http://13.237.89.59:7044",
      TELEGRAPH_ENGINE_URL: "http://13.237.89.59:8080",
      TELEGRAPH_DAEMON_URL: "http://13.237.89.59:8081",
      TELEGRAPH_EVM_PRIVATE_KEY: "0xyour_key_here",
    },
    transport: "stdio",
  },
});

const tools = await client.getTools();

OpenClaw

OpenClaw natively supports MCP via configuration. Add to openclaw.config.json:

{
  "mcpServers": {
    "telegraph": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

Goose

Goose supports MCP servers through its extensions system. Configuration in ~/.config/goose/config.yaml:

extensions:
  telegraph:
    type: mcp
    command: node
    args:
      - /path/to/telegraph-mcp/dist/index.js
    env:
      TELEGRAPH_NODE_URL: http://13.237.89.59:7044
      TELEGRAPH_ENGINE_URL: http://13.237.89.59:8080
      TELEGRAPH_DAEMON_URL: http://13.237.89.59:8081
      TELEGRAPH_EVM_PRIVATE_KEY: 0xyour_key_here

VS Code / Continue

In Continue's config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "node",
          "args": ["/path/to/telegraph-mcp/dist/index.js"],
          "env": {
            "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
            "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
            "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
            "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
          }
        }
      }
    ]
  }
}

Generic / Any MCP Client

The server uses MCP stdio transport — the standard for local MCP servers. Any client that supports the MCP protocol over stdio can use it:

{
  "mcpServers": {
    "telegraph": {
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

Dynamic Tool Discovery

Subnet tools are not hardcoded. On startup and every 5 minutes:

1. Fetches live integrations from GET /miner-dispatcher/integrations on the Telegraph node
2. Diffs against currently registered tools
3. Adds new subnets → auto-registers tools
4. Removes stale subnets → deletes tools
5. Sends notifications/tools/list_changed to connected clients

This means:

• New subnets appear automatically within 5 minutes of on-chain registration — no MCP restart needed
• Removed subnets are cleaned up — agents won't call non-existent tools
• Agents always have an accurate view of what's available on the network

Security

• Use a burner wallet. Never use your main wallet. Fund with only the USDC needed for inference.
• The private key stays in the MCP process. Never exposed to the agent or LLM.
• The MCP server runs locally over stdio — no network exposure.
• Payments are per-call: typically $0.01 per inference request.

Development

npm install          # Install deps
npm run build        # Compile TypeScript
npm run dev          # Dev mode with tsx (hot reload)
npx @modelcontextprotocol/inspector dist/index.js  # Inspect tools