# Connecting an agent

rapadura exposes the same operations three ways. Pick the one that matches
where the agent runs.

## 1. CLI (any agent that can run commands)

Install, log in once, then every command works with `--json`:

```sh
rapadura login
rapadura publish ./dist --site meetup-sobral --create --json
rapadura sites list --json
rapadura rollback meetup-sobral 3 --json
```

Errors go to stderr as `{"error":{"code":"…","message":"…","hint":"…"}}` with
exit status 1. Codes are stable; see [errors.md](errors.md).

For CI or an agent without an interactive login, set `RAPADURA_TOKEN` (and
optionally `RAPADURA_GATEWAY`) in the environment instead of a credentials file.

## 2. Local MCP over stdio (Claude Code, Cursor, Codex, …)

The CLI is also an MCP server. It uses the saved login and can upload local
directories:

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

Tools: `whoami`, `list_zones`, `list_sites`, `show_site`, `create_site`,
`publish_site` (with `path` or inline `files`), `list_versions`,
`rollback_site`, `delete_site`, `site_logs`; WordPress lane:
`list_blueprints`, `create_wp_site`, `wp_cli`, `wp_credentials`,
`wp_reset_password`.

## 3. Hosted MCP (no install)

The gateway serves Streamable HTTP MCP at `https://agents.rapadura.net/mcp`
with a bearer token. Get a token with `rapadura login` on any machine, or ask
the owner for one, then:

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

On the hosted lane `publish_site` takes files inline (`files: [{path, content}]`,
base64 for binaries) since the gateway cannot read your disk. OAuth sign-in for
clients that cannot send headers (claude.ai connectors) is planned; see
[en/roadmap.md](en/roadmap.md).

## What an agent should know

- A site is `slug.zone`. Slugs are lowercase letters, digits and single
  hyphens. A bare slug means the first zone, `rapadura.net`.
- `publish_site` with `create=true` is the one-step path for a new site.
- Every write returns a receipt built from reading the system back. Report
  `live_url` and the version number to the person; do not claim success from
  the request alone.
- The first HTTPS visit to a new hostname can take a few seconds while the
  certificate is issued.
- Deletion is soft and reversible by the owner, but ask the person before
  calling `delete_site`.
- Nothing server-side runs on the static lane. If a site needs PHP or a
  database, use the WordPress lane: `create_wp_site` / `rapadura wp create`
  gives a subsite on rapadura.net with an application password for the REST
  API, and `wp_cli` / `rapadura wp <site> -- …` runs policy-filtered wp-cli
  pinned to that site. Details: [en/wordpress.md](en/wordpress.md).