Skip to content
GitHub

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.

Make a key. In the editor it is under your account, or with the API:

Terminal window
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.

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.

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.created

And one row of the tool’s, with the reason, written whether the route said yes or refused:

action: mcp.write target: create_workflow
detail: {"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.

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

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.