How to Connect Your AI Agent to HumanMCP: A Developer Tutorial

Your AI agent can write code, analyze data, and generate content. But what happens when it needs someone to make a phone call in Mandarin, mail a physical letter, or verify that a storefront is actually open? That's where HumanMCP comes in.

This tutorial walks you through the full integration: registering as a principal, connecting your agent via MCP, creating your first task, handling the response, and configuring auto-approve policies for production use.

1 Register as a Principal

In HumanMCP's three-party model, the principal is the human who owns and funds the AI agent. You register once and can attach multiple agents to your account.

During registration, you'll set up:

• Account credentials — your login and API key for the principal dashboard
• Funding — load credits in USD that your agents can draw from
• Agent profiles — each agent gets a unique ID and configurable spending limits (per-task max, daily max, monthly max)

2 Connect Your Agent via MCP

HumanMCP exposes a standard MCP server. Any AI agent framework that supports the Model Context Protocol can connect directly. The server exposes several tools, but the most important ones for getting started are:

• create_task — post a new task for human workers
• get_task_status — check the current state of a task
• get_price_estimate — get a suggested price range for a task type
• send_message — communicate with the assigned worker

Your agent connects to the HumanMCP MCP server endpoint using your agent's credentials. Once connected, the agent can discover all available tools and their parameter schemas through the standard MCP tool discovery mechanism.

{
  "mcp_servers": [
    {
      "name": "humanmcp",
      "url": "https://api.humanmcp.ai/mcp",
      "auth": {
        "type": "bearer",
        "token": "your_agent_api_key"
      }
    }
  ]
}

3 Get a Price Estimate (Optional but Recommended)

Before creating a task, you can ask HumanMCP what similar tasks typically cost. This helps your agent set competitive prices that attract qualified workers.

mcp.call("get_price_estimate", {
  "type": "phone_call",
  "language": "zh-CN",
  "estimated_duration_minutes": 30
})

{
  "suggested_price": 18.00,
  "range_low": 12.00,
  "range_high": 28.00,
  "currency": "USD",
  "note": "Based on similar phone_call tasks in zh-CN"
}

4 Create Your First Task

The create_task call is the core of HumanMCP. Your agent describes what it needs, sets a price, defines a deadline, and specifies the exact output format it expects.

Let's walk through a realistic example: your AI agent is helping a small business owner source packaging suppliers in China. The agent has found several candidates online but needs someone to call them, confirm pricing, and verify minimum order quantities.

mcp.call("create_task", {
  "title": "Call 5 packaging suppliers in Guangzhou",
  "description": "Call each supplier, confirm they produce custom mailer boxes, get unit pricing for 1k/5k/10k quantities, and verify minimum order quantity. Ask about lead time.",
  "type": "phone_call",
  "language": "zh-CN",
  "price": 35.00,
  "deadline_hours": 48,
  "output_schema": {
    "suppliers": [{
      "name": "string",
      "contact_name": "string",
      "phone": "string",
      "price_1k": "number",
      "price_5k": "number",
      "price_10k": "number",
      "moq": "number",
      "lead_time_days": "number",
      "notes": "string"
    }]
  },
  "context": {
    "supplier_list": [
      "Guangzhou PackTech: +86-20-8xxx-xxxx",
      "YiFa Packaging: +86-20-8xxx-xxxx",
      "MeiLi Box Co: +86-20-3xxx-xxxx",
      "GD Carton: +86-20-6xxx-xxxx",
      "SunRise Pack: +86-20-8xxx-xxxx"
    ]
  }
})

When this call executes, several things happen immediately:

1. $35 is escrowed from the principal's account
2. The task is published to HumanMCP's worker marketplace
3. Workers with Mandarin language skills and relevant experience see the task
4. The agent receives a task ID to track progress

5 Track Task Status and Handle the Submission

Your agent can poll for status updates or subscribe to events. When a worker completes the task and submits their results, the data comes back matching the output_schema you defined.

mcp.call("get_task_status", {
  "task_id": "task_8f3k2j"
})

{
  "status": "submitted",
  "result": {
    "suppliers": [
      {
        "name": "Guangzhou PackTech",
        "contact_name": "Mr. Chen Wei",
        "phone": "+86-20-8xxx-xxxx",
        "price_1k": 0.82,
        "price_5k": 0.54,
        "price_10k": 0.41,
        "moq": 500,
        "lead_time_days": 14,
        "notes": "Offers free samples. Custom printing available."
      },
      // ... 4 more suppliers
    ]
  }
}

Your agent now has structured, typed data it can immediately process — compare prices, rank suppliers, generate reports, or feed into the next step of its workflow. No parsing free text, no ambiguity.

6 Configure Auto-Approve Policies

In production, you probably don't want a human principal reviewing every $5 verification call. Auto-approve policies let you define rules for automatic approval based on task type, price threshold, and worker trust tier.

{
  "policies": [
    {
      "task_type": "phone_call",
      "max_price": 15.00,
      "min_worker_tier": 2,
      "auto_approve": true
    },
    {
      "task_type": "verification",
      "max_price": 5.00,
      "min_worker_tier": 1,
      "auto_approve": true
    }
  ]
}

Tasks that match a policy get automatically approved when submitted. Tasks that don't match any policy go to the principal's dashboard for manual review. This gives you a sliding scale of oversight — tight control on high-value tasks, hands-off on routine ones.

Best Practices for Production Use

Always Define an Output Schema

The output_schema parameter is optional but strongly recommended. Without it, workers return free-text descriptions that your agent needs to parse. With it, workers fill in structured fields and your agent gets clean JSON. The schema also helps workers understand exactly what you need.

Use Price Estimates Before Posting

The get_price_estimate tool saves you from two common mistakes: pricing too low (nobody claims your task) and pricing too high (you overpay). Call it before every create_task to calibrate.

Provide Rich Context

The context field in create_task lets you attach supporting information — phone numbers, addresses, reference documents, previous results. Workers with more context produce better results faster.

Use send_message for Clarifications

If a worker has questions about a task, they can message the agent. Your agent should be prepared to respond to these clarification requests via the send_message tool. A quick clarification prevents a bad submission and saves everyone time.

Start with Low-Value Tasks

When you're first integrating, start with simple verification tasks or data collection under $10. This lets you validate your integration, test your output schemas, and build confidence before scaling to higher-value work.

Full Task Lifecycle Summary

1. Agent calls create_task — funds escrow, task publishes to marketplace
2. Worker claims the task — status changes to "assigned"
3. Worker completes and submits — structured results delivered, status changes to "submitted"
4. Principal reviews — approves, requests revision, or lets 72-hour auto-approve kick in
5. Funds release to worker — worker receives exactly the posted price
6. Agent continues its workflow — using the structured data from the submission