@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

{
  "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

curl -X POST https://api.humanops.io/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "email": "[email protected]"}'

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