The human layer your agents can call.

Two paths. If your agent runs on Anthropic MCP, paste a JSON block into Claude Desktop and restart. If your agent runs on REST, fire one curl. In both cases you'll see a deployment come back with an ID within the second.

// claude_desktop_config.json — paste and restart Claude Desktop.
{
  "mcpServers": {
    "humandeploy": {
      "command": "npx",
      "args": ["-y", "humandeploy-mcp"],
      "env": {
        "HUMANDEPLOY_API_KEY": "hd_test_your_key"
      }
    }
  }
}

curl https://api.humandeploy.ai/v1/deployments \
  -H "Authorization: Bearer hd_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Review the pricing hero for tonal drift against messaging-framework v3. Return one-line diagnosis + three rewrites.",
    "skills": ["brand-strategy", "copy"],
    "context_url": "https://humandeploy.ai/pricing",
    "urgency": "priority"
  }'

import { HumanDeploy } from "humandeploy";

const hd = new HumanDeploy({ apiKey: process.env.HUMANDEPLOY_API_KEY });

const deployment = await hd.deployments.create({
  brief: "Review the pricing hero for tonal drift. Return diagnosis + three rewrites.",
  skills: ["brand-strategy", "copy"],
  contextUrl: "https://humandeploy.ai/pricing",
  urgency: "priority"
});

console.log(deployment.id); // dep_01H8R...

from humandeploy import HumanDeploy

hd = HumanDeploy(api_key="hd_test_your_key")

deployment = hd.deployments.create(
    brief="Review the pricing hero for tonal drift. Return diagnosis + three rewrites.",
    skills=["brand-strategy", "copy"],
    context_url="https://humandeploy.ai/pricing",
    urgency="priority",
)

print(deployment.id)  # dep_01H8R...

API keys. Workspace-scoped. Two modes.

Test mode — keys prefixed hd_test_. Deployments return synthesized output, no experts paged, no billing.

Live mode — keys prefixed hd_live_. Deployments route to the real bench. Every request draws against workspace credits.

Every request to the Deploy API carries the key in the Authorization header:

Authorization: Bearer hd_live_your_key
HumanDeploy-Version: 2026-04-23

const hd = new HumanDeploy({
  apiKey: process.env.HUMANDEPLOY_API_KEY,
  apiVersion: "2026-04-23", // optional — defaults to latest stable
});

hd = HumanDeploy(
    api_key=os.environ["HUMANDEPLOY_API_KEY"],
    api_version="2026-04-23",  # optional
)

Every Deploy API action is a deployment — one unit of work handed from an agent to an expert. The agent packages context. We route to the right bench. An expert enters the workflow, makes the call, returns output.

States

A deployment moves through a narrow state machine. Subscribe to webhooks if you want to react; otherwise poll the status.

What your agent doesn't do

Your agent doesn't manage the expert. It doesn't write kickoff docs, schedule intros, or track hours. The system packages context, routes, and returns output. You get one ID per deployment and one webhook stream per workspace.

All endpoints return JSON. All timestamps are ISO 8601 in UTC. All IDs are ULID-prefixed.

curl https://api.humandeploy.ai/v1/deployments \
  -H "Authorization: Bearer hd_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dep-req-01H8R..." \
  -d '{
    "brief": "Review the Q2 launch post for tonal drift against messaging-framework v3. Return one-line diagnosis + three rewrites.",
    "skills": ["brand-strategy", "copy"],
    "context_url": "https://notion.so/humandeploy/q2-launch-draft",
    "urgency": "priority",
    "metadata": { "campaign_id": "q2-launch", "agent": "wren" }
  }'

{
  "id": "dep_01H8R4Y2K7QSG2N5PWTBX6Q3RH",
  "status": "pending",
  "brief": "Review the Q2 launch post...",
  "skills": ["brand-strategy", "copy"],
  "urgency": "priority",
  "sla_deadline": "2026-04-23T19:12:00Z",
  "credits_reserved": 24,
  "expert": null,
  "output": null,
  "metadata": { "campaign_id": "q2-launch", "agent": "wren" },
  "created_at": "2026-04-23T18:12:03Z",
  "updated_at": "2026-04-23T18:12:03Z"
}

{
  "id": "dep_01H8R4Y2K7QSG2N5PWTBX6Q3RH",
  "status": "completed",
  "expert": {
    "id": "spec_sarah_m",
    "name": "Sarah M",
    "role": "Brand Strategy"
  },
  "output": {
    "format": "markdown",
    "body": "### Diagnosis\nThe hero leans on 'empower'...",
    "attachments": []
  },
  "credits_charged": 18,
  "duration_seconds": 2612,
  "completed_at": "2026-04-23T18:55:35Z"
}

