io.github.telegraphprotocol/telegraph
Decentralized AI inference (weather, deepfake detection, LLMs) with x402 USDC micropayments.
Open source Open in the app JSON README (API)
About
Decentralized AI inference (weather, deepfake detection, LLMs) with x402 USDC micropayments.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- telegraphprotocol
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.0
- Last push
- 2026-07-23T12:50:28Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:31
- Updated
- 2026-08-29 04:01:31
- Origin id
io.github.telegraphprotocol/telegraph
README
# @telegraph/mcp-server
MCP server exposing [Telegraph Protocol](https://github.com/telegraphprotocol/Telegraph) 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](docs/architecture.md) | MCP protocol, tool categories, x402 auto-payment, client integrations |
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
## Quick Start
### Option A — npx (no clone, recommended once published)
```bash
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
```bash
# 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`](https://www.npmjs.com/package/telegraph-protocol-mcp) and listed on the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.telegraphprotocol/telegraph`. Maintainers: see [PUBLISHING.md](./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):
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"plugins": ["@elizaos/plugin-mcp"]
}
```
### LangChain / LangGraph
LangChain supports MCP through `langchain-mcp-adapters`:
```bash
pip install langchain-mcp-adapters
```
```python
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:
```bash
npm install @langchain/mcp-adapters
```
```typescript
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`:
```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`:
```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`:
```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:
```json
{
"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
```bash
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
```