human-dispatch-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@human-dispatch-mcp Dispatch a task to summarize the quarterly report"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
human-dispatch-mcp
š humandispatch.ai ā Homepage & provider docs
A universal dispatch layer for AI-agent-to-human task routing ā Any business (law firms, VA services, freelancers, agencies) can plug in via webhooks and start receiving AI-dispatched tasks in minutes.
Routes tasks to registered webhook providers with smart matching, fallback chains, and proof-of-completion tracking. Any service provider registers a webhook, and the router matches tasks to providers based on capabilities, region, and budget.
Quick Start
# Clone and install
git clone https://github.com/zyntarasystems/human-dispatch-mcp.git
cd human-dispatch-mcp
npm install
# Configure (optional ā works out of the box with manual fallback)
cp .env.example .env
# Build and run
npm run build
node dist/index.jsRelated MCP server: humanrail-mcp-server
Testing with MCP Inspector
The easiest way to verify the server is working:
npx @modelcontextprotocol/inspector node dist/index.jsOpen http://localhost:5173, enter the proxy session token shown in your terminal, and click Connect.
Test sequence:
List backends ā call
human_list_backendsto seewebhook_providerandmanualRegister a provider ā call
human_register_provider:
{
"name": "Test Provider",
"webhook_url": "https://webhook.site/your-uuid",
"webhook_secret": "a-secret-that-is-at-least-32-chars-long!",
"categories": ["digital_micro"],
"task_types": ["digital"],
"regions": ["*"],
"min_budget_usd": 0,
"max_budget_usd": 500,
"max_concurrent_tasks": 10
}Dispatch a task ā call
human_dispatch_taskwith Raw JSON input mode:
{
"description": "Test task ā verify the MCP server is routing correctly",
"category": "digital_micro",
"task_type": "digital",
"budget": { "max_usd": 5, "currency": "USD" },
"deadline": {
"complete_by": "2026-04-10T18:00:00Z",
"urgency": "low"
},
"proof_required": ["text_report"],
"quality_sla": "low",
"callback_url": null
}The task should route to your registered provider. If no providers match, it falls through to the manual backend.
MCP Client Configuration
Claude Desktop / Cursor / Any MCP Client
{
"mcpServers": {
"human-dispatch": {
"command": "npx",
"args": ["human-dispatch-mcp"]
}
}
}HTTP Transport
Note: HTTP transport binds to
127.0.0.1only. For remote access, place a TLS-terminating reverse proxy (e.g. nginx, Caddy) in front of the server. Never expose the port directly.
Required: HTTP transport refuses to start without
MCP_AUTH_TOKENset. AllPOST /mcprequests must includeAuthorization: Bearer <MCP_AUTH_TOKEN>. The/callbacks/task/:taskIdendpoint uses HMAC-signature auth instead ā providers do not see the bearer token.
{
"mcpServers": {
"human-dispatch": {
"command": "npx",
"args": ["human-dispatch-mcp"],
"env": {
"TRANSPORT": "http",
"PORT": "3000",
"MCP_AUTH_TOKEN": "a-long-random-string-32-chars-or-more"
}
}
}
}Tools Reference
Tool | Description |
| Submit a task to be completed by a human worker via the best matching provider |
| Poll the current status, worker info, and proof submissions for a task |
| Cancel a pending or in-progress task |
| List tasks with filters (status, backend, category) and pagination |
| Show available backends, their configuration status, and capabilities |
| Register a webhook provider to receive dispatched tasks |
| List registered providers with stats and filters |
| Deregister a webhook provider |
Architecture
āāāāāāāāāāāāāāā
ā AI Agent ā
ā (Claude, etc)ā
āāāāāāāā¬āāāāāāāā
ā MCP Protocol (stdio or HTTP)
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā human-dispatch-mcp Server ā
ā ā
ā āāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāā ā
ā ā Task Store ā ā Provider ā ā
ā ā (in-memory)ā ā Registry ā ā
ā āāāāāāāāāāāāāā āāāāāāāāā¬āāāāāāāāā ā
ā ā ā
ā āāāāāāāāāāāāāā āāāāāāāāā¼āāāāāāāāā ā
ā ā Router āāāā Webhook ā ā
ā ā (scoring) ā ā Provider ā ā
ā āāāāāāāā¬āāāāāā ā Adapter ā ā
ā ā āāāāāāāāā¬āāāāāāāāā ā
ā ā ā ā
ā ā āāāāāāāāāāāāā¼āāāāāāāāāā ā
ā ā ā Provider A (law) ā ā
ā ā ā Provider B (VA) ā ā
ā ā ā Provider C (photos) ā ā
ā ā āāāāāāāāāāāāāāāāāāāāāāā ā
ā ā¼ ā
ā āāāāāāāāāāāāāā ā
ā ā Manual ā (always-on fallback) ā
ā ā Adapter ā ā
ā āāāāāāāāāāāāāā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāFor Service Providers
Any business can register as a provider to receive AI-dispatched tasks. Here's how:
1. Set up a webhook endpoint
Your endpoint receives POST requests with these headers:
Header | Description |
|
|
| Event type: |
| UUID of the task |
2. Handle task.new events
Request body:
{
"payload_version": 1,
"event": "task.new",
"task_id": "uuid",
"description": "What needs to be done",
"category": "photo_video",
"task_type": "physical",
"location": { "address": "123 Main St", "region": "US" },
"budget": { "max_usd": 25, "currency": "USD" },
"deadline": { "complete_by": "2026-04-10T18:00:00Z", "urgency": "medium" },
"proof_required": ["photo", "gps_checkin"],
"quality_sla": "medium"
}payload_version is the request-shape version; pin your parser to a known version and reject unknown ones. Today only 1 is sent.
Respond with:
{ "accepted": true, "external_id": "your-internal-id" }Or reject:
{ "accepted": false, "reason": "Outside service area" }Handle provider.verify events
When a provider is registered, the server immediately POSTs a provider.verify event to confirm the endpoint is reachable and willing. A 200 alone is not enough ā your endpoint must return { "verified": true } in the JSON body. Anything else (missing field, false, non-JSON) marks verification as unreachable. This makes registration require explicit consent from your endpoint, not just URL reachability.
3. Report completion (HTTP transport only)
POST to http://<server>/callbacks/task/<task_id> with headers:
x-provider-id: Your provider UUIDx-dispatch-signature:sha256=<hmac_hex>of the body
{
"status": "completed",
"proof": [
{ "type": "photo", "url": "https://...", "submitted_at": "2026-04-10T12:00:00Z" }
],
"actual_cost_usd": 20,
"notes": "Task completed successfully"
}4. Verify HMAC signatures
Always verify incoming webhooks using your shared secret:
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));HMAC canonicalization contract (load-bearing): the signature is computed over the exact bytes the request was POSTed with, not over a re-serialized JSON object. When you send a callback, sign the byte string you put on the wire ā do not parse the body, re-stringify it, and sign that, because key ordering or whitespace may differ. Use JSON.stringify(payload) once, capture the resulting string, sign that string, send that string. The server applies the same rule on the receiving side: it captures the raw request body buffer before any JSON parser touches it.
Smart Routing
The router automatically picks the best backend based on:
Agent preferences ā
preferred_backendsandfallback_chainare honored firstProvider matching ā category, task type, region, and budget compatibility
Reliability ā providers with higher completion rates are tried first
Speed ā faster providers score higher
Fallback ā the
manualbackend is always available as the ultimate fallback
Example Agent Usage
Python with LangGraph
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
async def dispatch_photo_task():
async with MultiServerMCPClient({
"human": {
"command": "node",
"args": ["path/to/human-dispatch-mcp/dist/index.js"],
"transport": "stdio",
}
}) as client:
tools = client.get_tools()
# Register a provider first
await client.call_tool("human_register_provider", {
"name": "Photo Service Co",
"webhook_url": "https://photos.example.com/webhook",
"webhook_secret": "your-secret-that-is-at-least-32-characters",
"categories": ["photo_video"],
"task_types": ["physical"],
"regions": ["US"],
"min_budget_usd": 5,
"max_budget_usd": 100,
"max_concurrent_tasks": 20
})
# Dispatch a task
result = await client.call_tool("human_dispatch_task", {
"description": "Take a photo of the menu board at Starbucks on 5th Ave, NYC",
"category": "photo_video",
"task_type": "physical",
"location": {
"address": "5th Ave & 42nd St, New York, NY",
"region": "US"
},
"budget": {"max_usd": 15, "currency": "USD"},
"deadline": {
"complete_by": "2026-01-15T18:00:00Z",
"urgency": "medium"
},
"proof_required": ["photo", "gps_checkin"],
"quality_sla": "medium"
})
print(result)
asyncio.run(dispatch_photo_task())Environment Variables
Variable | Default | Description |
|
| Transport mode: |
|
| HTTP port (when TRANSPORT=http) |
| ā | Bearer token required on every |
| ā | Webhook URL for manual task notifications |
| ā | JSON array of provider objects to pre-seed on startup |
Security
This server processes outbound HTTP requests on behalf of its callers and is intended to run inside trusted infrastructure. The relevant guarantees:
HTTP transport requires authentication.
MCP_AUTH_TOKENis mandatory; the server refuses to start without it. Bearer comparison is constant-time (timingSafeEqual).DNS-rebinding protection is enabled on
POST /mcp. The transport rejects requests whoseHostheader points at anything other than the configured loopback.Outbound URL guard. Every webhook URL the server fetches (provider registration,
MANUAL_WEBHOOK_URL,callback_url, proof URLs) goes through a structured validator: HTTPS only, no loopback, no RFC1918 / link-local / unique-local hosts, with a DNS resolution check at fetch time to defeat last-second rebinds. There is no opt-out ā use a public tunnel (ngrok, cloudflared) for local testing.Inbound callbacks are authenticated by HMAC, not by IP. Each provider registers its own webhook secret. The server verifies
x-dispatch-signatureover the raw request bytes before parsing JSON. A per-provider token bucket limits callback flood (30 burst, 5/sec sustained).Terminal-state guard. Once a task reaches
completed,failed, orcancelled, callbacks for that task are rejected with 409. This blocks replays, late provider retries, and provider-driven status flips.Webhook payload versioning. All outbound bodies carry
payload_versionandeventdiscriminators. Pin your parser; reject unknown versions.Webhook secrets never leave the server. Provider data returned by MCP tools is sanitized to drop
webhook_secret. The same field never appears in logs.No persistence. Tasks, providers, and per-task state live in memory. Restarting the server discards all state. If you operate this in production, terminate it cleanly so in-flight tasks fail fast rather than hang in providers.
If you discover a security issue, please open a private security advisory on GitHub rather than a public issue.
Roadmap
Persistent provider registry (SQLite / PostgreSQL)
Task expiration and automatic retry
Provider quality scoring and feedback loops
Cost estimation before dispatch
Batch task submission
Provider dashboard / admin UI
OAuth-based provider authentication
Contributing
Adding a New Backend Adapter
Create a new file in
src/services/backends/Extend
BaseBackendAdapterImplement all methods from
BackendAdapterinterfaceAdd the backend ID to the
BackendIdenum insrc/types.tsRegister the adapter in
src/index.ts
License
MIT
Available Tools
8 toolshuman_cancel_taskA
Cancel a pending or in-progress human task.
Attempts to cancel the task both in the local system and on the backend service. Cancellation may not be possible if the task is already completed.
PARAMETERS:
task_id: The UUID of the task to cancel.
RETURNS: { task_id, cancelled: boolean, message: string }
EXAMPLES:
Cancel a task: { task_id: "550e8400-e29b-41d4-a716-446655440000" }
DON'T USE WHEN:
The task is already completed (check status first with human_get_task_status)
You want to modify a task (cancellation is permanent ā dispatch a new task instead)
Inputs: task_id (required).
human_dispatch_taskA
Dispatch a task to a human worker via the best available backend service.
This is the primary tool for sending work to humans. You describe what needs to be done, and the system routes it to the most appropriate registered webhook provider based on category, task type, region, and budget. If no providers match or accept, the task falls through to the manual fallback.
Register providers first with human_register_provider, then dispatch tasks to them.
PARAMETERS:
description: What the human should do. Be specific about location, timing, and deliverables.
category: Task category (errand, photo_video, data_collection, verification, delivery, digital_micro, in_person, custom)
task_type: physical (requires presence), digital (remote), or hybrid (both)
location: Where to perform the task (required for physical tasks). Include address or coordinates.
budget: Maximum USD to pay. Different providers have different ranges.
deadline: When it must be done, with urgency level.
proof_required: What evidence the worker must submit (photo, video, gps_checkin, text_report, receipt, signature).
quality_sla: low (fast/cheap), medium (default), high (verified workers, multiple proofs).
preferred_backends: Optional ordered list of backends to try first (webhook_provider, manual).
fallback_chain: Optional ordered fallback list if preferred backends fail.
metadata: Optional key-value pairs for your own tracking.
EXAMPLES:
Photo task: { description: "Take a photo of the menu board at the Starbucks on 5th Ave and 42nd St, NYC", category: "photo_video", task_type: "physical", location: { address: "5th Ave & 42nd St, New York, NY" }, budget: { max_usd: 15, currency: "USD" }, deadline: { complete_by: "2027-01-15T18:00:00Z", urgency: "medium" }, proof_required: ["photo", "gps_checkin"], quality_sla: "medium" }
Data collection: { description: "Count the number of electric vehicle charging stations within 1km of Times Square", category: "data_collection", task_type: "physical", location: { address: "Times Square, NYC", radius_km: 1 }, budget: { max_usd: 25, currency: "USD" }, deadline: { complete_by: "2027-01-20T00:00:00Z", urgency: "low" }, proof_required: ["text_report", "photo"], quality_sla: "high" }
Digital microtask: { description: "Transcribe the handwritten text in the attached image to typed text", category: "digital_micro", task_type: "digital", budget: { max_usd: 2, currency: "USD" }, deadline: { complete_by: "2027-01-16T00:00:00Z", urgency: "medium" }, proof_required: ["text_report"], quality_sla: "low" }
DON'T USE WHEN:
The task can be done by an AI (use an AI tool instead)
You need instant results (humans take minutes to hours)
No providers are registered (use human_register_provider first, or rely on manual fallback)
Inputs: budget (required), category (required), deadline (required), task_type (required), +8 more.
human_get_task_statusA
Get the current status of a previously dispatched human task.
Returns the full task state including: current status, which backend is handling it, worker info (if assigned), proof submissions (if any), actual cost, and timing info.
If the task has been routed to a backend, this tool fetches fresh status from that backend and merges any new data (worker assignment, proof uploads, completion).
PARAMETERS:
task_id: The UUID returned by human_dispatch_task.
RETURNS: Full task object with status, backend_id, worker_id, proof array, cost, timestamps, and routing attempts.
EXAMPLES:
Check on a task: { task_id: "550e8400-e29b-41d4-a716-446655440000" }
DON'T USE WHEN:
You don't have a task_id (use human_list_tasks to find tasks)
You want to check all tasks at once (use human_list_tasks instead)
Inputs: task_id (required).
human_list_backendsA
List all available backend services and their capabilities.
Shows which backends are configured and ready, what types of tasks they support, their regional availability, budget ranges, and average completion times.
Use this to understand what backends are available before dispatching a task, or to debug why a task was routed to a particular backend.
NO PARAMETERS REQUIRED.
RETURNS: Array of backend capabilities including:
id: Backend identifier
name: Human-readable name
supports_physical/digital: What task types it handles
supports_location: Whether it can handle location-specific tasks
available_regions: Where it operates
min/max_budget_usd: Budget range
avg_completion_minutes: Typical turnaround time
requires_api_key: Whether external credentials are needed
configured: Whether the backend is ready
EXAMPLES:
List all backends: {} (no parameters needed)
DON'T USE WHEN:
You already know which backend to use (just set preferred_backends in human_dispatch_task)
Inputs: no named parameters.
human_list_providersA
List all registered webhook providers with their stats.
Returns provider profiles including categories, regions, budget ranges, and performance stats (reliability score, completed/failed counts). Webhook secrets are never included in the output.
PARAMETERS:
category: Optional ā filter by supported task category
region: Optional ā filter by supported region
active_only: Only show active providers (default true)
Inputs: region, category, active_only.
human_list_tasksA
List all dispatched human tasks with optional filters and pagination.
Returns tasks sorted by creation time (newest first). Use filters to narrow results by status, backend, or category.
PARAMETERS:
status: (optional) Filter by task status: pending, routed, completed, failed, cancelled
backend_id: (optional) Filter by backend: webhook_provider, manual
category: (optional) Filter by category: errand, photo_video, data_collection, verification, delivery, digital_micro, in_person, custom
limit: (optional) Max results to return, 1-100, default 20
offset: (optional) Skip N results for pagination, default 0
RETURNS: { total, count, tasks[], has_more, next_offset }
EXAMPLES:
List all tasks: {}
List completed tasks: { status: "completed" }
List webhook provider tasks: { backend_id: "webhook_provider", limit: 10 }
Paginate: { limit: 5, offset: 5 }
DON'T USE WHEN:
You know the exact task_id (use human_get_task_status for a single task)
Inputs: limit, offset, status, category, +1 more.
human_register_providerA
Register a new webhook provider to receive dispatched tasks.
Any service provider (law firm, VA agency, freelancer, etc.) can register their webhook endpoint to start receiving tasks that match their profile. The system will POST task payloads to the webhook URL, signed with HMAC-SHA256 using the shared secret.
PARAMETERS:
name: Human-readable provider name (e.g. "Smith & Associates Law")
webhook_url: HTTPS URL where tasks will be POSTed
webhook_secret: Shared secret for HMAC-SHA256 webhook signatures (min 32 characters)
categories: Task categories this provider handles (errand, photo_video, data_collection, verification, delivery, digital_micro, in_person, custom)
task_types: Task types supported (physical, digital, hybrid)
regions: Regions served (e.g. ["US", "EU", "*"] where * = global)
min_budget_usd: Minimum task budget accepted (USD)
max_budget_usd: Maximum task budget accepted (USD)
max_concurrent_tasks: Max simultaneous tasks (default 10)
WEBHOOK FORMAT: Tasks are POSTed with headers:
x-dispatch-signature: sha256=<hmac_hex>
X-Dispatch-Event: task.new | task.cancel | provider.verify
X-Dispatch-TaskId: <task_uuid>
Expected response: { "accepted": true, "external_id": "your-id" } or { "accepted": false, "reason": "..." }
Inputs: name (required), regions (required), categories (required), task_types (required), +5 more.
human_remove_providerA
Remove a registered webhook provider.
Deregisters a provider so it will no longer receive dispatched tasks. Does not affect tasks already dispatched to this provider.
PARAMETERS:
provider_id: The UUID of the provider to remove (as returned by human_register_provider)
Inputs: provider_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 8 tools
All 8 tools have clearly distinct purposes: dispatching tasks, checking status, canceling, listing tasks, listing backends, and managing providers. No overlap or ambiguity.
All tools use the 'human_' prefix followed by verb_noun (dispatch_task, get_task_status, cancel_task, etc.). Consistent and predictable pattern.
8 tools is well-scoped for a human dispatch system, covering core operations (dispatch, status, cancellation, listing) and provider management without being excessive.
The tool surface covers the main lifecycle (dispatch, status, cancel, list) and provider CRUD. Missing a tool to modify a task in flight, but cancellation and re-dispatch suffice.
Maintenance
Related MCP Connectors
Human-as-a-Service for AI agents. Delegate tasks that need a real human, get results via API.
API for AI agents to delegate tasks to real humans.
Human-in-the-loop API for AI agents. CAPTCHA, OTP, KYC, and approvals by real humans.
Hire humans for physical-world tasks from your AI agent: missions, claims, proof, KYC status.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to search for and hire humans for real-world tasks.33102 npm9MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to route tasks requiring human judgment (e.g., content moderation, refund decisions, data verification) to a vetted worker pool, with verified results returned via Lightning Network payments.MIT
- AlicenseNot gradedqualityDmaintenanceLets AI agents natively discover and hire human experts for tasks they can't do themselves, such as research, verification, and expert calls.MIT

humanforaiofficial
AlicenseAqualityCmaintenanceEnables AI agents to hire real human operators for tasks requiring physical presence, human perception, or judgment, such as verification, testing, data collection, and physical-world tasks.459 npm1MIT