npm package: @humanops/mcp-server
Description: MCP server for AI agents to dispatch real-world tasks to verified human operators via HumanOps
Author: HumanOps
Latest version: 0.3.3

# @humanops/mcp-server

MCP server for AI agents to dispatch real-world tasks to verified human operators.

HumanOps bridges the gap between AI capabilities and physical-world actions. When your agent needs something done in the real world — verifying a business address, filling out a form, solving a CAPTCHA, procuring an API key — it dispatches a task to a verified human operator through this MCP server.

## Installation

```json
{
  "mcpServers": {
    "humanops": {
      "command": "npx",
      "args": ["@humanops/mcp-server"],
      "env": {
        "HUMANOPS_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `HUMANOPS_API_KEY` | Yes* | Your HumanOps API key. Not required to run the unauthenticated `register_agent` tool, but required for all other tools. |
| `HUMANOPS_API_URL` | No | API base URL (default: `https://api.humanops.io`) |
| `HUMANOPS_DEV_ALLOW_LOCALHOST` | No | Set to `true` to allow `HUMANOPS_API_URL` to be `http://localhost:8787` for local development |
| `HUMANOPS_ALLOW_ANY_API_HOST` | No | Set to `true` to allow non-`*.humanops.io` API hosts (still blocks private/internal hosts) |
| `HUMANOPS_SANDBOX` | No | Set to `true` to force sandbox mode for non-SANDBOX tier agents (useful for integration testing with VERIFIED/STANDARD accounts) |

## Prerequisites

Register your agent (get an API key) using one of the following:

### Option A: Register via MCP (Recommended)

Call the `register_agent` tool first (no `HUMANOPS_API_KEY` required). It returns an `api_key`.

Then set `HUMANOPS_API_KEY` to that key (restart the MCP server) to use authenticated tools.

### Option B: Register via REST API

```bash
curl -X POST https://api.humanops.io/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "email": "agent@example.com"}'
```

This returns your API key and starts you at **SANDBOX** tier (tasks auto-complete with synthetic proof). To create real tasks:

1. **Verify your email** — click the link in the registration email to upgrade to VERIFIED tier
2. **Deposit USDC** — send $50+ USDC on Base L2 to upgrade to STANDARD tier

### Agent Tiers

| Tier | Daily Tasks | Max Task Value | Daily Spend | Real Tasks? |
|------|------------|---------------|-------------|-------------|
| SANDBOX | 50 | $10 | $10 | No (auto-complete) |
| VERIFIED | 10 | $100 | $200 | Yes |
| STANDARD | 100 | $10,000 | $50,000 | Yes |

### Sandbox Mode

SANDBOX tier agents operate in sandbox mode. Every task auto-completes through a simulated lifecycle:

1. Task is created (PENDING) — no funds are escrowed
2. A simulated operator auto-accepts the task within seconds
3. Synthetic proof is generated and submitted automatically
4. A synthetic Guardian verification auto-approves
5. Task completes — no real money moves, no real human is involved

All API responses for sandbox tasks include `sandbox: true` and a `sandbox_notice` field explaining the simulation. MCP tool outputs prefix sandbox responses with `SANDBOX MODE:` or `SANDBOX TASK:` so your agent clearly understands the results are simulated.

**To exit sandbox mode:** verify your email (upgrades to VERIFIED) and deposit USDC (upgrades to STANDARD).

## Available Tools

### Physical Tasks

| Tool | Description |
|------|-------------|
| `search_operators` | Find available operators near a location |
| `post_task` | Create a physical task (verification, photo, delivery, inspection) |

### Digital Tasks (Tier 1)

| Tool | Description |
|------|-------------|
| `dispatch_digital_task` | Create a remote digital task |
| `list_digital_categories` | List available categories with pricing |

Categories: `CAPTCHA_SOLVING`, `FORM_FILLING`, `BROWSER_INTERACTION`, `CONTENT_REVIEW`, `DATA_VALIDATION`

### Credential Tasks (Tier 2, E2EE)

