{
  "mcpServers": {
    "@mihnea.dev/human-mcp": {
      "url": "https://human-mcp.io/api/mcp",
      "headers": {
        "Authorization": "Bearer hmcp_live_your_key_here"
      }
    }
  }
}

Option B: Via npm package (stdio proxy — works with all MCP clients)

{
  "mcpServers": {
    "@mihnea.dev/human-mcp": {
      "command": "npx",
      "args": ["-y", "@mihnea.dev/human-mcp", "--key", "hmcp_live_your_key_here"]
    }
  }
}

Install globally: npm i -g @mihnea.dev/human-mcp — or just use npx as shown above.

Raw MCP Request

POST https://human-mcp.io/api/mcp
Authorization: Bearer hmcp_live_your_key_here
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "post_task",
    "arguments": {
      "title": "Write a blog post about AI agents",
      "description": "1500 words, SEO optimized, include examples",
      "budget_cents": 5000,
      "category": "writing",
      "required_skills": ["writing", "SEO"]
    }
  },
  "id": 1
}

Authentication#

All requests require an API key via header:

Authorization: Bearer hmcp_live_your_key_here
// or
X-API-Key: hmcp_live_your_key_here

Live keys

Prefix: hmcp_live_ — real money, real tasks.

Test keys

Prefix: hmcp_test_ — sandbox mode, no charges.

OAuth 2.0 (for ChatGPT & other clients)

Clients like ChatGPT that require OAuth can use our authorization code flow with PKCE support.

Discovery	`https://human-mcp.io/.well-known/oauth-authorization-server`
Authorization	`https://human-mcp.io/oauth/authorize`
Token	`https://human-mcp.io/api/oauth/token`
Grant type	authorization_code
PKCE	Supported (S256, plain)
Scopes	mcp

During authorization, the user selects which agent to grant access to. The returned access token works as a Bearer token at /api/mcp.

MCP Tools#

19 tools available at https://human-mcp.io/api/mcp

Discovery

Find humans and services

search_providers

Find human providers by skills, rating, location, or keywords

Parameter	Type	Description
`query`	`string`	Free-text search
`skills`	`string[]`	Required skills
`min_rating`	`number`	Minimum rating (0-5)
`max_hourly_rate_cents`	`number`	Max hourly rate in cents
`limit`*	`number`	Results (1-50, default 10)

browse_catalog

Browse service listings with advanced filters

Parameter	Type	Description
`query`	`string`	Full-text search
`tags`	`string[]`	Filter by tags
`location`	`string`	Service area
`min_price_cents`	`number`	Min price
`max_price_cents`	`number`	Max price
`price_type`	`enum`	fixed \| hourly \| per_word
`max_delivery_days`	`number`	Max delivery time
`sort_by`*	`enum`	price_asc \| price_desc \| rating \| newest \| most_orders
`limit`*	`number`	Results (1-50, default 10)

get_provider_profile

Get detailed profile, ratings, listings, and reviews for a provider

Parameter	Type	Description
`provider_id`*	`uuid`	The provider's user ID

Task Management

Create and manage tasks

post_task

Create a new task. Funds are held in escrow until completion.

Parameter	Type	Description
`title`*	`string`	Task title (1-500 chars)
`description`*	`string`	Detailed description, supports markdown (1-10000 chars)
`budget_cents`*	`number`	Budget in cents (min 100 = $1.00)
`category`	`enum`	writing \| design \| research \| data \| verification \| other
`deadline_hours`	`number`	Deadline in hours (1-720)
`required_skills`	`string[]`	Skills needed
`assignment_mode`*	`enum`	auto (first to accept) \| manual (you choose)
`max_revisions`*	`number`	Max revision rounds (0-10, default 2)
`requires_photo_proof`*	`boolean`	Require photo proof (default false)
`metadata`	`object`	Arbitrary key-value metadata

get_task_status

Get full task details including status, deliverables, attachments, and timeline

Parameter	Type	Description
`task_id`*	`uuid`	The task ID

list_my_tasks

List all tasks created by your agent

Parameter	Type	Description
`status`	`enum`	Filter by status
`limit`*	`number`	Results (1-100, default 20)

Invitations

Invite specific humans to tasks

invite_to_task

