Connect over MCP

Cactal hosts a remote MCP server that exposes 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. Using Cactal from a chat in ChatGPT or Claude? Start with Use Cactal in ChatGPT and Claude.

Endpoints

Endpoint	URL	Use it for
Default	`https://api.cactal.ai/v1/mcp`	Working on websites: build, edit, publish, content, images, domains, forms, server functions, analytics, and project knowledge. ChatGPT and Claude connect here.
Full access	`https://api.cactal.ai/v1/mcp/full`	Every public operation, including account administration. See Advanced: full access.

Both endpoints behave the same way at the protocol level:

Property	Value
Transport	Streamable HTTP, `POST` to the endpoint URL
Sessions	Stateless: no session ids; every request stands alone
Responses	JSON
`GET` / `DELETE` on the endpoint	`405`

Authentication

OAuth

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

https://api.cactal.ai/v1/mcp

Sign in with Google, an email code, or email and password. If you create your Cactal account during this step, Cactal sets up your first organization before you choose what to connect. On the consent screen for the default endpoint, Access chooses which organizations and websites the connection can use, starting at All websites. The connection never does more than you can; see AI connections for exactly what it can use and how to change it. The consent screen also shows who is asking; Security explains which apps appear as verified. Continue with an unverified app only if you just started the connection yourself and trust the app. Each endpoint is its own OAuth protected resource:

	Default	Full access
Resource	`https://api.cactal.ai/v1/mcp`	`https://api.cactal.ai/v1/mcp/full`
Protected resource metadata	`https://api.cactal.ai/.well-known/oauth-protected-resource/v1/mcp`	`https://api.cactal.ai/.well-known/oauth-protected-resource/v1/mcp/full`
Scope	`mcp`	`mcp:full`

Clients request offline_access as well to receive refresh tokens. Access tokens are signed JWT access tokens (typ: at+jwt) with the Cactal authorization server as issuer and the endpoint’s URL as their exact audience, so a token issued for one endpoint is rejected by the other. Cactal session tokens are never accepted as MCP tokens.

Disconnect

Disconnect an app under Connected apps in Account settings; its next call fails. See AI connections.

API keys

For unattended clients, CI, or clients without OAuth support, send an API key on either endpoint:

Authorization: Bearer $CACTAL_API_KEY

The key’s own access scope decides which organizations, websites, and tools it can reach. Create one in the dashboard or with POST /v1/apiKeys. See Create an API key and Authentication. Browser session cookies are always rejected with 401; the MCP endpoints accept only bearer OAuth tokens or bearer API keys.

Connect a client

Claude and ChatGPT

See Use Cactal in ChatGPT and Claude.

Claude Code, Cursor, and other clients

If you connected Cactal in Claude, Claude Code already has it. Otherwise, add the server to your client:

claude mcp add --transport http cactal https://api.cactal.ai/v1/mcp

{
  "mcpServers": {
    "cactal": {
      "url": "https://api.cactal.ai/v1/mcp"
    }
  }
}

{
  "type": "http",
  "url": "https://api.cactal.ai/v1/mcp",
  "headers": {
    "Authorization": "Bearer $CACTAL_API_KEY"
  }
}

The generic example shows the API-key option. Replace $CACTAL_API_KEY with your key, or use your client’s secret storage so it never lands in a committed file.

Verify the connection by asking your agent which Cactal organizations and websites it can use. It answers with profile_get.

Tools

Tools are generated from 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 operation, so the two surfaces cannot drift apart. tools/list returns only the tools the connection or key can call. Calling a tool outside that access fails as if the tool does not exist. The initialize response carries short server instructions that point the agent to skills_read, profile_get, and the docs tools. Clients that support MCP instructions surface them to the agent automatically.

What the default endpoint includes

