MCP server for LLM agents

Cloudomation ships a built-in MCP (Model Context Protocol) server. It lets your own LLM agents (Claude, Cursor, OpenAI agents, and any other MCP-compatible client) use Cloudomation as one tool among others to create, run and monitor automation content.

The MCP server is served by your workspace, so there is nothing extra to deploy.

Endpoint

https://<your-workspace>.cloudomation.com/api/latest/mcp

The server uses the MCP Streamable HTTP transport. All interaction happens as request/response over POST.

Authentication

Agents authenticate with an API key on every request, sent either as a bearer token or via a dedicated header:

Authorization: Bearer cldm_<prefix>_<secret>

or

x-cloudomation-api-key: cldm_<prefix>_<secret>

The same API key also works against the full REST API and the GraphQL API.

Creating an API key

1. Open the Cloudomation Engine UI and go to the user you want the agent to act as (see "Scoping access" below).
2. In the user's detail page, find the API keys (MCP / programmatic access) section.
3. Click Create API key, give it a descriptive name, and copy the key. The key is shown only once.

API keys can also be minted via the REST API:

curl -X POST \
  -H "x-cloudomation-session-id: <your-session-id>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude agent", "user_id": "<agent-user-id>"}' \
  https://<your-workspace>.cloudomation.com/api/latest/api_key

The response contains the plaintext token. Revoke a key with DELETE /api/latest/api_key/{id} or from the UI.

Scoping access (RBAC)

An API key is bound to a Cloudomation user identity and inherits exactly that user's permissions. To give an agent fine-grained access:

1. Create a dedicated user for the agent (for example claude-agent).
2. Create a role with role_permission entries scoped to the specific projects, record types and operations the agent should be allowed to use (for example: READ/CREATE/UPDATE on FLOW and EXECUTION in a single project).
3. Assign the role to the agent user.
4. Mint an API key for the agent user.

Because every MCP tool call runs through the same permission checks as the REST API, the agent can only ever see and change what the bound user is allowed to. If a tool call fails with a permission error, the bound user is missing a role.

Connecting a client

Most MCP clients accept a remote server URL plus custom headers. For example, a generic configuration looks like:

{
  "mcpServers": {
    "cloudomation": {
      "url": "https://<your-workspace>.cloudomation.com/api/latest/mcp",
      "headers": {
        "Authorization": "Bearer cldm_<prefix>_<secret>"
      }
    }
  }
}

Refer to your client's documentation for the exact configuration format. MCP prompts defined in your workspace appear in the client's prompt picker (slash commands) once the server supports the prompts capability.

Available tools

The server exposes the following tools (discoverable via MCP tools/list):

Tool	Description
list_projects	List projects the API key can access.
list_flows	List flows, optionally filtered by project.
get_flow	Get a flow including its Python script.
create_flow	Create a new flow.
update_flow	Update an existing flow (for example its script).
run_flow	Start an execution of a flow.
get_execution	Get the status, message and output of an execution.
get_execution_logs	Get the log entries of an execution.
list_executions	List executions newest-first, filtered by flow and/or status.
list_record_types	List the record types that exist (FLOW, SETTING, WRAPPER, ...).
list_records	List records of a given record type, with an optional name wildcard.
list_connectors	List configured connectors.
list_record_metadata	List metadata rows on a record.
get_record_metadata	Read one metadata key on a record.
set_record_metadata	Create or update one metadata key on a record.
delete_record_metadata	Delete one metadata key on a record.
memory_recall	Read the agent's durable, per-user memory.
memory_remember	Store/update entries in the agent's durable memory.
memory_forget	Remove entries from the agent's durable memory.

Listing parameters

All list_* tools share a common set of optional parameters:

Parameter	Description
fields	List of field names to return (each tool has a sensible default set).
order	Order by a field; - descending, + ascending (e.g. -created_at). Defaults to -modified_at, or -created_at for list_executions.
filter_	Extra filter, AND-combined with the tool's own filters. A {"field","op","value"} comparison or an {"and":[...]} / {"or":[...]} of such. Ops: eq, neq, like, notlike, lt, gt, lte, gte, set, unset, in, notin.
limit / offset	Page through large result sets.

To check the status of a flow's runs, use list_executions with flow_id or flow_name (optionally status): it returns status, message and timestamps directly and is ordered newest-first, so the latest run is the first result.

Resources (discovery and typings)

The server exposes MCP resources so an agent can learn how to use Cloudomation and author correct flows:

Resource URI	Contents
cloudomation://usage-guide	How to connect, authenticate and author flows.
cloudomation://connector-types	The available connector types and a description of each.
connector-type://<TYPE>	The description and input/output JSON schemas of one connector type (e.g. connector-type://REST).
flow_api://<module>	The flow_api typings (one per module), with full docstrings.