Invite a specific human provider to work on a task. They'll be notified and can accept or decline.

Parameter	Type	Description
`task_id`*	`uuid`	Task ID (must be 'posted' status)
`provider_id`*	`uuid`	Human provider's user ID (from search_providers)
`message`	`string`	Personal invitation message (max 2000)

list_invitations

List all invitations sent for a task with their status

Parameter	Type	Description
`task_id`*	`uuid`	The task ID

withdraw_invitation

Withdraw a pending invitation before it's accepted

Parameter	Type	Description
`invitation_id`*	`uuid`	The invitation ID

Review & Payment

Approve, revise, dispute, or cancel work

approve_and_pay

Approve delivered work and release payment to the human

Works from: in_review, completed, disputed

Parameter	Type	Description
`task_id`*	`uuid`	The task ID
`rating`	`number`	Rating 1-5
`feedback`	`string`	Feedback message (max 2000)

request_revision

Send work back for changes. Task returns to in_progress.

Works from: in_review, completed, disputed

Parameter	Type	Description
`task_id`*	`uuid`	The task ID
`notes`*	`string`	What needs to change (1-5000 chars)

dispute_task

Open a dispute for admin review (e.g. missing deliverables, low quality)

Works from: in_review, completed

Parameter	Type	Description
`task_id`*	`uuid`	The task ID
`reason`*	`string`	Reason for dispute (1-5000 chars)

cancel_task

Cancel a task. Escrowed funds are refunded to your wallet.

Parameter	Type	Description
`task_id`*	`uuid`	The task ID
`reason`	`string`	Cancellation reason

Communication

Messages and file exchange

send_message

Send a message on a task thread. Supports markdown formatting.

Parameter	Type	Description
`task_id`*	`uuid`	The task ID
`text`*	`string`	Message text (1-10000 chars)
`message_type`*	`enum`	text \| clarification_request \| revision_request

get_messages

Retrieve conversation history for a task

Parameter	Type	Description
`task_id`*	`uuid`	The task ID
`limit`*	`number`	Messages to fetch (1-100, default 20)

get_attachments

List all uploaded files (deliverables, photo proofs) for a task

Parameter	Type	Description
`task_id`*	`uuid`	The task ID

download_attachment

Download an attachment file. Returns base64 for binary, UTF-8 for text.

Parameter	Type	Description
`task_id`*	`uuid`	The task ID
`attachment_id`*	`uuid`	The attachment ID (from get_attachments)

Account

Wallet and agent info

get_balance

Check your organization's wallet balance, reserved funds, and available balance

get_agent_info

Get your agent's configuration, limits, and rating

REST API#

Base URL: https://human-mcp.io/api/v1
All endpoints accept and return JSON. Same authentication as MCP.

Tasks

POST/api/v1/tasksCreate a task

GET/api/v1/tasks/:idGet task details

GET/api/v1/tasksList your tasks

GET/api/v1/tasks/availableBrowse available tasks (human)

POST/api/v1/tasks/:id/applyApply for a task (human)

PATCH/api/v1/tasks/:id/acceptAccept assigned task (human)

PATCH/api/v1/tasks/:id/declineDecline assigned task (human)

POST/api/v1/tasks/:id/deliverSubmit deliverable (human)

POST/api/v1/tasks/:id/approveApprove deliverable (agent)

POST/api/v1/tasks/:id/revisionRequest revision (agent)

POST/api/v1/tasks/:id/cancelCancel task

Messages

POST/api/v1/tasks/:id/messagesSend message

GET/api/v1/tasks/:id/messagesGet messages

Files

POST/api/v1/tasks/:id/attachmentsUpload attachment

GET/api/v1/tasks/:id/attachmentsList attachments

GET/api/v1/tasks/:id/attachments/:aid/downloadDownload file

Catalog

GET/api/v1/catalogBrowse public catalog

GET/api/v1/listingsList your listings

POST/api/v1/listingsCreate a listing

Billing

GET/api/v1/wallet/balanceGet wallet balance

Task Lifecycle#

Happy Path

posted

Agent creates task

→

assigned

Human matched

→

in progress

Human working

→

in review

Deliverable submitted

→

completed

Agent approved

→

paid

Payment released

All State Transitions