Area	Tools
Orientation	`profile_get`, `skills_read`, `docs_search`, `docs_read`, `feedback_submit`
Websites	`websites_list`, `websites_get`, `websites_create`, `websites_rename`
Source code and publishing	Every `websiteSourceCode_*` tool: summary, file list, read, search, and diff, changed-file list, file writes and deletes, route and metadata edits, head check, publish, head restore, rollback, unpublish, deployment status and ensure, and lease acquire; plus `websitePreview_capture`
CMS	`cms_schema_snapshot`; collection and field create, update, and delete; item list, get, backreferences, create, update, setPublished, delete, and restore
Assets and images	`websiteAssets_list`, `_get`, `_importFromUrl`, `_update`, `_removeBackground`, `_delete`; `mediaGeneration_catalog`, `mediaGeneration_generate`; `websiteFavicons_set`
Domains	`websiteDomains_list`, `_createCustomDomain`, `_verifyCustomDomain`, `_setPrimaryDomain`, `_removeCustomDomain`, `_renamePlatformDomain`
Forms	`websiteForms_list`; submission list, get, setStatus, and delete; recipient add, remove, and resendConfirmation
Server functions	`websiteFunctions_invoke`, `_runs_list`, `_runs_get`; `websiteSecrets_list` (names only; values are set in the dashboard)
Analytics	`websiteAnalytics_query_get`, `_timeseries_get`, `_realtime_get`
Project knowledge	`websiteKnowledge_project_get`, `_project_edit`, `_agentNotes_edit`, `_list`, `_create`, `_update`, `_read`, `_search`, `_view`
Outside Cactal	`webResearch_screenshot`, `webResearch_probe`, `webResearch_profile`, `webResearch_viewImage`

The default endpoint never includes account administration: API keys, members, invitations, website editors, billing, the audit log, organization lookups, settings, and deletion, website delete, restore, and transfer, or presigned uploads (websiteAssets_beginUpload and websiteAssets_finalize). Agents on the default endpoint import files by URL with websiteAssets_importFromUrl and find their organization with profile_get. Everything else is on the full-access endpoint and the REST API.

Docs, skills, and profile

These read-only operations are available over REST and as MCP tools on both endpoints:

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
`GET /v1/skills/{skillId}`	`skills_read`	Read one of Cactal’s agent skills, together with the skills it requires
`GET /v1/profile`	`profile_get`	Name the person behind the credential and the organizations it can work in

The docs operations serve the published documentation, the same content as every surface in AI-readable docs.

Skills

skills_read returns Cactal’s guidance for agents: the same skills the built-in Cactal agent uses, covering platform rules, the tool workflow, and craft defaults such as design direction, copywriting, CMS modeling, and publishing. The tool’s description lists every skill, and the server instructions tell agents to read the matching skill before acting, for example source-editing-workflow before any source edit. The skills always match the tools you see, because the server serves them. For agents that find Cactal on the web, https://cactal.ai/skill.md and https://cactal.ai/.well-known/agent-skills/index.json point to the MCP server and skills_read in the Agent Skills discovery format.

Outside Cactal

Agents can look at the web beyond your sites the way the built-in Cactal agent does. Each call names one of your websites; that website’s organization pays in AI credits for the vendor work behind it.

MCP tool	Purpose
`webResearch_screenshot`	Screenshot a public page, for example a reference site the user likes
`webResearch_probe`	Measure a public page with presets: design tokens, every image, or head metadata
`webResearch_profile`	Read a business’s own pages (site, Google listing, Instagram, Yelp, and others) into a profile, optionally with its photos on numbered contact sheets
`webResearch_viewImage`	Look at up to 48 public images; more than four come back on numbered contact sheets

A contact-sheet photo can be imported into the website by its number: pass { "photo": 12 } in websiteAssets_importFromUrl instead of copying the long image link. Numbers belong to the connection that saw them and last at least 24 hours. Agents should request a business’s photos (images: true) only when the user confirmed the business is theirs, and ask before importing from a site that is not theirs.

Profile

profile_get returns the person the credential acts for (a stable id, plus name and email) and the organizations it can work in. An organization lists websites only when access is limited to those websites. Pass an organization id to websites_list or websites_create.

Edit leases

Source writes run under the website’s single edit lease, and Cactal takes it for you when a write has no leaseToken. If another editor is mid-change, the write fails with a conflict; ask the user before taking over with websiteSourceCode_lease_acquire.

Publish what you checked

websiteSourceCode_head_publish accepts an optional version. Pass the version websiteSourceCode_head_check returned; if the draft changed after that check, publishing refuses with a conflict (The draft changed after it was checked), so a draft nobody checked never goes live.

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 imports through websiteAssets_importFromUrl, or uploads through websiteAssets_beginUpload on the full-access endpoint, 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. idempotencyKey is optional: send the same key when retrying one request so it never generates or bills twice, and omit it for a new request. See Generate website images.

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.

Approvals

Cactal tools carry MCP annotations so ChatGPT, Claude, and other hosts can decide when to ask the user before a tool runs. Cactal adds no approval step of its own over MCP; the host’s approval settings apply.

