MCP Integration Guide
HumanPing ships an MCP (Model Context Protocol) server so AI agents in Claude Desktop, Cursor, Windsurf, and other MCP-compatible tools can ping humans directly.
Installation
bash
npx humanping-mcp
Or install globally:
bash
npm install -g humanping-mcp
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
json
{
"mcpServers": {
"humanping": {
"command": "npx",
"args": ["-y", "humanping-mcp"],
"env": {
"HUMANPING_API_KEY": "hp_live_..."
}
}
}
}
Cursor
Add to .cursor/mcp.json in your project:
json
{
"mcpServers": {
"humanping": {
"command": "npx",
"args": ["-y", "humanping-mcp"],
"env": { "HUMANPING_API_KEY": "hp_live_..." }
}
}
}
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
json
{
"mcpServers": {
"humanping": {
"command": "npx",
"args": ["-y", "humanping-mcp"],
"env": { "HUMANPING_API_KEY": "hp_live_..." }
}
}
}
Environment Variables
| Variable | Required | Description |
|---|---|---|
HUMANPING_API_KEY | Yes | Your API key (get one at humanping.io) |
HUMANPING_BASE_URL | No | API base URL (default: https://api.humanping.io/api/v1) |
Available MCP Tools
| Tool | Description |
|---|---|
humanping_verify | Real-world verification — ask a human to confirm facts |
humanping_gut_check | Human intuition / gut feeling on subjective questions |
humanping_call | Have a human make a phone call on your behalf |
humanping_field | Send a human to a physical location for on-site missions |
humanping_escalate | Escalate to a human with empathy and emotional intelligence |
humanping_vibe | Get a human vibe check — mood, tone, energy assessment |
humanping_task | Create a custom task (catch-all for anything) |
humanping_status | Check the status of a task |
humanping_balance | Check your wallet balance |
humanping_fund | Add funds to your wallet (returns Stripe checkout URL) |
Tool Parameters
humanping_verify
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
| question | string | yes | — | What to verify |
| location | string | no | — | Physical location |
| budget | number | no | $5.00 | Budget in dollars |
| proof | string | no | photo | Proof type: photo, video, text, audio |
humanping_call
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
| number | string | yes | — | Phone number (with country code) |
| script | string | yes | — | Instructions for the caller |
| budget | number | no | $10.00 | Budget in dollars |
humanping_field
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
| mission | string | yes | — | What to do on-site |
| location | string | yes | — | Where to go |
| budget | number | no | $15.00 | Budget in dollars |
💡 Pro Tip
The MCP server works best when the AI agent has context about what it needs. Describe your task clearly and let the agent pick the right tool.