# Build with AI agents

> Connect Hapti to Claude Code, Cursor, VS Code or any MCP client, and give coding agents the docs they need to integrate Hapti well.

Hapti is made to be used by AI agents as much as by developers. An agent can call Hapti through its remote MCP server to do tasks on websites, and a coding agent can read these docs as plain text to integrate Hapti in your code.

## When an agent should use Hapti

An agent should reach for Hapti when it has to act on a website that offers no API: fill a form, book a slot, download a document, check a status, sign in to a customer area. It should not use Hapti when the website has an API that covers the job, or for reading a public page that a simple fetch can read.

## Remote MCP server

The MCP server lives at `https://api.hapti.dev/mcp` and speaks Streamable HTTP. It accepts two ways in:

- **OAuth**, for apps such as Claude: you add the address, sign in to Hapti, choose the organisation and the mode, and approve. Nothing to copy.
- **An API key** in the `Authorization` header, for code editors and scripts. Use a test key while you try it: test tasks are free.

### Claude (web and desktop)

In Claude, open **Settings**, then **Connectors**, and add a custom connector with the address `https://api.hapti.dev/mcp`. Claude opens the Hapti sign-in: choose the organisation, **Test** or **Live**, and approve. The connection appears in the Hapti console under **Developers**, where you can disconnect it at any time.

Any other client that supports MCP authorization works the same way: give it the address and it will open the Hapti sign-in.


### Install in one click

The fastest way: create a test key in the [console](https://app.hapti.dev), under **Developers**. Next to the new key, the **Cursor**, **VS Code** and **Claude Code** buttons install Hapti with that key already filled in.

From here, these links install Hapti with a placeholder: replace `hp_test_YOUR_KEY` with your key in the editor that opens.

- [Add to Cursor](https://cursor.com/install-mcp?name=hapti&config=eyJ1cmwiOiJodHRwczovL2FwaS5oYXB0aS5kZXYvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIGhwX3Rlc3RfWU9VUl9LRVkifX0%3D)
- [Install in VS Code](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522hapti%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fapi.hapti.dev%252Fmcp%2522%252C%2522headers%2522%253A%257B%2522Authorization%2522%253A%2522Bearer%2520hp_test_YOUR_KEY%2522%257D%257D)

### Claude Code

```bash
claude mcp add --transport http hapti https://api.hapti.dev/mcp \
  --header "Authorization: Bearer hp_test_..."
```

### Cursor

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "hapti": {
      "url": "https://api.hapti.dev/mcp",
      "headers": { "Authorization": "Bearer hp_test_..." }
    }
  }
}
```

### VS Code

Add this to `.vscode/mcp.json`:

```json
{
  "servers": {
    "hapti": {
      "type": "http",
      "url": "https://api.hapti.dev/mcp",
      "headers": { "Authorization": "Bearer hp_test_..." }
    }
  }
}
```

### Any other client

Any MCP client that supports remote servers over HTTP with custom headers can connect with the same address and header.

## Tools

| Tool | What it does |
| --- | --- |
| `start_task` | Give a goal to a Hapti agent that operates a real web browser by sight, like a person. |
| `get_task` | State of a task. |
| `answer_task` | Answer the question a waiting task asked. |
| `approve_task` | Give or refuse the approval a waiting task asked for before a step that commits the person. |
| `cancel_task` | Stop a task that is queued, running or waiting. |
| `estimate_task` | The price of a task before starting it, from the earlier successes of the same task and its recipe: likely_cents, at_most_cents and what it is based on. |
| `list_templates` | The ready-made tasks Hapti offers on sites that have no API (book an appointment, file a form, track an application, get invoices, cancel a subscription, place an order...), each with its id, what it does and its parameters. |
| `list_tasks` | The latest tasks of this key, newest first, optionally only one status (for example running or waiting): find a task again when you lost its id. |
| `list_recipes` | The recipes of this organisation, newest first: id, name, site, number of steps, uses. |
| `get_balance` | The credit left for live tasks, in cents of US dollars. |

The agent starts a task with `start_task`, then calls `get_task` with `wait_seconds` in a loop. When a task waits, the agent relays the question or the approval to the person and answers with `answer_task` or `approve_task`. It must never invent the answer.

## Docs for coding agents

Every page of these docs exists as plain Markdown: add `.md` to its address, for example [/docs/quickstart.md](/docs/quickstart.md). Each page also has **Copy as Markdown**, **Ask Claude** and **Ask ChatGPT** buttons.

| File | What it holds |
| --- | --- |
| [/llms.txt](/llms.txt) | A short map of Hapti and links to every page |
| [/llms-full.txt](/llms-full.txt) | The whole documentation in one file |
| [/openapi.json](/openapi.json) | The OpenAPI 3.1 specification of every endpoint |

A prompt that works well with a coding agent:

```text
Integrate Hapti in this project. Read https://hapti.dev/llms-full.txt first.
Use the official SDK, send an Idempotency-Key with every task you create,
receive results with a signed webhook endpoint, and verify the signature.
Use the test key from HAPTI_KEY. Never invent data a task asks for: relay
the question to the user.
```

## Good practice for agents

- Give the agent only the data the task needs, in `data`. It uses nothing else.
- Set `user` to the person the task is for, so their session and stored accounts are used.
- Ask for an `output` schema when a program reads the result.
- Set `max_price_cents` when the agent runs without supervision.
- Use test keys while building. Switch to a live key only for real tasks.
