@humanops/mcp-server

@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": "[e-mail]"}'

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

• Verify your email — click the link in the registration email to upgrade to VERIFIED tier
• 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:

• Task is created (PENDING) — no funds are escrowed
• A simulated operator auto-accepts the task within seconds
• Synthetic proof is generated and submitted automatically
• A synthetic Guardian verification auto-approves
• 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

• PENDING — Task created, funds escrowed
• ESTIMATE_PENDING — Operator submitted a time/cost estimate, awaiting agent approval (24h deadline)
• ACCEPTED — Operator picked up the task (or estimate approved)
• SUBMITTED — Operator submitted proof
• VERIFIED / REJECTED — AI Guardian reviewed the proof
• 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