> ## Documentation Index
> Fetch the complete documentation index at: https://cactal.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring your own agent

> Cactal is agent-native: agent-safe platform operations are available over MCP and the complete public API is available over REST. Agents can create websites, edit source, manage content, publish, and operate domains and analytics while scoped access, drafts, and the audit log keep you in control.

Cactal treats agents as first-class operators, not a bolt-on integration. The built-in [Cactal agent](/docs/agents/cactal-agent) is already docked in every site's studio with no setup; this page is for bringing an agent of your own. The [MCP server](/docs/agents/mcp) exposes agent-safe public operations as tools, while REST remains the complete programmatic interface. Financial transactions stay in the dashboard or REST API rather than MCP.

Connect Claude, Claude Code, Cursor, ChatGPT, Codex, or any other MCP client with OAuth. Agents that prefer raw HTTP can use the REST API with an API key.

## One platform, three interfaces

Every operation runs through the same authorization, rate limits, and audit pipeline, whichever interface invokes it.

| Interface | Entry point                            | Authentication                          |
| --------- | -------------------------------------- | --------------------------------------- |
| Dashboard | [app.cactal.ai](https://app.cactal.ai) | Browser session                         |
| REST API  | `https://api.cactal.ai/v1`             | `Authorization: Bearer $CACTAL_API_KEY` |
| MCP       | `POST https://api.cactal.ai/v1/mcp`    | OAuth (recommended) or bearer API key   |

The interfaces share one operation vocabulary. `websites.create` is the operation behind the dashboard's create button, the `POST /v1/websites` endpoint, and the `websites_create` MCP tool.

## What an agent can do end to end

An agent holding a suitably scoped API key can run the full website lifecycle without a human touching the dashboard.

* **Create a website** — `POST /v1/websites` creates a website in your organization with a draft head version.
* **Edit source code**: acquire an edit lease with `POST /v1/websiteSourceCode/lease/acquire`, then write pages, components, reusable modules, global CSS, and custom head or body snippets with `PUT /v1/websiteSourceCode/files`. TypeScript source can also import pinned npm packages. See [Source code](/docs/concepts/source-code).
* **Model and manage content** — create collections and fields, then create, publish, and query items through the `/v1/cms/*` endpoints. See [CMS](/docs/concepts/cms).
* **Upload assets and set the favicon** — `POST /v1/websiteAssets` begins a presigned upload with a one-line `description` and image `category` so the asset stays searchable; finalize it, then select it with `PUT /v1/websites/{websiteId}/favicon`. The favicon changes immediately on every site host and does not require publishing. See [Assets](/docs/concepts/assets).
* **See the result** — `POST /v1/websitePreview/capture` renders a page in a real browser and returns the image, so an agent without a browser can still check layout and responsive behavior. See [Preview drafts and versions](/docs/guides/preview-drafts-and-versions).
* **Publish** — validate the draft with `POST /v1/websiteSourceCode/head/check`, then ship it with `POST /v1/websiteSourceCode/head/publish`. See [Publishing](/docs/concepts/publishing).
* **Operate the live website** — add and verify custom domains, read analytics, and roll back with `POST /v1/websiteSourceCode/published/rollback-version` when needed. See [Domains](/docs/concepts/domains).

<Note>
  Drafts, publishing, platform-domain serving, and the full API are available on every plan, including Free. A site counts toward your plan when an organization owner enables custom domains for it. Sites on Cactal domains are unlimited and free. See [Plans and limits](/docs/platform/plans-and-limits).
</Note>

### A concrete run

The same lifecycle, named in both interfaces. An agent on MCP and a script on REST perform identical operations.

| Step                      | REST                                           | MCP tool                              |
| ------------------------- | ---------------------------------------------- | ------------------------------------- |
| Create the website        | `POST /v1/websites`                            | `websites_create`                     |
| Acquire the edit lease    | `POST /v1/websiteSourceCode/lease/acquire`     | `websiteSourceCode_lease_acquire`     |
| Write a page              | `PUT /v1/websiteSourceCode/files`              | `websiteSourceCode_files_upsert`      |
| Set the favicon           | `PUT /v1/websites/{websiteId}/favicon`         | `websiteFavicons_set`                 |
| Run the quality gate      | `POST /v1/websiteSourceCode/head/check`        | `websiteSourceCode_head_check`        |
| Look at the rendered page | `POST /v1/websitePreview/capture`              | `websitePreview_capture`              |
| Publish                   | `POST /v1/websiteSourceCode/head/publish`      | `websiteSourceCode_head_publish`      |
| Confirm the deployment    | `POST /v1/websiteSourceCode/deployment/status` | `websiteSourceCode_deployment_status` |

## The human stays in control

Agent access is broad by design, so the platform bounds it with three mechanisms you configure once and audit continuously.

### Scoped API keys

A key carries explicit access: the whole organization or a fixed list of websites, with a role of `admin`, `full_editor`, or `content_editor`. The `owner` role is not grantable to keys. The MCP server even filters `tools/list` to what the key can call, so an agent never sees operations it cannot use. See [Access control](/docs/concepts/access-control).

OAuth connections instead inherit the signed-in user's existing organization and website grants. Use OAuth for interactive clients and a narrowly scoped API key for unattended automation.

### Draft-first editing

Source edits land on the website's head, the draft version. Nothing reaches the live website until an explicit publish, and you can review the draft on its preview URL first. A wrong draft costs nothing: discard it with `POST /v1/websiteSourceCode/head/restore` and `{ "to": "published" }`.

### The audit log

Lifecycle and access operations — websites, editors, API keys, domains, members, billing — write organization audit events with actor attribution, so agent actions are distinguishable from human actions. Filter `GET /v1/organizations/{organizationId}/audit-log` by `actorKind=api_key` to review them, and review content work through the changed-file list, targeted diffs, and preview. [Agent-safe publishing](/docs/agents/agent-safe-publishing) turns these mechanisms into a working process.

## Set up your agent

<Columns cols={2}>
  <Card title="Connect over MCP" icon="plug" href="/docs/agents/mcp">
    Endpoint, authentication, client setup for Claude Code, Cursor, and generic MCP clients, and a first-session walkthrough.
  </Card>

  <Card title="Agent-safe publishing" icon="shield-check" href="/docs/agents/agent-safe-publishing">
    Scope keys, keep work on drafts, gate publishes on checks and human approval, watch the audit log, and recover fast.
  </Card>

  <Card title="AI-readable docs" icon="file-text" href="/docs/agents/ai-readable-docs">
    llms.txt, Markdown variants of every page, and the docs-search MCP server — how agents read this documentation.
  </Card>

  <Card title="Submit product feedback" icon="message-square-warning" href="/docs/agents/product-feedback">
    Send a report to Cactal when the user explicitly asks you to share product feedback.
  </Card>

  <Card title="Create an API key" icon="key" href="/docs/create-an-api-key">
    Create a scoped credential for REST clients and unattended MCP automation.
  </Card>
</Columns>