> ## 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.

# Connect over MCP

> Connect any MCP client to Cactal's remote MCP server at https://api.cactal.ai/v1/mcp with OAuth or an API key, agent-safe platform tools, setup examples, and a first-session walkthrough.

Cactal hosts a remote MCP server that exposes agent-safe platform operations as tools. There is nothing to install and no local proxy to run: point your client at the endpoint, authorize Cactal, and start working.

## Server

| Property                         | Value                                                  |
| -------------------------------- | ------------------------------------------------------ |
| Endpoint                         | `POST https://api.cactal.ai/v1/mcp`                    |
| Transport                        | Streamable HTTP                                        |
| Sessions                         | Stateless — no session ids; every request stands alone |
| Responses                        | JSON                                                   |
| `GET` / `DELETE` on the endpoint | `405`                                                  |

## Authentication with OAuth

OAuth is the recommended path for interactive MCP clients. Add the server URL without headers; a compatible client discovers Cactal's authorization server, registers itself, opens the Cactal sign-in and consent screens, and refreshes access automatically:

```text theme={null}
https://api.cactal.ai/v1/mcp
```

OAuth access tokens are JWTs bound to this exact MCP resource. The connection acts as your Cactal user, so `tools/list` and tool calls use the organization and website grants already attached to your account.

For unattended clients, CI, or clients without OAuth support, API keys remain available:

```text theme={null}
Authorization: Bearer $CACTAL_API_KEY
```

Browser session cookies are always rejected with `401`; the MCP server accepts only bearer OAuth tokens or bearer API keys. An API key's access scope decides which organizations and websites it can reach. Create one in the dashboard or with `POST /v1/apiKeys` — see [Create an API key](/docs/create-an-api-key) and [Authentication](/docs/api-reference/authentication).

## Connect a client

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport http cactal https://api.cactal.ai/v1/mcp
  ```

  ```json Cursor (.cursor/mcp.json) theme={null}
  {
    "mcpServers": {
      "cactal": {
        "url": "https://api.cactal.ai/v1/mcp"
      }
    }
  }
  ```

  ```json Generic Streamable HTTP client theme={null}
  {
    "type": "http",
    "url": "https://api.cactal.ai/v1/mcp",
    "headers": {
      "Authorization": "Bearer $CACTAL_API_KEY"
    }
  }
  ```
</CodeGroup>

<Note>
  The generic example shows the API-key fallback. Replace `$CACTAL_API_KEY` with your key, or use your client's secret storage so it never lands in a committed file.
</Note>

<Check>
  Verify the connection by asking your agent to list its Cactal tools.
</Check>

## Tools

The server generates tools from agent-safe public API operations. A tool's name is the operation id with every character outside `a-z`, `A-Z`, `0-9`, `_`, and `-` replaced by `_`:

| Operation id                     | Tool name                        |
| -------------------------------- | -------------------------------- |
| `websites.create`                | `websites_create`                |
| `cms.items.setPublished`         | `cms_items_setPublished`         |
| `websiteSourceCode.head.publish` | `websiteSourceCode_head_publish` |
| `websiteFavicons.set`            | `websiteFavicons_set`            |

Each tool's input schema is the operation's request schema, and its metadata carries the HTTP method, path, and required capability. A tool's title and description are the same authored prose as its [API reference](/docs/api-reference/introduction) operation, so the two surfaces cannot drift apart. `tools/list` returns only the tools the authenticated user or key can access. Calling a tool outside that access fails as if the tool does not exist.

The server also returns usage instructions in the `initialize` response: the platform's mental model, the draft-then-publish workflow, and where to read further. Clients that support MCP instructions surface them to the agent automatically.

### Product feedback

When the user explicitly asks to send Cactal product feedback, an authenticated MCP principal can use `feedback_submit`. Briefly describe what happened and what would have made the experience better. An agent must pass `authorKind: "agent"` even when its OAuth connection acts as the signed-in user; Cactal stores the authenticated principal, authored-by kind, and MCP channel separately. Feedback must never contain secrets or unnecessary sensitive data. See [Submit product feedback](/docs/agents/product-feedback).

### Documentation operations

The public API includes two authenticated, read-only documentation operations. Like every other public operation, they are available over REST and automatically appear as MCP tools:

| HTTP                            | MCP tool      | Purpose                                                                                                               |
| ------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/docs/search?query=...` | `docs_search` | Search this documentation; returns matching excerpts with page paths                                                  |
| `GET /v1/docs/read?path=...`    | `docs_read`   | Read one docs page as Markdown by path, for example `concepts/publishing`; pass `llms.txt` for an index of every page |

