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:

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.

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:

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:

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.

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.