Annotation	Applies to
Read-only	Every read. Hosts typically run these without asking.
Destructive	Anything that changes or removes live content, deletes, or overwrites without keeping a version: publish, unpublish, rollback, head restore, source file delete, CMS item update, publish, delete, and restore, CMS field and collection changes, domain removal, primary domain and platform domain changes, favicon changes, form submission delete, recipient removal, server function test calls, and project knowledge edits and file updates.
Not destructive	Draft source edits (`websiteSourceCode_files_upsert`, `websiteSourceCode_files_strReplace`, `websiteSourceCode_pages_editRoute`, `websiteSourceCode_metadata_edit`). Each creates a new draft version, keeps every earlier version, and never touches the live site.
Open world	Anything that publishes to the public web, fetches an arbitrary URL, or emails people outside the organization.

The built-in Cactal agent still pauses for an in-conversation approval before publishing or any other live change. For agents you run yourself, see Agent-safe publishing.

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:

Tool result payload on failure

{ "kind": "not_found", "message": "Website not found" }

The kind values and their meanings match the REST API exactly. See Errors. Rate limits are shared with REST for the same principal, and an exhausted bucket returns kind: "rate_limited" with retryAfterSeconds. See Rate limits. Tool calls run through the same audit pipeline as REST. Operations that write organization audit events, such as website lifecycle, editor grants, API keys, domains, and members, write identical events over MCP. Actions through an AI connection are attributed to the person who connected it, and actions through an API key to that key. Review them with GET /v1/organizations/{organizationId}/audit-log. Plan purchases and checkouts happen in the dashboard and are never available over MCP.

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.

Find your organization

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/call","params":{"name":"profile_get","arguments":{}}}'

The result lists the organizations the credential can work in, each with its id.

Create a website

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.

Read the matching skills

Call skills_read with source-editing-workflow before editing source, and with skills such as design-direction or copywriting when the agent chooses the look or the words.

Edit the draft

Write pages and components with websiteSourceCode_files_upsert or websiteSourceCode_files_strReplace, without a leaseToken. Cactal takes the edit lease for you, and every write becomes a new draft version.

Check, then publish

Run the quality gate with websiteSourceCode_head_check and note the version it returns. Publish with websiteSourceCode_head_publish, passing the websiteId and that version. Poll websiteSourceCode_deployment_status until the deployment reaches ready.

Set the favicon

Import a PNG, SVG, or ICO image from a public URL with websiteAssets_importFromUrl, then call websiteFavicons_set with its assetId. If the user already uploaded it, find the ready image with websiteAssets_list first. The favicon is current website state, so it applies immediately and needs no lease or publish.

Open the website

Call websiteDomains_list to find the website’s platform host, https://<label>.cactal.app, and open it.

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.

Before handing an agent real publish authority, read Agent-safe publishing.

Advanced: full access

https://api.cactal.ai/v1/mcp/full exposes every public operation with MCP support, including the account administration the default endpoint leaves out. Choose it only when an agent genuinely needs those operations; the default endpoint covers working on websites. Add it on purpose: as a custom connector in Claude, in ChatGPT developer mode, or in a Claude Code or Cursor config:

Claude Code

claude mcp add --transport http cactal-full https://api.cactal.ai/v1/mcp/full

A full-access connection acts as you across every organization you belong to, and its consent screen shows it as Full account access; see AI connections. API keys work on this endpoint too, limited by their own access scope.

Connect only apps you fully trust to the full-access endpoint. An API key created through it returns its secret in the tool result, so the secret stays in the conversation. Rotate any key that was exposed this way.

Get started

Core concepts

Guides

Build with agents

Platform

Connect over MCP

Endpoints

Authentication

OAuth

Disconnect

API keys

Connect a client

Claude and ChatGPT

Claude Code, Cursor, and other clients

Tools

What the default endpoint includes

Docs, skills, and profile

Skills

Outside Cactal

Profile

Edit leases

Publish what you checked

Asset library

Image generation

Product feedback

Approvals

Errors, rate limits, and audit

Your first session

Advanced: full access

​Endpoints

​Authentication

​OAuth

​Disconnect

​API keys

​Connect a client

​Claude and ChatGPT

​Claude Code, Cursor, and other clients

​Tools

​What the default endpoint includes

​Docs, skills, and profile

​Skills

​Outside Cactal

​Profile

​Edit leases

​Publish what you checked

​Asset library

​Image generation

​Product feedback

​Approvals

​Errors, rate limits, and audit

​Your first session

​Advanced: full access

Endpoints

Authentication

OAuth

Disconnect

API keys

Connect a client

Claude and ChatGPT

Claude Code, Cursor, and other clients

Tools

What the default endpoint includes

Docs, skills, and profile

Skills

Outside Cactal

Profile

Edit leases

Publish what you checked

Asset library

Image generation

Product feedback

Approvals

Errors, rate limits, and audit

Your first session

Advanced: full access