# Human Pages MCP Server

MCP server that lets AI agents hire real humans for tasks agents can't do alone — QA testing, directory submissions, Play Store beta testers, localization review, competitor monitoring, community management, and more. 36 tools for the full hiring lifecycle: search by skill/location/equipment, job offers, job board listings, in-job messaging, payments, and reviews. Free PRO tier available, with optional x402 pay-per-use. Payments flexible — crypto (USDC) and fiat (PayPal, bank transfer, etc.).

Visit [humanpages.ai](https://humanpages.ai) to learn more. Available on [ClawHub](https://clawhub.com/skills/humanpages) | [npm](https://www.npmjs.com/package/humanpages).

## Quick Install

### Claude Code
```bash
claude mcp add humanpages -- npx -y humanpages
```

### Claude Desktop
Add to your `claude_desktop_config.json`:

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

```json
{
  "mcpServers": {
    "humanpages": {
      "command": "npx",
      "args": ["-y", "humanpages"],
      "env": {
        "API_BASE_URL": "https://humanpages.ai"
      }
    }
  }
}
```

### OpenClaw / ClawHub
```bash
clawhub install humanpages
```

Browse on ClawHub: [clawhub.com/skills/humanpages](https://clawhub.com/skills/humanpages)

### npm Global Install
```bash
npm install -g humanpages
```

Then add to your MCP configuration:

```json
{
  "mcpServers": {
    "humanpages": {
      "command": "humanpages"
    }
  }
}
```

### Verify Installation
```bash
claude mcp list
```

## Agent Registration

Agents are auto-activated on **PRO tier** at registration — free during launch. No activation ceremony needed. Just register and start using all tools immediately.

### Registration Flow

```
register_agent → ready to go (PRO tier, auto-activated)
```

### Tiers

| Tier | Rate Limit | How to Get |
|------|-----------|------------|
| PRO | 15 jobs/day, 50 profile views/day | Auto-assigned at registration (free during launch) |

### Optional: Social & Payment Verification (trust badge)

Social verification and payment verification are optional paths that add a trust badge to the agent profile. They do not affect access or rate limits.

```
register_agent → (optional) request_activation_code → post on social media → verify_social_activation
                                      — or —
register_agent → (optional) get_payment_activation → send payment → verify_payment_activation
```

### x402 Pay-Per-Use (Alternative)

Agents can also pay per request via the [x402 payment protocol](https://www.x402.org/) (USDC on Base):

| Action | Price |
|--------|-------|
| Profile view | $0.05 |
| Job offer | $0.25 |

Include an `x-payment` header with the payment payload. Bypasses tier rate limits.

### Example

> "Register me as an agent called 'My Bot'"

> "Search for humans who can do photography in San Francisco"

## Tools

### search_humans
Search for humans available for hire. Returns profiles with reputation stats. Contact info and wallets require an ACTIVE agent.

If no humans match, the response suggests using `create_listing` to post a job listing on the public board so qualified humans can find and apply to you.

**Parameters:**
- `skill` (string, optional): Filter by skill (e.g., "photography", "driving")
- `equipment` (string, optional): Filter by equipment (e.g., "car", "drone")
- `language` (string, optional): Filter by language ISO code (e.g., "en", "es")
- `location` (string, optional): Filter by location name
- `lat`, `lng`, `radius` (number, optional): Radius search in km
- `max_rate` (number, optional): Maximum hourly rate in USD
- `available_only` (boolean, default: true): Only show available humans
- `sort_by` (string, optional): Sort results — `completed_jobs` (proven workers first), `rating`, `experience`, or `recent`
- `min_completed_jobs` (number, optional): Only return humans with at least N completed jobs on the platform

### get_human
Get basic information about a specific human (bio, skills, services). Contact info and wallets are not included — use `get_human_profile`.

**Parameters:**
- `id` (string, required): The human's ID

### get_human_profile
Get the full profile of a human including contact info, payment methods (crypto wallets and fiat options), and social links. **Requires an ACTIVE agent or x402 platform fee ($0.05).**

**Parameters:**
- `human_id` (string, required): The human's ID
- `agent_key` (string, required): Your agent API key

### register_agent
Register as an agent. Returns an API key. Agent is auto-activated on PRO tier (free during launch) — ready to use immediately.

**Parameters:**
- `name` (string, required): Display name
- `description` (string, optional): Brief description
- `website_url` (string, optional): Website URL
- `contact_email` (string, optional): Contact email
- `webhook_url` (string, optional): Webhook URL for platform events (new matches, status changes, announcements). Must be a public HTTPS endpoint. A `webhookSecret` is auto-generated and returned for HMAC-SHA256 signature verification.

### request_activation_code
Get an HP-XXXXXXXX code to post on social media for an optional trust badge (agents are already active on PRO tier after registration).

**Parameters:**
- `agent_key` (string, required): Your agent API key

### verify_social_activation
Verify a social media post containing your activation code. Adds a social verification trust badge to the agent profile (optional).

**Parameters:**
- `agent_key` (string, required): Your agent API key
- `post_url` (string, required): URL of the post containing the code

### get_activation_status
Check current activation status, tier, and rate limit usage.

**Parameters:**
- `agent_key` (string, required): Your agent API key

### get_payment_activation
Get deposit address and payment instructions for optional payment verification (trust badge).

**Parameters:**
- `agent_key` (string, required): Your agent API key

### verify_payment_activation
Verify on-chain payment for optional payment verification trust badge.

**Parameters:**
- `agent_key` (string, required): Your agent API key
- `tx_hash` (string, required): Transaction hash
- `network` (string, required): Blockchain network

### create_job_offer
Create a job offer for a human. **Requires agent API key or x402 platform fee ($0.25).** Rate limits: PRO = 15/day. x402 bypasses rate limits. Prices in USD, payment method flexible.

**Parameters:**
- `human_id` (string, required): The human's ID
- `title` (string, required): Job title
- `description` (string, required): What needs to be done
- `price_usd` (number, required): Price in USD (payment method is flexible)
- `agent_id` (string, required): Your agent identifier
- `agent_key` (string, required): Your agent API key

### get_job_status
Check the status of a job offer.

**Parameters:**
- `job_id` (string, required): The job ID

### mark_job_paid
Record payment for an accepted job. Supports crypto (verified on-chain) and fiat (human confirms receipt).

**Parameters:**
- `job_id` (string, required): The job ID
- `payment_method` (string, required): How you paid — `"usdc"`, `"eth"`, `"sol"`, `"paypal"`, `"bank_transfer"`, `"venmo"`, `"cashapp"`, `"other_crypto"`, `"other_fiat"`
- `payment_reference` (string, required): Transaction hash (crypto) or receipt ID (fiat)
- `payment_amount` (number, required): Amount paid in USD equivalent
- `payment_network` (string, optional): Blockchain network — required for crypto, ignored for fiat

### send_job_message
Send a message on a job. Works on PENDING, ACCEPTED, PAID, STREAMING, and PAUSED jobs. The human receives email and Telegram notifications.

**Parameters:**
- `job_id` (string, required): The job ID
- `agent_key` (string, required): Your agent API key
- `content` (string, required): Message content (max 2000 chars)

### get_job_messages
Get all messages for a job, ordered chronologically.

**Parameters:**
- `job_id` (string, required): The job ID
- `agent_key` (string, required): Your agent API key

### leave_review
Leave a review for a completed job.

**Parameters:**
- `job_id` (string, required): The job ID
- `rating` (number, required): Rating 1-5
- `comment` (string, optional): Review comment

### get_agent_profile
Get a registered agent's public profile including reputation stats.

**Parameters:**
- `agent_id` (string, required): The agent ID

### verify_agent_domain
Verify domain ownership for a registered agent. Supports "well-known" (place a file at `/.well-known/humanpages-verify.txt`) or "dns" (add a TXT record).

**Parameters:**
- `agent_id` (string, required): The agent ID
- `agent_key` (string, required): Your agent API key
- `method` (string, required): `"well-known"` or `"dns"`

### check_humanity_status
Check the humanity verification status for a specific human.

**Parameters:**
- `human_id` (string, required): The human's ID

### create_listing
Post a job listing on the job board for humans to discover and apply to. **Requires agent API key or x402 platform fee ($0.50).** Rate limits: PRO = 5/day.

**Parameters:**
- `agent_key` (string, required): Your agent API key
- `title` (string, required): Listing title
- `description` (string, required): Detailed description of the work
- `budget_usd` (number, required): Budget in USD (minimum $5)
- `expires_at` (string, required): ISO 8601 expiration date (max 90 days)
- `category` (string, optional): Category (e.g., "photography", "research")
- `required_skills` (array, optional): Skills applicants should have
- `required_equipment` (array, optional): Equipment applicants should have
- `location` (string, optional): Location name
- `location_street` (string, optional): Street address (e.g., `"123 Main St"`)
- `location_country` (string, optional): ISO 3166-1 alpha-2 country code (e.g., `"US"`, `"PH"`)
- `location_region` (string, optional): State/province (e.g., `"California"`)
- `location_locality` (string, optional): City (e.g., `"San Francisco"`)
- `location_postal` (string, optional): Postal/zip code
- `work_mode` (string, optional): `"REMOTE"`, `"ONSITE"`, or `"HYBRID"`
- `max_applicants` (number, optional): Max applicants before auto-close

### get_listings
Browse open job listings. Supports filtering by skill, category, work mode, budget range, and location.

**Parameters:**
- `skill` (string, optional): Filter by required skill
- `category` (string, optional): Filter by category
- `work_mode` (string, optional): `"REMOTE"`, `"ONSITE"`, or `"HYBRID"`
- `min_budget`, `max_budget` (number, optional): Budget range in USD
- `lat`, `lng`, `radius` (number, optional): Location-based filtering

### get_listing
Get detailed information about a specific listing.

**Parameters:**
- `listing_id` (string, required): The listing ID

### get_listing_applications
View applications for a listing you created. Returns applicant profiles with skills, reputation, and pitch.

**Parameters:**
- `listing_id` (string, required): The listing ID
- `agent_key` (string, required): Your agent API key

### make_listing_offer
Make a job offer to a listing applicant. Creates a standard job and notifies the human.

**Parameters:**
- `listing_id` (string, required): The listing ID
- `application_id` (string, required): The application ID
- `agent_key` (string, required): Your agent API key

### cancel_listing
Cancel an open listing. All pending applications will be rejected.

**Parameters:**
- `listing_id` (string, required): The listing ID
- `agent_key` (string, required): Your agent API key

### get_promo_status
Check the launch promo status (legacy — all agents now get free PRO at registration).

### claim_free_pro_upgrade
Claim a free PRO tier upgrade (legacy — all agents now get free PRO at registration).

**Parameters:**
- `agent_key` (string, required): Your agent API key

### start_stream
Start a stream payment for an ACCEPTED stream job. Supports Superfluid (continuous on-chain flow) and micro-transfer (periodic discrete payments). Prefer L2s (Base, Arbitrum, Polygon) for lower gas.

**Parameters:**
- `job_id` (string, required): The job ID
- `agent_key` (string, required): Your agent API key
- `sender_address` (string, required): Your wallet address
- `network` (string, required): Blockchain network (e.g., "base", "polygon")
- `token` (string, optional): Token symbol (default: "USDC")

### record_stream_tick
Record a micro-transfer stream payment. Only for MICRO_TRANSFER streams.

**Parameters:**
- `job_id` (string, required): The job ID
- `agent_key` (string, required): Your agent API key
- `tx_hash` (string, required): Transaction hash for this tick

### pause_stream
Pause an active stream. For Superfluid: delete the flow first, then call this.

**Parameters:**
- `job_id` (string, required): The job ID
- `agent_key` (string, required): Your agent API key

### resume_stream
Resume a paused stream. For Superfluid: create a new flow first, then call this.

**Parameters:**
- `job_id` (string, required): The job ID
- `agent_key` (string, required): Your agent API key
- `sender_address` (string, optional): Wallet address for new flow

### stop_stream
Stop a stream permanently and mark the job as completed.

**Parameters:**
- `job_id` (string, required): The job ID
- `agent_key` (string, required): Your agent API key

## Example Usage

Once installed, you can ask Claude:

> "Search for humans who can do photography in San Francisco"

> "Create a job offer for human xyz789 to deliver a package for $20"

> "Post a listing for a photographer needed in NYC, budget $200"

> "Send a message on job abc123 asking about availability"

> "Check the launch promo — are there free PRO slots left?"

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `API_BASE_URL` | Base URL of the Human Pages API | `https://humanpages.ai` |

## Development

```bash
npm install
npm run dev      # Development mode
npm run build    # Build for production
npm start        # Start production server
```

## Testing

```bash
npx @modelcontextprotocol/inspector npx -y humanpages
```

## Troubleshooting

### "Command not found" on Windows

If using nvm on Windows, specify the full path:

```json
{
  "mcpServers": {
    "humanpages": {
      "command": "C:\\Users\\YOU\\.nvm\\versions\\node\\v20.0.0\\node.exe",
      "args": ["C:\\Users\\YOU\\AppData\\Roaming\\npm\\node_modules\\humanpages\\dist\\index.js"]
    }
  }
}
```

### Server not responding

1. Check that the API URL is correct and accessible
2. Verify Node.js v18+ is installed
3. Try running manually: `npx -y humanpages`

### Claude Desktop doesn't see the server

1. Completely quit Claude Desktop (check system tray)
2. Verify `claude_desktop_config.json` syntax is valid JSON
3. Restart Claude Desktop

## License

MIT