Skip to main content
Glama

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.js

Related MCP server: humanrail-mcp-server

Testing with MCP Inspector

The easiest way to verify the server is working:

npx @modelcontextprotocol/inspector node dist/index.js

Open http://localhost:5173, enter the proxy session token shown in your terminal, and click Connect.

Test sequence:

  1. List backends — call human_list_backends to see webhook_provider and manual

  2. Register 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
}
  1. Dispatch a task — call human_dispatch_task with 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.1 only. 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_TOKEN set. All POST /mcp requests must include Authorization: Bearer <MCP_AUTH_TOKEN>. The /callbacks/task/:taskId endpoint 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

human_dispatch_task

Submit a task to be completed by a human worker via the best matching provider

human_get_task_status

Poll the current status, worker info, and proof submissions for a task

human_cancel_task

Cancel a pending or in-progress task

human_list_tasks

List tasks with filters (status, backend, category) and pagination

human_list_backends

Show available backends, their configuration status, and capabilities

human_register_provider

Register a webhook provider to receive dispatched tasks

human_list_providers

List registered providers with stats and filters

human_remove_provider

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

x-dispatch-signature

sha256=<hmac_hex> — HMAC-SHA256 of the request body using your shared secret

X-Dispatch-Event

Event type: task.new, task.cancel, or provider.verify

X-Dispatch-TaskId

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 UUID

  • x-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:

  1. Agent preferences — preferred_backends and fallback_chain are honored first

  2. Provider matching — category, task type, region, and budget compatibility

  3. Reliability — providers with higher completion rates are tried first

  4. Speed — faster providers score higher

  5. Fallback — the manual backend 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

stdio

Transport mode: stdio or http

PORT

3000

HTTP port (when TRANSPORT=http)

MCP_AUTH_TOKEN

—

Bearer token required on every POST /mcp request when TRANSPORT=http. The HTTP transport refuses to start if unset.

MANUAL_WEBHOOK_URL

—

Webhook URL for manual task notifications

PROVIDERS_CONFIG

—

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_TOKEN is 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 whose Host header 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-signature over 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, or cancelled, 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_version and event discriminators. 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

  1. Create a new file in src/services/backends/

  2. Extend BaseBackendAdapter

  3. Implement all methods from BackendAdapter interface

  4. Add the backend ID to the BackendId enum in src/types.ts

  5. Register the adapter in src/index.ts

License

MIT

Available Tools

8 tools
human_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:

  1. 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:

  1. 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" }

  2. 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" }

  3. 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:

  1. 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:

  1. 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:

  1. List all tasks: {}

  2. List completed tasks: { status: "completed" }

  3. List webhook provider tasks: { backend_id: "webhook_provider", limit: 10 }

  4. 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

    A4.4/5.0

    Scored across 8 tools

    Disambiguation5/5

    All 8 tools have clearly distinct purposes: dispatching tasks, checking status, canceling, listing tasks, listing backends, and managing providers. No overlap or ambiguity.

    Naming Consistency5/5

    All tools use the 'human_' prefix followed by verb_noun (dispatch_task, get_task_status, cancel_task, etc.). Consistent and predictable pattern.

    Tool Count5/5

    8 tools is well-scoped for a human dispatch system, covering core operations (dispatch, status, cancellation, listing) and provider management without being excessive.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      4
      59 npm
      1
      MIT