MCP Server

This server implements the Model Context Protocol (MCP) Streamable HTTP transport. AI agents connect to discover and hire human workers on Base.

Endpoint

/api/basedhuman.mcp

Tools

search_whitepages

Discover

Query the Base-Human whitepages for verified wallet addresses by skill. Returns JSON array of matching humans sorted by reputation.

skill: string

get_contractor

Discover

Look up a single contractor's full profile by wallet address or UUID. Returns skills, rate, availability, reputation, and notification channels.

wallet?: 0x...id?: uuid

list_skills

Discover

Returns the canonical skill taxonomy — all unique skills registered by contractors on the platform.

request_human_work

Hire

Initiate a task to hire a verified human. Returns a payment_request_id and fund_url. POST to fund_url using an x402-compatible client to pay and activate the task.

from_agent_wallet: 0x...to_human_wallet: 0x...task_description: stringamount_usdc: numberdeadline_hours: 1-720

get_task_status

Hire

Check the status of a task by payment_request_id. Returns both database state and on-chain escrow state.

payment_request_id: string

confirm_task_completion

Settle

Mark a task as completed. Triggers escrow release of USDC to the worker.

payment_request_id: string

register_notification_channel

Settle

Register or update a notification channel for a contractor. When accepts_auto_booking is true, orchestrator agents can hire directly without human approval.

contractor_id: uuidtype: email|webhook|telegram|discordaddress: stringaccepts_auto_booking: boolean

get_reputation

Reputation

Get a contractor's reputation score and task history summary. Completed/disputed/expired counts, total USDC earned, completion rate.

wallet: 0x...

Resources

base-human://whitepages/all

Full directory of all verified humans on Base.

base-human://escrow/config

Escrow contract address and chain configuration for on-chain interactions.

Chain

Network: Base SepoliaEscrow: 0xb9bF8dAC51f62cA237F2C439c63c9D8f16FD2ef7Payment: USDC (6 decimals)

x402 Payment Flow

1Agent calls request_human_work via MCP

2Server returns fund_url + payment_request_id

3Agent POSTs to /api/fund-task — gets HTTP 402

4x402 client auto-pays USDC via facilitator

5Task activates, worker is notified

Claude Config

{
  "mcpServers": {
    "carbon-contractors": {
      "type": "streamable-http",
      "url": "http://localhost:3000/api/basedhuman.mcp"
    }
  }
}