{
  "data": [
    {
      "id": "spec_sarah_m",
      "name": "Sarah M",
      "role": "Brand Strategy",
      "skills": ["brand-strategy", "copy", "positioning"],
      "tenure_years": 6,
      "median_turnaround_minutes": 52,
      "availability": "online",
      "rate_credits_per_hour": 120
    }
  ],
  "next": null
}

{
  "credits_remaining": 1842,
  "credits_reserved": 48,
  "cycle_start": "2026-04-01T00:00:00Z",
  "cycle_end": "2026-05-01T00:00:00Z",
  "deployments_this_cycle": 127,
  "burn_rate_daily": 14.3,
  "forecasted_depletion": "2026-05-08T00:00:00Z"
}

We ship an MCP server so your agent can call the Deploy API as a tool. Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any Anthropic MCP host.

Install

Paste this block into your MCP host's config file, set your key, and restart the host. No other setup.

// ~/Library/Application Support/Claude/claude_desktop_config.json  (macOS)
// %APPDATA%\Claude\claude_desktop_config.json             (Windows)
{
  "mcpServers": {
    "humandeploy": {
      "command": "npx",
      "args": ["-y", "humandeploy-mcp"],
      "env": { "HUMANDEPLOY_API_KEY": "hd_live_..." }
    }
  }
}

// .cursor/mcp.json  (repo-local) or ~/.cursor/mcp.json (global)
{
  "mcpServers": {
    "humandeploy": {
      "command": "npx",
      "args": ["-y", "humandeploy-mcp"],
      "env": { "HUMANDEPLOY_API_KEY": "hd_live_..." }
    }
  }
}

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "humandeploy": {
      "command": "npx",
      "args": ["-y", "humandeploy-mcp"],
      "env": { "HUMANDEPLOY_API_KEY": "hd_live_..." }
    }
  }
}

Tools the server exposes

The server registers five tools. Claude (or your agent) sees them as first-class capabilities alongside its built-in tools.

The tools are named deploy_specialist / list_specialists, and expert IDs use the spec_ prefix, for historical reasons — the business term is expert everywhere else. A coordinated tool rename is planned for a future version; consumers pinned to today's HumanDeploy-Version header will keep working.

First-class paths for the stacks agents actually run on. If your stack isn't here, the REST API works everywhere fetch does.

Every state change emits an event. Register an HTTPS endpoint once; receive every deployment's lifecycle. HMAC-signed. Retried with exponential backoff.

Event catalog

Signature verification

Every delivery carries HumanDeploy-Signature. Construct the signed payload as {timestamp}.{raw_body}, HMAC-SHA256 with your webhook secret, and compare with constant-time equality. Reject timestamps older than 5 minutes — that's your replay-protection.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("="))
  );
  const ts = parts.t;
  const sig = parts.v1;

  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = parts["t"], parts["v1"]

    if abs(time.time() - int(ts)) > 300:
        return False

    expected = hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(sig, expected)

HumanDeploy-Signature: t=1714500123,v1=a2c8d7f6e1b4...
HumanDeploy-Event: deployment.completed
HumanDeploy-Delivery: del_01H8R4Y...
HumanDeploy-Idempotency-Key: del_01H8R4Y...

Delivery & retries

We send events with exponential backoff on 5xx and timeouts: 30s, 2m, 8m, 30m, 2h, 8h — then dead-letter. 2xx within 10 seconds is success; 4xx is acknowledged and not retried. Deliveries are idempotent; we resend with the same HumanDeploy-Delivery ID.

Rate limits

Limits are per API key, burst-tolerant, and rolling-window enforced.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (epoch seconds).

Errors

Error responses return a JSON body in a stable shape:

{
  "error": {
    "type": "invalid_request",
    "code": "expert_unavailable",
    "message": "No experts matching those skills are currently available.",
    "request_id": "req_01H8R4Y2...",
    "docs_url": "https://humandeploy.ai/developers/api/#errors"
  }
}

Idempotency

All POST endpoints accept an optional Idempotency-Key header (any string ≤ 255 chars). We cache the response for 24h keyed on (workspace, route, key). Replays return the cached response; different bodies under the same key return a 409 idempotency_conflict.

Use it on every deployment create from an agent — the agent may retry; you don't want a second expert paged.

Versioning

We version the API by date. Send HumanDeploy-Version: 2026-04-23 to pin. Without the header, requests use the latest stable. Breaking changes get a new date and a 12-month overlap window.

Non-breaking changes — new endpoints, new optional fields, new enum values at the end of existing enums — ship without a version bump. Read the ship log to see what landed this week.