firsthandapi-mcp-server

# @firsthandapi/mcp-server — FirstHandAPI MCP Server

## Zero-to-job for agents (bootstrap mode)

No API key yet? Start the server anyway — it exposes a single `signup` tool:

```bash
npx @firsthandapi/mcp-server        # no env var needed
```

Call `signup` with an `org_name` and `email` to receive an API key and $2.50
in free credits (the key is shown once — save it), then restart configured:

```bash
claude mcp add firsthandapi -e FIRSTHAND_API_KEY=fh_live_... -- npx @firsthandapi/mcp-server
```

With the key set, all 7 job tools unlock: `create_job`, `create_job_and_wait`,
`get_job`, `list_jobs`, `get_job_files`, `cancel_job`, `get_credits`.


Official [MCP](https://modelcontextprotocol.io) server for [FirstHandAPI](https://firsthandapi.com) — human-in-the-loop (HITL) crowdsourced data collection. Enables Claude Code, Cursor, and other AI agents to collect photos, audio, video, and screen recordings from real human workers with automated AI quality scoring.

Use cases: UGC collection, ground truth data for AI evaluation, LLM training data for multimodal models.

## Installation

```bash
npm install @firsthandapi/mcp-server
```

## Configuration

### Claude Code
```json
{
  "mcpServers": {
    "firsthand": {
      "command": "npx",
      "args": ["@firsthandapi/mcp-server"],
      "env": {
        "FIRSTHAND_API_KEY": "fh_live_your_key_here"
      }
    }
  }
}
```

### Cursor
Add to `.cursor/mcp.json`:
```json
{
  "firsthand": {
    "command": "npx @firsthandapi/mcp-server",
    "env": { "FIRSTHAND_API_KEY": "fh_live_..." }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `create_job` | Post a content collection job |
| `get_job` | Get job status and details |
| `create_job_and_wait` | Post a job and wait for completion |
| `list_jobs` | List all jobs with filters |
| `cancel_job` | Cancel an open job |
| `get_job_files` | Get approved files with download URLs |
| `get_credits` | Check credit balance |

All job creation tools accept an optional `location` parameter: `{ city, state }` for text-based or `{ latitude, longitude, radius_km }` for coordinate-based constraints.

## Environment Variables

- `FIRSTHAND_API_KEY` (required) — Your API key
- `FIRSTHAND_BASE_URL` (optional) — API base URL (default: https://api.firsthandapi.com)
- `FIRSTHAND_TIMEOUT_MS` (optional) — Request timeout (default: 30000)

## License

Proprietary