# The MCP server

The HeadHoncho MCP server lets Claude, ChatGPT, Claude Code and Cursor use your jobs and raw data as tools, with the access you approve.

Page: https://headhoncho.app/docs/api/mcp | Part of the HeadHoncho API docs: https://headhoncho.app/docs/api | Machine-readable: https://headhoncho.app/docs/api/openapi.json

## Connect an AI app

The HeadHoncho MCP server is at `https://api.headhoncho.app/mcp`. It speaks MCP over Streamable HTTP and answers JSON only. It offers the same 16 endpoints as tools, with the same names and the same arguments as the [REST API](https://headhoncho.app/docs/api), so what one can do the other can do.

## Claude.ai and ChatGPT

Open the connector settings in the app, add a custom connector, and paste `https://api.headhoncho.app/mcp`. The app sends you to HeadHoncho's own page. There you choose which companies the app reaches, its access for each area, and whether personal details are hidden, then approve. No key is copied or pasted.

## Claude Code

Add the server with a key from [API keys](https://headhoncho.app/docs/api/keys):

```bash
claude mcp add --transport http headhoncho https://api.headhoncho.app/mcp \
  --header "Authorization: Bearer hh_live_..."
```

## Cursor

Put this in `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "headhoncho": {
      "url": "https://api.headhoncho.app/mcp",
      "headers": {
        "Authorization": "Bearer hh_live_..."
      }
    }
  }
}
```

## The tools

Each tool is documented on its own page, with its arguments, its answer and an example prompt on the "Your AI" tab. A tool tells the app whether it only reads, whether it can destroy anything (none can), and whether it is safe to repeat (all are).

| Tool | Group | Needs | Effect |
| --- | --- | --- | --- |
| [`whoami`](https://headhoncho.app/docs/api/whoami) | Account | any key | Reads only |
| [`list_jobs`](https://headhoncho.app/docs/api/list_jobs) | Jobs | read on Jobs | Reads only |
| [`get_job`](https://headhoncho.app/docs/api/get_job) | Jobs | read on Jobs | Reads only |
| [`get_job_history`](https://headhoncho.app/docs/api/get_job_history) | Jobs | read on Jobs | Reads only |
| [`create_job`](https://headhoncho.app/docs/api/create_job) | Job commands | do on Jobs | Changes a job |
| [`update_job`](https://headhoncho.app/docs/api/update_job) | Job commands | do on Jobs | Changes a job |
| [`change_job_status`](https://headhoncho.app/docs/api/change_job_status) | Job commands | do on Jobs | Changes a job |
| [`assign_worker`](https://headhoncho.app/docs/api/assign_worker) | Job commands | do on Jobs | Changes a job |
| [`unassign_worker`](https://headhoncho.app/docs/api/unassign_worker) | Job commands | do on Jobs | Changes a job |
| [`add_job_note`](https://headhoncho.app/docs/api/add_job_note) | Job commands | do on Jobs | Changes a job |
| [`list_tables`](https://headhoncho.app/docs/api/list_tables) | Raw data | read on Raw data | Reads only |
| [`read_table`](https://headhoncho.app/docs/api/read_table) | Raw data | read on Raw data | Reads only |
| [`export_table`](https://headhoncho.app/docs/api/export_table) | Raw data | read on Raw data | Reads only |
| [`get_job_conversion`](https://headhoncho.app/docs/api/get_job_conversion) | Click IDs and conversions | read on Click IDs and conversions | Reads only |
| [`get_click_id_report`](https://headhoncho.app/docs/api/get_click_id_report) | Click IDs and conversions | read on Click IDs and conversions | Reads only |
| [`export_click_id_report`](https://headhoncho.app/docs/api/export_click_id_report) | Click IDs and conversions | read on Click IDs and conversions | Reads only |

## Downloads come back as a link

[Export table](https://headhoncho.app/docs/api/export_table) and [Export click id report](https://headhoncho.app/docs/api/export_click_id_report) return a file. Over MCP the answer is a one-time download link that works for five minutes, so the file never passes through the AI. Open the link yourself, or have your own code fetch it.

## Who did it

When an AI app changes a job, the job's history records it as "Claude, for" and the name of the person who approved it, for example "Claude, for Ariel T.". [Get job history](https://headhoncho.app/docs/api/get_job_history) returns that name in `by`. Rate limits are the same as for the REST API; see [errors and rate limits](https://headhoncho.app/docs/api/errors#rate-limits).

To understand what the tools do before you let an app use them, start with [the model](https://headhoncho.app/docs/api/model). Keys are on [API keys](https://headhoncho.app/docs/api/keys).