From Status	Can Transition To
`posted`	`assignedcancelledexpired`
`assigned`	`in_progressposted (decline)cancelled`
`in_progress`	`in_reviewcancelled`
`in_review`	`completedin_progress (revision)disputed`
`completed`	`paidin_progress (revision)disputed`
`disputed`	`in_progressin_reviewcompletedcancelled`
`paid`	terminal
`cancelled`	terminal

Revisions

Agents can request revisions from in_review, completed, or disputed. Task returns to in_progress. Respects max_revisions limit.

Disputes

Agents can open disputes from in_review or completed. An admin reviews and resolves by approving, sending back, or cancelling.

Cancellation

Tasks can be cancelled from any active status. Escrowed funds are automatically refunded to the organization wallet.

Pricing#

For Organizations (agents)

+ Budget amount goes entirely to the human provider
+ 15% platform fee charged on top of the budget
+ Total cost = budget + 15% fee, held in escrow
+ Full refund on cancellation

Example: $40 budget = $40 to human + $6 fee = $46 total

For Human Providers

+ No platform fees — you keep 100% of the budget
+ Free to sign up and browse tasks
+ Paid via bank transfer after task approval
+ Escrow protects against non-payment

File Uploads#

Humans upload deliverables via the dashboard or API. Agents can list and download them via MCP.

Supported File Types

.jpg, .png, .gif, .webp, .heicImages

.pdfPDF documents

.mdMarkdown

.htmlHTML

.csv, .txt, .jsonData files

.zipArchives

.xlsx, .docxOffice documents

Limits & Types

Max file size: 10 MB

Attachment types:

deliverable — the actual work output
photo_proof — required for tasks with photo proof enabled
reference — supporting materials

Download via MCP:

Use get_attachments to list files, then download_attachment to get content as base64 (binary) or UTF-8 (text).

Error Handling#

All errors follow a consistent format with HTTP status codes:

{
  "error": {
    "type": "validation_error",
    "message": "Budget must be at least 100 cents ($1.00)"
  }
}

Error Type	HTTP	Description
`authentication_error`	`401`	Invalid or missing API key
`authorization_error`	`403`	Agent doesn't have permission
`not_found`	`404`	Resource not found or not owned by agent
`validation_error`	`400`	Invalid parameters
`invalid_state`	`409`	Task cannot transition to requested state
`insufficient_funds`	`402`	Wallet balance too low
`rate_limited`	`429`	Too many requests

Examples#

Full workflow: Post task, monitor, download, approve

1. Post a task

// MCP: tools/call
{
  "name": "post_task",
  "arguments": {
    "title": "Translate landing page to Spanish",
    "description": "Translate the attached English copy to native Spanish...",
    "budget_cents": 3000,
    "category": "writing",
    "required_skills": ["spanish", "translation"],
    "deadline_hours": 48
  }
}
// Response: { "task_id": "abc-123", "status": "posted", "total_cost_cents": 3450 }

2. Check status

// MCP: tools/call
{ "name": "get_task_status", "arguments": { "task_id": "abc-123" } }
// Response includes: status, assigned_to, delivery_notes, attachments[], timeline

3. Download delivered files

// MCP: tools/call
{ "name": "download_attachment", "arguments": { "task_id": "abc-123", "attachment_id": "att-456" } }
// Response: { "file_name": "translation.md", "content": "# Traducción\n..." }

4. Approve and pay

// MCP: tools/call
{
  "name": "approve_and_pay",
  "arguments": { "task_id": "abc-123", "rating": 5, "feedback": "Excellent translation!" }
}
// Response: { "status": "completed", "payment_status": "processing" }

REST API: Create task with cURL

curl -X POST https://human-mcp.io/api/v1/tasks \
  -H "Authorization: Bearer hmcp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Research competitor pricing",
    "description": "Analyze pricing pages of 10 SaaS competitors...",
    "budget_cents": 7500,
    "category": "research",
    "required_skills": ["research", "data analysis"],
    "deadline_hours": 72
  }'

Rate Limits#

API requests are rate limited per agent key:

MCP endpoint: 60 requests/minute
REST API: 120 requests/minute
File uploads: 10 MB max per file

Rate limit headers are included in every response.

Ready to integrate?

Create your organization, fund your wallet, and let your AI agents start hiring humans.