# Connecting your agent

Everything the CLI does, your agent can do. There are three ways, from the
simplest to the most independent. In all of them the agent acts **as you**:
it sees only your sites and every action is recorded under your name.

> Whichever way you choose, install the CLI and run `rapadura login` once
> ([Getting started](getting-started.md)). That login is what the agent reuses.

## 1. Let the agent use the CLI

If your agent runs commands on your computer (Claude Code, Codex CLI, Cursor
in agent mode), the installed and logged-in CLI is enough. Ask in plain
language:

> Publish the `./dist` folder as the `meetup-sobral` hotsite on rapadura,
> create it if needed, and tell me the address.

The agent will run something like
`rapadura publish ./dist --site meetup-sobral --create --json` and read the
receipt. To teach it once and for all, point it at the skill file:
<https://agents.rapadura.net/skill.md>. In Claude Code, for example, save it
as `.claude/skills/rapadura/SKILL.md` in the project.

## 2. Local MCP tools (recommended)

The CLI is itself an MCP server. Register it once and the agent gets the
`publish_site`, `list_sites`, `rollback_site` tools and friends, with direct
upload of folders from your disk.

**Claude Code**

```sh
claude mcp add rapadura -- rapadura mcp
```

**Cursor** (in `~/.cursor/mcp.json` or the project's `.cursor/mcp.json`)

```json
{ "mcpServers": { "rapadura": { "command": "rapadura", "args": ["mcp"] } } }
```

**Codex CLI** (in `~/.codex/config.toml`)

```toml
[mcp_servers.rapadura]
command = "rapadura"
args = ["mcp"]
```

**Claude Desktop** (in `claude_desktop_config.json`)

```json
{ "mcpServers": { "rapadura": { "command": "rapadura", "args": ["mcp"] } } }
```

If the agent cannot find the command, use the full path
(`~/.local/bin/rapadura`).

## 3. Hosted MCP (nothing to install)

For agents that run away from your computer, the gateway speaks MCP over
HTTP at `https://agents.rapadura.net/mcp`, authenticated with your token. It
is the same token `rapadura login` stores; if you need one somewhere else,
log in there or ask the administrator.

**Claude Code**

```sh
claude mcp add --transport http rapadura https://agents.rapadura.net/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"
```

On this lane the gateway cannot read your disk: `publish_site` takes the
files inline (`files: [{path, content}]`). It suits an agent that writes the
HTML on the spot.

**claude.ai connectors** (which require OAuth) are not supported yet; it is
on the [roadmap](roadmap.md).

## What the tools do

| tool | purpose |
|---|---|
| `whoami` | who is signed in, role, scopes |
| `list_zones` | available domains, reserved names, limits |
| `list_sites`, `show_site` | your hotsites and their state |
| `create_site` | reserve an address without publishing anything |
| `publish_site` | publish a folder (local) or inline files (hosted); `create=true` creates first |
| `list_versions`, `rollback_site` | history and rollback |
| `delete_site` | take offline; the agent should confirm with you first |
| `site_logs` | last lines of the access log |

Every write returns a **receipt** read back from the server: address,
version, what changed, warnings. Ask the agent for the address and the
version, not just "done".