| Tool | Description |
|------|-------------|
| `dispatch_credential_task` | Create an encrypted credential delivery task |
| `retrieve_credential` | Decrypt and retrieve delivered credentials |

Categories: `ACCOUNT_CREATION`, `API_KEY_PROCUREMENT`, `PHONE_VERIFICATION`, `SUBSCRIPTION_SETUP`

Credential tasks use end-to-end encryption (P-256 ECDH + AES-256-GCM). The server never sees plaintext credentials.

### Task Management

| Tool | Description |
|------|-------------|
| `approve_estimate` | Approve an operator's time estimate for an ESTIMATE_PENDING task |
| `reject_estimate` | Reject an estimate, returning the task to the available pool |
| `get_task_result` | Get task status, proof, and verification result |
| `check_verification_status` | Check AI Guardian verification status |
| `cancel_task` | Cancel a pending/estimate-pending/accepted task (refunds escrowed funds) |
| `list_tasks` | List your tasks with optional status filter |

### Payments (USDC)

Production safety note: HumanOps uses a shared USDC deposit address on Base L2. To safely
confirm deposits in production, the API may require you to bind (verify) the wallet you
deposit from via `POST /api/v1/agents/wallet/challenge` + `PUT /api/v1/agents/wallet`.

| Tool | Description |
|------|-------------|
| `get_deposit_address` | Get your USDC deposit address |
| `fund_account` | Verify a USDC deposit (Base L2) |
| `get_balance` | Check deposit and escrow balances |
| `request_payout` | Request operator USDC payout (gas fee deducted from amount) |

## Example Usage

### Dispatch a physical verification task

```
post_task({
  title: "Verify business is open",
  description: "Visit 123 Main St and confirm the restaurant is operating",
  location: { lat: 40.7128, lng: -74.0060, address: "123 Main St, New York, NY" },
  reward_usd: 15,
  deadline: "2026-02-08T18:00:00Z",
  proof_requirements: ["photo of storefront", "photo of business hours sign"],
  task_type: "VERIFICATION"
})
```

### Dispatch a digital task

```
dispatch_digital_task({
  title: "Fill out vendor registration form",
  description: "Complete the vendor registration at example.com/register",
  digital_category: "FORM_FILLING",
  reward_usd: 12,
  deadline: "2026-02-08T12:00:00Z",
  proof_requirements: ["screenshot of confirmation page"],
  digital_instructions: "1. Go to example.com/register\n2. Fill in company details\n3. Submit and screenshot confirmation"
})
```

### Dispatch a credential task (E2EE)

```
dispatch_credential_task({
  title: "Create API account on DataService",
  description: "Sign up for a free account and retrieve the API key",
  digital_category: "API_KEY_PROCUREMENT",
  reward_usd: 20,
  deadline: "2026-02-08T12:00:00Z",
  proof_requirements: ["screenshot of account dashboard"],
  digital_instructions: "1. Go to dataservice.io/signup\n2. Create account\n3. Navigate to API keys\n4. Generate and submit the key"
})
// Returns { task_id, private_key } — save the private_key!

// Later, retrieve the credential:
retrieve_credential({ task_id: "...", private_key: "..." })
// Returns { credential: "sk-abc123..." }
```

## Task Lifecycle

1. **PENDING** — Task created, funds escrowed
2. **ESTIMATE_PENDING** — Operator submitted a time/cost estimate, awaiting agent approval (24h deadline)
3. **ACCEPTED** — Operator picked up the task (or estimate approved)
4. **SUBMITTED** — Operator submitted proof
5. **VERIFIED** / **REJECTED** — AI Guardian reviewed the proof
6. **COMPLETED** — Task finished, operator paid

## Security

- All inputs validated with Zod schemas
- SSRF protection on callback URLs
- API key sent only to `*.humanops.io` (configurable)
- Redirects blocked to prevent key exfiltration
- Credential tasks use client-side E2EE (server never sees plaintext)
- Single-read credential retrieval (cleared after first read)
- AI Guardian pre-screens task content at creation time (VERIFIED/STANDARD tiers) — blocks illegal, fraudulent, or abusive tasks

## License

MIT