MCP Overview

Endpoint

POST https://api.instahuman.com/api/mcp

The server uses the Streamable HTTP transport with MCP sessions. Authentication is via Bearer token.

Authorization: Bearer ih_your_api_key_here

Transport

InstaHuman’s MCP server is stateless per-request (runs on Cloudflare Workers). Each request creates a fresh server instance.

Initialize with POST /api/mcp
Keep the returned mcp-session-id header on subsequent requests
Supports GET, POST, and DELETE methods
Accepts application/json and returns text/event-stream or application/json

JSON-RPC Example

curl https://api.instahuman.com/api/mcp \
  -X POST \
  -H "Authorization: Bearer ih_your_api_key_here" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list",
    "params": {}
  }'

Available Tools

Job Management

Tool	Description
`create_job`	Create a new job and return immediately
`wait_job`	Block until job reaches terminal state
`get_job`	Inspect job progress and feedback
`list_jobs`	List owner’s recent jobs
`pause_job`	Pause an active job
`resume_job`	Resume a paused job
`stop_job`	Graceful shutdown, existing testers finish
`cancel_job`	Cancel an active or paused job
`close_job`	Close job and begin settlement
`resize_job`	Change number of tester slots
`approve_job`	Approve a pending settlement
`submit_dispute`	Dispute a pending settlement
`get_settlement_status`	Check settlement details

Project Management

Tool	Description
`create_project`	Create a new project
`update_project`	Update project name/description
`delete_project`	Delete a project
`get_project`	Get project details
`list_projects`	List owner’s projects
`archive_project`	Archive a project
`unarchive_project`	Unarchive a project
`assign_job_to_project`	Link/unlink a job to a project
`add_project_tester`	Manually add a tester
`list_project_testers`	List testers in a project
`update_project_tester`	Update tester flags
`remove_project_tester`	Remove a tester

Prompts

The server exposes one prompt:

job_tool_usage — Agent-facing instructions for choosing between create_job, wait_job, and follow-up status tools.

Agent Patterns

Error Handling

Tool errors return isError: true with a JSON { error: "message" } body. The wait_job tool includes additional context on timeout:

{
  "error": "Timeout waiting for job",
  "job_id": "uuid",
  "status": "active",
  "next_action": "Call wait_job(job_id) again to resume waiting, or use get_job(job_id) to inspect progress."
}