The flow_api typings are the authoritative type definitions for the system and this objects and all resource classes. An agent should read them before writing or editing a flow script. They are also available over REST at:

GET https://<your-workspace>.cloudomation.com/api/latest/flow_api/typings

record_metadata configuration

Several MCP features store configuration in record_metadata (JSON attached to a record by key). Agents maintain them with list_record_metadata / get_record_metadata / set_record_metadata / delete_record_metadata.

The workspace record id is included in the MCP server's initialize instructions and in the cloudomation://usage-guide resource (section "This workspace"). Use that id as record_id for workspace-level metadata keys.

Key	Record	Purpose
agent_memory	bound user	Per-agent memory — use memory_* tools only
agent_instructions	workspace	Free-form guidance appended to MCP initialize
mcp_prompt:<slug>	workspace	MCP prompt template (slug: [a-z][a-z0-9_-]*)

Example: set workspace instructions (via agent or REST) with key agent_instructions and data as a string or {"text": "..."}.

MCP prompts (customer workflows)

The server exposes MCP prompts so users can start repeatable agent tasks from their client (slash-command style). There are no built-in prompts — you define your own on the workspace as record_metadata keys mcp_prompt:<slug>.

Example prompt data object:

{
  "title": "Check integration test status",
  "description": "Summarize the latest run-integrationtest executions.",
  "arguments": [
    {
      "name": "flow_name",
      "description": "Orchestrator flow name",
      "required": false
    }
  ],
  "template": "Check integration test status on this workspace.\n\n1. list_executions(flow_name=\"{{flow_name}}\", limit=10)\n2. Summarize running/failed runs and link to failing child executions.\n\nDefault flow_name: run-integrationtest"
}

Use template (one user message) or a messages array (role + text per item). Placeholders {{argument_name}} are filled when the user runs the prompt.

Example templates worth creating (not shipped by Cloudomation):

• integrationtest-status — monitor a test orchestrator flow (as above).
• investigate-execution — required argument execution_id; pull status, logs, failure summary.
• onboard-workspace — list projects, flows and connectors; produce a short workspace map.

Create and update prompts with set_record_metadata on the workspace record; remove with delete_record_metadata. The MCP client lists them via prompts/list.

Agent memory

The server gives each agent a small, durable, per-user memory so it can reuse findings across sessions (for example the name of a flow it looks up often). Agents read it with memory_recall, write entries with memory_remember and prune them with memory_forget.

Memory is stored under agent_memory on the bound user's record. Do not write that key via set_record_metadata. Memory is a best-effort cache: agents should re-verify facts when correctness matters and remove obsolete entries with memory_forget.

Instructions for agents

You can give agents additional guidance in three ways:

• Workspace-level instructions — metadata key agent_instructions on the workspace (delivered automatically in MCP initialize).
• MCP prompts — metadata keys mcp_prompt:<slug> (user-invoked workflows).
• Record descriptions — a flow or project description may contain agent-directed notes, but may also be ordinary documentation; agents treat clearly operational guidance as advisory only.

Instructions never widen what the API key is allowed to do; RBAC always applies.

Local editor IntelliSense & linting

The MCP flow_api:// resources are for agents. A local editor's Python language server (Pyright / Pylance / mypy) does not read MCP resources - it analyses files on disk or installed packages. To get autocompletion and linting while editing flow scripts locally, download the typings (which are generated per workspace and per version) into a local stub directory:

curl -sS -H "Authorization: Bearer $CLOUDOMATION_API_KEY" \
  https://<your-workspace>.cloudomation.com/api/latest/flow_api/typings \
| python -c "import json,sys,pathlib; \
d=json.load(sys.stdin)['files']; \
out=pathlib.Path('typings/flow_api'); out.mkdir(parents=True, exist_ok=True); \
[ (out/name).write_text(src) for name, src in d.items() ]"

Then point your editor at the typings directory:

• VS Code / Pylance: "python.analysis.extraPaths": ["typings"] (or "python.analysis.stubPath": "typings").
• Pyright: "extraPaths": ["typings"] in pyrightconfig.json.
• mypy: run with MYPYPATH=typings.

Re-run the download after upgrading your workspace so the typings stay in sync. The downloaded flow_api package is for static analysis only - flow scripts execute inside the Cloudomation workspace, not in your local interpreter.

Flow authoring contract

A flow is a Python module that defines a handler function:

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution, inputs: dict):
    # automation logic
    return this.success('done')

• system is the gateway to the workspace.
• this is the running execution.
• inputs is a dict validated against the flow input schema.

See the flow_api reference for the full API.