The MCP server
Cascade has an MCP server, and it reads and writes. It ships on, at /mcp on the
same address as the API and the editor, and an agent that connects to it can do
what the person behind its key can do and nothing past that. There is no read
only mode to find your way round, because a server an agent can look at and not
touch is a status page, and you already have one of those.
83 tools, and every one of them is a route of the REST API. A call doesn’t go beside the route, it goes through it: the route’s own handler checks the permission, validates the body, makes the change and writes the audit row. Nothing was copied into the MCP server to drift, and nothing was left out of it to skip.
So what it means for you: if a workflow, a credential, a project or a person is something you can change from the editor, an agent holding your key can change it too, with your role’s limits, and the audit log says it was an agent and which one.
Connecting
Section titled “Connecting”Make a key. In the editor it is under your account, or with the API:
curl -s -X POST https://cascade.plant.example/api/v1/api-keys \ -H "X-CSRF-Token: $CSRF" -b cookies.txt -H 'Content-Type: application/json' \ -d '{"name":"line 4 agent","scopes":["*"],"days":30}'The token comes back once, and starts hlc_. A key does what its holder could do,
cut down to its scopes: give an agent ["workflow.read","execution.read"] and it
can look and not touch. A service account key (one project, one role, made by a
project admin) works the same way and is the right key for a standing integration.
Then point the client at /mcp and send the key as a bearer token. The
streamable HTTP transport is the one it speaks:
{ "mcpServers": { "cascade": { "type": "http", "url": "https://cascade.plant.example/mcp", "headers": { "Authorization": "Bearer hlc_..." } } }}A request with no key, a wrong one, a revoked or expired one, or one whose person has been switched off gets a 401 before it reaches a tool, and a key that is revoked in the middle of a session stops working at its next call.
The rules
Section titled “The rules”Permissions are the route’s. whoami says which projects the key can see and
its role in each. A tool the key may not use is refused with the route’s own
reason: 403 for a permission it lacks, 404 for something it can’t see, which is
the same answer the REST API gives. That is a decision, not a fault to route
round.
A write needs a reason. Every tool that changes something takes a reason,
and refuses without one. It is written to the audit log with your key and the
name your client gave itself.
Secrets stay put. No tool returns a credential’s secret field, to any key, and
a credential made over MCP has its secrets sealed in the vault as they arrive.
get_credential is the same non-secret view the edit form has.
The switches are the deployment’s. Two settings, in the environment the server starts in, nothing an API call or an agent can change:
| Setting | Default | What it does |
|---|---|---|
HOTLOOP_CASCADE_MCP |
true |
false and /mcp isn’t there. |
HOTLOOP_CASCADE_MCP_WRITES |
true |
false and every tool that changes anything refuses, and the ones that read still work. |
PATCH /settings doesn’t know either of them, so an agent that may edit the
settings still can’t switch writes back on.
It never writes to equipment. run_workflow starts a real run, and what its
steps do to the systems they call is up to the steps. Anything that moves a valve
or changes a setpoint goes through HotLoop’s write gate, so that gate’s audit sees
it whoever started the workflow.
What the audit log says
Section titled “What the audit log says”Two rows for a write. The route’s own row has the agent as its actor, with type
mcp, the key, whose it is and the client:
actor: mcp, "line 4 agent (ops@plant.example) via claude-desktop"action: workflow.createdAnd one row of the tool’s, with the reason, written whether the route said yes or refused:
action: mcp.write target: create_workflowdetail: {"reason": "the line 4 oven needs a setpoint workflow", "method": "POST", "path": "/api/v1/workflows", "status": 201}list_audit with action=mcp.write is every change an agent made and why.
The tools
Section titled “The tools”Every row is a real route and the permission that route asks for, and a test holds the table to both. A permission is a project permission (it is checked in the project the thing is in) or an instance one (owners and admins). Any signed in key can ask the ones marked so.
Body tools take a body, the same JSON the REST API takes. describe_tool_body
gives any tool’s schema, so the first call is right.
| Tool | Route | Permission | Kind |
|---|---|---|---|
get_version |
GET /api/v1/version |
any signed in key | read |
whoami |
GET /api/v1/me |
any signed in key | read |
list_permissions |
GET /api/v1/permissions |
any signed in key | read |
list_roles |
GET /api/v1/roles |
any signed in key | read |
get_role |
GET /api/v1/roles/{role} |
any signed in key | read |
list_projects |
GET /api/v1/projects |
project.read |
read |
get_project |
GET /api/v1/projects/{project} |
project.read |
read |
create_project |
POST /api/v1/projects |
project.create |
write |
rename_project |
PATCH /api/v1/projects/{project} |
project.update |
write |
delete_project |
DELETE /api/v1/projects/{project} |
project.delete |
write |
list_members |
GET /api/v1/projects/{project}/members |
project.read |
read |
set_member |
PUT /api/v1/projects/{project}/members/{user} |
project.members |
write |
remove_member |
DELETE /api/v1/projects/{project}/members/{user} |
project.members |
write |
list_service_accounts |
GET /api/v1/projects/{project}/service-accounts |
project.members |
read |
list_workflows |
GET /api/v1/workflows |
workflow.read |
read |
get_workflow |
GET /api/v1/workflows/{workflow} |
workflow.read |
read |
create_workflow |
POST /api/v1/workflows |
workflow.create |
write |
save_workflow |
PUT /api/v1/workflows/{workflow} |
workflow.update |
write |
delete_workflow |
DELETE /api/v1/workflows/{workflow} |
workflow.delete |
write |
listen_workflow |
POST /api/v1/workflows/{workflow}/listen |
workflow.execute |
write |
activate_workflow |
POST /api/v1/workflows/{workflow}/activate |
workflow.activate |
write |
deactivate_workflow |
POST /api/v1/workflows/{workflow}/deactivate |
workflow.activate |
write |
run_workflow |
POST /api/v1/workflows/{workflow}/run |
workflow.execute |
write |
move_workflow |
PUT /api/v1/workflows/{workflow}/folder |
workflow.update |
write |
list_workflow_versions |
GET /api/v1/workflows/{workflow}/versions |
workflow.read |
read |
get_workflow_version |
GET /api/v1/workflows/{workflow}/versions/{version} |
workflow.read |
read |
diff_workflow_versions |
GET /api/v1/workflows/{workflow}/diff |
workflow.read |
read |
restore_workflow_version |
POST /api/v1/workflows/{workflow}/versions/{version}/restore |
workflow.update |
write |
label_workflow_version |
PUT /api/v1/workflows/{workflow}/versions/{version}/label |
workflow.update |
write |
preview_expression |
POST /api/v1/workflows/{workflow}/preview |
workflow.read |
read |
list_expression_functions |
GET /api/v1/expression/functions |
any signed in key | read |
list_step_types |
GET /api/v1/step-types |
any signed in key | read |
shape_step |
POST /api/v1/step-types/{type}/{version}/shape |
any signed in key | read |
list_folders |
GET /api/v1/folders |
folder.read |
read |
create_folder |
POST /api/v1/folders |
folder.create |
write |
update_folder |
PATCH /api/v1/folders/{folder} |
folder.update |
write |
delete_folder |
DELETE /api/v1/folders/{folder} |
folder.delete |
write |
list_variables |
GET /api/v1/variables |
variable.read |
read |
create_variable |
POST /api/v1/variables |
variable.create |
write |
update_variable |
PUT /api/v1/variables/{variable} |
variable.update |
write |
delete_variable |
DELETE /api/v1/variables/{variable} |
variable.delete |
write |
list_executions |
GET /api/v1/executions |
execution.read |
read |
get_execution |
GET /api/v1/executions/{execution} |
execution.read |
read |
get_step_output |
GET /api/v1/executions/{execution}/steps/{step}/output |
execution.read |
read |
get_insights |
GET /api/v1/insights |
execution.read |
read |
stop_execution |
POST /api/v1/executions/{execution}/stop |
execution.stop |
write |
retry_execution |
POST /api/v1/executions/{execution}/retry |
execution.retry |
write |
replay_execution |
POST /api/v1/executions/{execution}/replay |
execution.retry |
write |
delete_execution |
DELETE /api/v1/executions/{execution} |
execution.delete |
write |
annotate_execution |
PUT /api/v1/executions/{execution}/annotation |
execution.annotate |
write |
clear_annotation |
DELETE /api/v1/executions/{execution}/annotation |
execution.annotate |
write |
list_credential_types |
GET /api/v1/credential-types |
any signed in key | read |
list_credentials |
GET /api/v1/credentials |
credential.list |
read |
get_credential |
GET /api/v1/credentials/{credential} |
credential.read |
read |
start_oauth |
POST /api/v1/credentials/{credential}/oauth/start |
credential.update |
write |
create_credential |
POST /api/v1/credentials |
credential.create |
write |
update_credential |
PATCH /api/v1/credentials/{credential} |
credential.update |
write |
delete_credential |
DELETE /api/v1/credentials/{credential} |
credential.delete |
write |
share_credential |
PUT /api/v1/credentials/{credential}/shares/{project} |
credential.share |
write |
unshare_credential |
DELETE /api/v1/credentials/{credential}/shares/{project} |
credential.share |
write |
create_role |
POST /api/v1/roles |
role.manage |
write |
update_role |
PUT /api/v1/roles/{role} |
role.manage |
write |
delete_role |
DELETE /api/v1/roles/{role} |
role.manage |
write |
list_redaction_policies |
GET /api/v1/redaction-policies |
any signed in key | read |
create_redaction_policy |
POST /api/v1/redaction-policies |
redaction.manage |
write |
update_redaction_policy |
PUT /api/v1/redaction-policies/{policy} |
redaction.manage |
write |
delete_redaction_policy |
DELETE /api/v1/redaction-policies/{policy} |
redaction.manage |
write |
list_secret_providers |
GET /api/v1/secret-providers |
any signed in key | read |
test_secret_provider |
POST /api/v1/secret-providers/{provider}/test |
secrets.manage |
write |
list_log_destinations |
GET /api/v1/log-destinations |
logstream.manage |
read |
test_log_destination |
POST /api/v1/log-destinations/{destination}/test |
logstream.manage |
write |
list_keys |
GET /api/v1/api-keys |
any signed in key | read |
revoke_key |
DELETE /api/v1/api-keys/{key} |
any signed in key | write |
list_scim_tokens |
GET /api/v1/scim-tokens |
scim.manage |
read |
revoke_scim_token |
DELETE /api/v1/scim-tokens/{token} |
scim.manage |
write |
list_users |
GET /api/v1/users |
user.manage |
read |
create_user |
POST /api/v1/users |
user.manage |
write |
change_user |
PATCH /api/v1/users/{user} |
user.manage |
write |
list_audit |
GET /api/v1/audit |
audit.read |
read |
verify_audit |
GET /api/v1/audit/verify |
audit.read |
read |
get_settings |
GET /api/v1/settings |
instance.settings |
read |
change_settings |
PATCH /api/v1/settings |
instance.settings |
write |
describe_tool_body |
not a route: the JSON Schema a tool’s body takes | any signed in key | read |
Left out on purpose
Section titled “Left out on purpose”Ten routes turn a key away themselves, because they want a person signed in, and the MCP server doesn’t pretend otherwise: making an API key, making a service account key, making a SCIM token, adding, changing and deleting an external secret provider, adding, changing and deleting a log destination, and a person’s own password. A key that could mint keys, or change where the audit log is sent, is a leaked key that can keep itself alive. Each of those is one tool that would only ever answer “not allowed”, so none is offered. Everything beside them is a tool: listing the log destinations, the secret providers and the SCIM tokens, revoking a SCIM token, testing a provider or a destination, listing and revoking keys, opening a workflow’s test webhook, and starting an OAuth2 sign-in, which hands back the address a person then opens. A key can revoke itself, which is what a leaked key’s holder should be able to do first.
/api/v1/openapi.json is not a tool: describe_tool_body gives the bodies.