@hdp/mcp-server

MCP Server for the Human Dividend Protocol — gives Claude Desktop (and any MCP-capable AI client) real-time visibility into your HDP capture session and the ability to report usage manually.

What It Does

The HDP MCP Server is a bridge between your AI assistant and the HDP Desktop App. It exposes three tools and one live resource over the Model Context Protocol, so Claude can:

• See your capture stats — tokens processed, compute units earned, receipts submitted, proof score, GPU info
• Browse receipt history — every compute receipt generated during your session
• Report usage manually — record token usage from API calls that weren't automatically captured

The server communicates with the HDP Desktop App over a local IPC connection (127.0.0.1:19876). It does not make any external network requests — all data stays on your machine.

Architecture

Claude Desktop ──(stdio)──> @hdp/mcp-server ──(HTTP)──> HDP Desktop App (:19876)
                                                              │
                                                         Capture Engine
                                                              │
                                                    Aggregator (on-chain)

The MCP server uses stdio transport (stdin/stdout), which is the standard way Claude Desktop communicates with MCP servers. It acts as a thin adapter between Claude's MCP protocol and the Desktop App's local HTTP API.

Installation

npm install -g @hdp/mcp-server

Or run directly with npx:

npx @hdp/mcp-server

Setup with Claude Desktop

Add the following to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hdp": {
      "command": "npx",
      "args": ["@hdp/mcp-server"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "hdp": {
      "command": "hdp-mcp-server"
    }
  }
}

Restart Claude Desktop after editing the config.

Prerequisites

The HDP Desktop App must be running for the MCP server to return data. If the Desktop App is not running, tools will return a "status": "disconnected" response with instructions to launch it.

Download the Desktop App from humandividendprotocol.com.

Tools

get_capture_stats

Returns current capture session statistics.

Parameters: None

Response fields: | Field | Type | Description | |-------|------|-------------| | status | string | "connected" or "disconnected" | | is_active | boolean | Whether capture is currently active | | total_tokens | number | Total tokens processed this session | | total_compute_units | number | Compute units earned | | receipts_submitted | number | Receipts successfully submitted to aggregator | | receipts_pending | number | Receipts awaiting submission | | session_duration_ms | number | Session uptime in milliseconds | | proof_score | number | Current proof quality score (0-100) | | reward_multiplier | number | HDPT reward multiplier based on tier | | gpu_info | object|null | Detected GPU hardware info | | detected_models | array | AI models detected running locally | | current_telemetry | object|null | Live system telemetry |

Example prompt: "How many tokens has HDP captured this session?"

get_receipt_history

Returns the history of compute receipts generated during the current and past sessions.

Parameters: None

Response fields (per receipt): | Field | Type | Description | |-------|------|-------------| | receipt_hash | string | Unique SHA-256 hash of the receipt | | computation_type | string | Type of computation (api_call, local_inference, etc.) | | input_tokens | number | Input/prompt tokens | | output_tokens | number | Output/completion tokens | | compute_units | number | Normalized compute units | | total_latency_ms | number | Request latency in milliseconds | | provider | string | AI provider (anthropic, openai, google, etc.) | | start | number | Unix timestamp of request start | | end | number | Unix timestamp of request end |

Example prompt: "Show me my recent HDP compute receipts"

report_usage

Manually report AI API usage that wasn't automatically captured by the proxy.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | provider | string | Yes | AI provider name ("anthropic", "openai", "google") | | input_tokens | integer | Yes | Number of input/prompt tokens | | output_tokens | integer | Yes | Number of output/completion tokens | | latency_ms | integer | Yes | Total request latency in milliseconds |

Example prompt: "Report 500 input tokens and 200 output tokens from OpenAI with 3 second latency to HDP"

Resources

hdp://status

A subscribable resource that returns the current capture status as JSON. MCP clients can poll this for live updates.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | HDP_IPC_URL | http://127.0.0.1:19876 | Override the Desktop App IPC address |

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

How It Fits Into HDP

HDP (Human Dividend Protocol) is a DePIN protocol on Base that rewards machine owners for AI compute work via the $HDPT token. The system has five client applications:

| Client | Capture Method | Tier | |--------|---------------|------| | Desktop App | Embedded proxy on :19877 intercepts API calls | Provider (1.0x) | | MCP Server | Reads stats from Desktop App via IPC | — (companion tool) | | CLI | hdp proxy or hdp wrap commands | Provider (1.0x) | | Browser Extension | Intercepts fetch() to AI APIs | Consumer (0.3x) | | TypeScript SDK | createTrackedClient() wrapper | Orchestrator (0.6x) |

The MCP Server doesn't capture compute directly — it's a companion tool that lets your AI assistant see and interact with the capture data from the Desktop App.

License

MIT