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
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.
wait_for_executions	Block until one or more executions end, then return their details.
list_executions	List executions newest-first, filtered by flow and/or status.
list_record_types	List record types (FLOW, PROJECT, CONNECTOR, …).
list_subrecord_types	List subrecord types (OBJECT_TEMPLATE_ATTRIBUTE, RECORD_METADATA, …).
describe_record_type	JSON Schemas and field lists for a record type.
describe_subrecord_type	JSON Schemas and field lists for a subrecord type.
list_records	List records of one type (uses that type's REST resource and filters).
list_subrecords	List subrecords of one type, scoped to a parent record.
get_record	Get one record by id or name.
get_subrecord	Get one subrecord row by id.
create_record	Create a record of any type.
update_record	Patch a record.
delete_record	Delete a record.
create_subrecord	Create a subrecord row (including RECORD_METADATA).
update_subrecord	Patch a subrecord row.
delete_subrecord	Delete a subrecord row.

Most workspace content is accessed through the generic record/subrecord tools. Dedicated execution tools (run_flow, list_executions, get_execution, get_execution_logs, wait_for_executions) remain for the common run-and-monitor workflow.

Read cloudomation://usage-guide for examples (listing projects/flows/connectors via list_records, metadata via RECORD_METADATA subrecords, type-specific filter_ fields).

Listing parameters

list_records, list_subrecords, and list_executions share optional listing 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 executions.
filter_	Extra filter on type-specific columns, AND-combined with convenience 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.

User tools

Built-in MCP tools let an agent maintain and monitor workspace content. User tools add a second class: domain-specific capabilities you define for agents (for example lookup_customer, provision_vm, run_monthly_report).

Each user tool is an MCP_USER_TOOL record that:

• exposes the record name as the MCP tool name in tools/list and tools/call
• uses the record description as the MCP tool description
• references a flow by flow_id (the implementation)
• takes argument schemas from that flow's input_schema (MCP inputSchema)
• returns the flow execution's output_value when the agent calls the tool

Configure user tools in the Engine UI under Create → Configuration → MCP user tool, or via the REST/GraphQL API and MCP record tools (list_records(record_type="MCP_USER_TOOL"), create_record, …).

How invocation works

When an agent calls a user tool:

1. Cloudomation creates a flow execution with input_value set to the tool arguments.
2. The MCP server waits until the execution finishes or reaches the tool's timeout_sec (default 300 seconds).
3. On success, the tool result contains output_value from the execution.
4. On failure or timeout, the result is an error that includes execution_id so the agent can inspect logs with get_execution / get_execution_logs or wait longer with wait_for_executions.

Define input_schema and output_schema on the flow, not on the tool record. Changing the flow updates the MCP contract on the next tools/list.

Example

1. Create a flow get-customer with an input_schema requiring customer_id and an output_schema describing the returned customer object.
2. Create an MCP user tool named lookup_customer pointing at that flow, add a description, set Enabled.
3. The agent sees lookup_customer in tools/list and can call it with {"customer_id": "C-42"} without knowing the underlying flow name.

Naming rules

• The tool name must be unique across the workspace (same rule as any record name).
• Names matching a built-in MCP tool (for example run_flow, list_records) are rejected when saving. Built-in tools always take precedence at runtime.
• Prefer descriptive names such as lookup_customer or provision_vm.

RBAC

The agent user's API key needs at least:

• READ on MCP_USER_TOOL (to list and invoke tools)
• CREATE and READ on EXECUTION
• READ on the referenced FLOW

Grant these via roles scoped to the relevant projects.

Real-world examples

User tool	Typical arguments	Flow implements
reset_user_password	{ "username": "alice" }	AD/LDAP reset and notification
check_server_health	{ "hostname": "app-01" }	Monitoring connectors, status summary
provision_environment	{ "template": "small-linux", "ttl_hours": 24 }	DevStack or internal provisioning
export_sales_summary	{ "from_date", "to_date", "region" }	Warehouse query and report output
integrationtest_status	{ "limit": 5 }	Wraps an existing test orchestrator flow

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://developer-artifacts	REST endpoints and layout for local editor typings and JSON Schemas.
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:

Endpoint	Description
GET /api/latest/flow_api/typings	flow_api Python typings (?format=zip for archive)
GET /api/latest/schemas/export	JSON Schemas for export YAML files
GET /api/latest/schemas/connectors	JSON Schemas for connector values
GET /api/latest/developer-artifacts	Index of all developer artifact endpoints

See Local editor setup for manual download and editor configuration. Agents should follow the Local editor setup (agent-driven) section in cloudomation://usage-guide when the user edits flows or Cloudomation YAML locally.

Metadata and MCP prompts

Key/value metadata on records (including workspace agent instructions and MCP prompt templates) is stored as RECORD_METADATA subrecords. Use list_subrecords(subrecord_type="RECORD_METADATA", parent_record_id="<record-id>") and the subrecord CRUD tools.

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 parent_record_id for workspace-level metadata.

Key	Parent record	Purpose
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 with create_subrecord(subrecord_type="RECORD_METADATA", payload={"record_id": "<workspace-id>", "key": "agent_instructions", "data": "..."}).

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 subrecords with 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 via list_records; produce a short workspace map.

Create and update prompts with create_subrecord / update_subrecord on RECORD_METADATA; remove with delete_subrecord. The MCP client lists them via prompts/list.

Instructions for agents

You can give agents additional guidance in three ways:

• Workspace-level instructions — RECORD_METADATA key agent_instructions on the workspace (delivered automatically in MCP initialize).
• MCP prompts — RECORD_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 setup (agents)

When the user edits flows or Cloudomation YAML locally, agents should read cloudomation://developer-artifacts and follow the Local editor setup (agent-driven) section in cloudomation://usage-guide to:

1. Download flow_api/typings, schemas/export, and schemas/connectors (prefer ?format=zip).
2. Extract into .cloudomation/ in the project root.
3. Merge .vscode/settings.json with python.analysis.extraPaths and yaml.schemas from the export manifest.

Tell the user to re-run setup after workspace upgrades.

For manual setup without an agent, see Local editor setup.

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.