They serve the published documentation, the same content as every surface in [AI-readable docs](/docs/agents/ai-readable-docs), so an agent connected only to the product MCP can read the relevant docs before acting.

### Asset library

`websiteAssets_list` accepts `search` and `category` filters over each asset's
one-line description and category, so an agent can find "the logo" or "the
team photo" without opening every file. When an agent uploads through
`websiteAssets_beginUpload` or imports through `websiteAssets_import` it should
pass `description` and `category` itself;
`websiteAssets_update` fixes them later. Reading an image with
`websiteAssets_get` returns the picture itself to clients that render images,
the same view the built-in Cactal agent gets. `websiteAssets_removeBackground`
derives a new transparent PNG from a ready image and returns it, picture
included; `transparentShare` on any image row confirms real transparency.

### Image generation

Website content editors can use `mediaGeneration_catalog` and
`mediaGeneration_generate` to create up to eight images in one concurrent batch.
Generation can use ready same-website images as references. Successful outputs
are ordinary CDN-backed website assets, and compatible clients receive visual
image content alongside the structured result. See [Generate website
images](/docs/guides/generate-images).

## Errors, rate limits, and audit

A failed tool call returns a result with `isError: true`. Its payload is the same error shape the REST API uses:

```json Tool result payload on failure theme={null}
{ "kind": "not_found", "message": "Website not found" }
```

The `kind` values and their meanings match the REST API exactly — see [Errors](/docs/api-reference/errors). Rate limits are shared with REST for the same principal, and an exhausted bucket returns `kind: "rate_limited"` with `retryAfterSeconds`. See [Rate limits](/docs/api-reference/rate-limits).

Tool calls run through the same audit pipeline as REST. Operations that write organization audit events — website lifecycle, editor grants, API keys, domains, and members — write identical events over MCP, attributed to the OAuth user or API key. Financial transactions remain dashboard or REST operations and are not exposed through MCP. Review agent actions with `GET /v1/organizations/{organizationId}/audit-log`.

## Your first session

The steps below sketch the JSON-RPC calls your client makes. MCP clients perform the standard `initialize` handshake automatically before these requests — in a client, just ask the agent in plain language and it makes the same calls.

<Steps>
  <Step title="List the available tools">
    ```bash theme={null}
    curl https://api.cactal.ai/v1/mcp \
      -H "Authorization: Bearer $CACTAL_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
    ```

    The response lists tools such as `organizations_list`, `websites_create`, and `websiteSourceCode_head_publish`.
  </Step>

  <Step title="Create a website">
    Call `organizations_list` first if you do not know your organization id, then:

    ```bash theme={null}
    curl https://api.cactal.ai/v1/mcp \
      -H "Authorization: Bearer $CACTAL_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"websites_create","arguments":{"organizationId":"V1StGXR8Z5jdHi6BmyTxQ","name":"Acme Marketing"}}}'
    ```

    The result is the website record, including its `id` and draft `headVersion`.
  </Step>

  <Step title="Check, then publish">
    After the agent edits the draft (acquiring the edit lease with `websiteSourceCode_lease_acquire` first), run the quality gate with `websiteSourceCode_head_check`, then publish with `websiteSourceCode_head_publish`, passing the `websiteId` and the `leaseToken`. Poll `websiteSourceCode_deployment_status` until the deployment reaches `ready`.
  </Step>

  <Step title="Set the favicon">
    Upload and finalize a PNG, SVG, or ICO image with `websiteAssets_beginUpload` and `websiteAssets_finalize`, or import one from a public URL with `websiteAssets_import`, then call `websiteFavicons_set` with its `assetId`. If the user already uploaded it, find the recent ready image with `websiteAssets_list` first. This is current website state, so it applies immediately and needs no source lease or publish.
  </Step>

  <Step title="Open the website">
    Call `websiteDomains_list` to find the website's platform host, `https://<label>.cactal.app`, and open it.
  </Step>
</Steps>

<Note>
  Publishing and serving on a Cactal platform domain is 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>

Before handing an agent real publish authority, read [Agent-safe publishing](/docs/agents/agent-safe-publishing).