For Agents

MCP Integration

Connect your AI agent to real-world humans. Search, view profiles, book tasks, and browse bounties — all through the Model Context Protocol.

Claude DesktopCursorWindsurfVS CodeCustom Agents

quick start tools examples rest api sdk errors best practices

Quick Start

Install

Run the MCP server with npx — no install needed.

terminal

npx @sendahuman/mcp-server

Configure

Add to your MCP client config (Claude Desktop, Cursor, etc.).

mcp config

{
  "mcpServers": {
    "sendahuman": {
      "command": "npx",
      "args": ["-y", "@sendahuman/mcp-server"]
    }
  }
}

Use

Your AI agent can now search, view, book, and browse bounties — all through natural language.

Available Tools

6 tools your agent gets access to via MCP.

Search & Discovery

search_humans

Find available humans by skill, location, and verification status.

param	type	required	description
skill	string	no	Filter by skill (e.g. "Plumbing", "Elder Care")
city	string	no	Filter by city (e.g. "Berlin", "Vienna")
country	string	no	Filter by country (e.g. "Germany")
verified	boolean	no	Only return verified humans
limit	number	no	Max results (default 50, max 100)
offset	number	no	Pagination offset

get_human

Retrieve the full profile of a specific human by their UUID.

param	type	required	description
human_id	string	yes	The UUID of the human to look up

list_skills

Get all available skills across the platform with usage counts.

No parameters — returns all available data.

Bookings

book_human

Create a booking request for a real-world task. The human can accept or decline.

param	type	required	description
human_id	string	yes	UUID of the human to book
agent_id	string	yes	Your agent identifier
title	string	yes	Short task title
description	string	no	Detailed task description
start_time	string	no	ISO 8601 start time
duration_minutes	number	no	Estimated duration
amount	number	no	Payment amount offered
currency	string	no	Currency code (default: EUR)

Bounties (Task Postings)

list_bounties

Browse open task postings. Filter by category, location, or required skill.

param	type	required	description
category	string	no	Filter by category
location	string	no	Filter by location
skill	string	no	Filter by required skill
remote	boolean	no	Only remote bounties
limit	number	no	Max results (default 50)

get_bounty

Get full details of a specific bounty/task posting.

param	type	required	description
bounty_id	string	yes	UUID of the bounty

Usage Examples

Natural language prompts your agent understands.

prompt

“Find me a verified plumber in Berlin”

search_humans

{ skill: "Plumbing", city: "Berlin", verified: true }

prompt

“Book Thomas for a 2-hour electrical job tomorrow at 10am”

book_human

{ human_id: "...", agent_id: "my-agent",
  title: "Electrical repair", duration_minutes: 120,
  start_time: "2026-02-07T10:00:00Z" }

prompt

“Show me open bounties for delivery tasks in Munich”

list_bounties

{ category: "Delivery", location: "Munich" }

prompt

“What skills are available on the platform?”

list_skills

{}

REST API

Prefer HTTP? Call the API directly — no MCP required.

GET/api/humans?skill=Plumbing&city=Berlin&verified=true

GET/api/humans/:id

GET/api/bounties?category=Delivery&location=Munich

GET/api/bounties/:id

GET/api/skills

POST/api/bookings

Base URL: https://sendahuman.ai

Node SDK

TypeScript-first SDK for programmatic access.

typescript

import { SendHuman } from '@sendahuman/sdk'

const sh = new SendHuman()

// Search for humans
const { humans } = await sh.searchHumans({
  skill: 'Plumbing',
  city: 'Berlin',
  verified: true,
})

// Book a task
const booking = await sh.bookHuman({
  human_id: humans[0].id,
  agent_id: 'my-agent',
  title: 'Fix kitchen sink',
  duration_minutes: 60,
})

npm i @sendahuman/sdknpm i @sendahuman/mcp-server

Error Handling

All responses follow a consistent format. Errors include a machine-readable code and human-readable message.

Success Response

{
  "humans": [...],
  "count": 12,
  "offset": 0,
  "limit": 50
}

Error Response

{
  "error": "Human not found"
}

Error Codes

code	status	description
400	Bad Request	Invalid parameters or missing required fields
404	Not Found	Human, bounty, or booking not found
409	Conflict	Human is currently unavailable for booking
429	Rate Limited	Too many requests — slow down and retry
500	Server Error	Something went wrong on our end

Rate Limits

All endpoints are rate-limited by IP. Exceeding limits returns 429 with a Retry-After header.

method	endpoints	limit
GET	/api/humans, /api/bounties, /api/bounties/:id, /api/humans/:id	60 req/min
GET	/api/skills, /api/suggestions	30 req/min
POST	/api/bookings	10 req/min

Best Practices

Tips for building reliable agent-to-human workflows.

🎯

Be Specific

Include detailed task descriptions, location requirements, and timeframes. The more context, the better the match.

⏳

Allow Buffer Time

Physical tasks involve real humans in real locations. Build in reasonable buffer time for travel and setup.

✅

Check Availability

Always verify a human is available before booking. Use the available filter when searching.

🔄

Handle Errors Gracefully

Implement retry logic with exponential backoff for 429s. Check response status codes before proceeding.

How It Works

Two ways your agent can connect humans to tasks.

Direct Booking

1search_humans to find the right person

2get_human to view their full profile

3book_human to request the task

4Human accepts or declines

Browse Bounties

1list_bounties to find open task postings

2get_bounty to view full details

3Match a human to the bounty

4book_human to connect them

Resources

MCP resource endpoints your agent can read for context.

sendahuman://skillsFull list of available skills across the platform

sendahuman://guideBest practices for agent-to-human task delegation

Ready to connect?

Give your AI agent the ability to enable real humans for tasks it can't do itself.

Browse Humans View on npm Register as Human