Server
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: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:
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 and Authentication.
Connect a client
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.Verify the connection by asking your agent to list its Cactal tools.
Tools
The server generates tools from agent-safe public API operations. A tool’s name is the operation id with every character outsidea-z, A-Z, 0-9, _, and - replaced by _:
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 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 usefeedback_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.
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:
They serve the published documentation, the same content as every surface in 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 usemediaGeneration_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.
Errors, rate limits, and audit
A failed tool call returns a result withisError: true. Its payload is the same error shape the REST API uses:
Tool result payload on failure
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 — 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 standardinitialize handshake automatically before these requests — in a client, just ask the agent in plain language and it makes the same calls.
1
List the available tools
organizations_list, websites_create, and websiteSourceCode_head_publish.2
Create a website
Call The result is the website record, including its
organizations_list first if you do not know your organization id, then:id and draft headVersion.3
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.4
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.5
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.