MCP tools, resources and prompts

The server implements the Model Context Protocol (JSON-RPC 2.0) so an agent can operate cereyan. The tool set is curated rather than a mirror of the HTTP API. Definitions live in crates/server/src/mcp.rs; this page is generated from a snapshot of what a client actually receives. Setup for Claude Code, Claude Desktop, and HTTP clients is in Use cereyan with an AI agent.

Transports

Transport	How	Authentication
stdio	cereyan mcp, started by the host; proxies every message to the running server found through server.json (--url and --socket override)	CEREYAN_TOKEN, or --token before the subcommand (cereyan --token <token> mcp); with a Unix socket and no token it connects over the socket
Streamable HTTP	POST /mcp with one JSON-RPC message per request; requests get a JSON reply, notifications get 202; initialize returns Mcp-Session-Id to send on later requests; DELETE /mcp ends the session; GET /mcp answers 405	Authorization: Bearer <token> when the server has a token

Runs created through MCP record created_by = mcp:<client name> from the initialize handshake.

Handshake

initialize answers with protocol version 2025-06-18, server name cereyan and its release version, and the capabilities prompts, resources, tools. It also carries the instructions the server gives the model:

cereyan runs Python pipelines on this machine. Use list_flows to see what can run, run_flow to start work, get_run and run_logs to follow it, and explain_failure when a run fails. Flows run on demand: a flow needs no schedule, and run_flow is how work usually starts. For work that should recur, list_schedules shows what is scheduled and the create, edit, delete, pause and resume schedule tools manage it. Writes take effect immediately.

Tools

Every tool description states its effect so a model can decide before calling. A tool returns one text content block holding the JSON whose top-level keys are listed as its response; a failure returns isError: true and a message instead. Rule creation is not exposed, and a schedule declared in a flow's code cannot be deleted through MCP: the next restart recreates it from the declaration, so pausing it is what lasts.

Read-only tools (9)

Tool	Arguments	Returns
list_flows	project (string) — Only flows of this project	List the registered flows with their project, parameters schema, tags, and any registration error. Response keys: flows
list_runs	flow (string) limit (integer, 1 to 200, default 20) name (string) — Exact run name project (string) state_name (string) — A named sub-state such as Late or AwaitingRetry state_type (string) — Scheduled, Pending, Running, Completed, Failed, Cancelled, Crashed, Paused, Cancelling	List runs, newest first, with optional filters. Response keys: next_cursor, runs
get_run	run_id (integer, required)	One run with its state, parameters, timing, and task runs. Response keys: run, task_runs
run_logs	limit (integer, 1 to 1000, default 200) min_level (integer) run_id (integer, required) search (string)	Log lines of a run, oldest first. Filter by minimum level (10 debug, 20 info, 30 warning, 40 error) or a search string. Response keys: logs, next_cursor
list_events	flow_id (integer) limit (integer, 1 to 500, default 50) name (string) — Exact name or a prefix ending in * such as run.* run_id (integer)	Recent events (run and task transitions, schedule changes, rule firings, custom events), newest first. Response keys: events, next_cursor
list_artifacts	flow (string) key (string) kind (string) limit (integer, 1 to 200, default 50) project (string) run_id (integer)	Artifacts across runs, newest first, with their run, flow, and project. Response keys: artifacts, next_cursor
list_rules	none	The rules (reactive and proactive) with their match, actions, guards, and fire counts. Response keys: rules
list_schedules	flow (string) — Flow name, or project/flow when the name exists in several projects project (string) — Only schedules of this project	The schedules of one flow or of every flow: the spec, whether it is active, when it next fires, and whether it was declared in the flow's code, created in the interface, or created by an agent. Response keys: schedules
explain_failure	run_id (integer, required)	Everything needed to diagnose a run in one call: the run, its failed or crashed task runs, the last warning-or-above log lines, and the run's events. Response keys: error_logs, events, failed_task_runs, run, verdict

Tools that change state (10)

Tool	Arguments	Returns
run_flow	flow (string, required) — Flow name, or project/flow when the name exists in several projects name (string) — Optional run name parameters (object) — Flow parameters as JSON tags (array of string)	Start a run of a flow now. Creates the run immediately and returns without waiting; follow it with get_run. Parameters are validated against the flow's schema. Response keys: note, run
cancel_run	run_id (integer, required)	Cancel a run. A queued run is cancelled at once; a running run is asked to stop and killed after the grace period. Response keys: run
resume_run	input (any JSON, required) — The answer, any JSON run_id (integer, required)	Answer a Paused run's wait_for_input question and schedule its next attempt. The answer can be any JSON. Response keys: run
backfill	concurrency (integer, default 1) dry_run (boolean, default true) end (string, required) extra_parameters (object) flow (string, required) — Flow name, or project/flow when the name exists in several projects interval (string) — Seconds or a duration such as 1d or 12h (default 1d) parameter (string, required) reverse (boolean) start (string, required) — YYYY-MM-DD or RFC 3339	Create one run per value of a date or datetime parameter between start and end. Defaults to a dry run that only reports how many runs would be created; pass dry_run false to create them. Can create thousands of runs. Response keys: dry run: dry_run, first, flow, interval_seconds, last, note, parameter, runs dry_run false: backfill, dry_run
create_schedule	anchor (integer) — Microseconds UTC the interval counts from; defaults to now catchup (string, default "skip") catchup_max (integer, default 100) cron (string) — Five-field cron expression, for kind cron day_or (boolean) — For cron, OR day-of-month with day-of-week (default true) flow (string, required) — Flow name, or project/flow when the name exists in several projects interval (number) — Seconds between fires, for kind interval kind (string, required) — Which kind of schedule project (string) rrule (string) — RFC 5545 RRULE, for kind rrule timezone (string) — IANA name such as Europe/Istanbul; UTC when unset	Make a flow run repeatedly. To run a flow once, now, use run_flow instead: a flow needs no schedule, and running on demand is the normal case. Returns the schedule and the next few times it will fire. Response keys: next_fires, schedule
edit_schedule	anchor (integer) catchup (string) catchup_max (integer) cron (string) day_or (boolean) interval (number) rrule (string) schedule_id (integer, required) timezone (string)	Retime an existing schedule. Editing one that was declared in the flow's code lasts until the server restarts, when the declaration in the Python source applies again, and the result says so. Returns the schedule and the next few times it will fire. Response keys: next_fires, schedule
delete_schedule	schedule_id (integer, required)	Remove a schedule that was created in the interface or by an agent. A schedule declared in the flow's code cannot be removed this way, because the next restart recreates it from the declaration; pause_schedule stops that one durably. Response keys: deleted, schedule_id
pause_schedule	schedule_id (integer, required)	Pause a schedule so it stops creating runs until resumed. Response keys: schedule
resume_schedule	schedule_id (integer, required)	Resume a paused schedule. Response keys: schedule
set_variable	name (string, required) secret (boolean, default false) tags (array of string) value (any JSON, required) — Any JSON	Create or overwrite a variable. Secrets are encrypted at rest and never returned in plain text. Response keys: variable

Fields of the lists a tool returns

Recorded from real responses, so a model knows what it gets without a second call.

Tool	Key	Item fields
explain_failure	error_logs	id, level, logger, message, run_id, task_run_id, timestamp
explain_failure	events	external_id, flow_id, id, name, occurred, payload, related, resource, run_id, seq
get_run	task_runs	crash_count, created_at, dynamic_key, end_time, external_id, failure_count, flow_id, flow_name, id, name, parents, project, run_id, run_name, start_time, state, task_key, total_run_time
list_artifacts	artifacts	created_at, data, external_id, flow_name, id, key, kind, project, run_id, run_name, task_run_id, updated_at
list_events	events	external_id, flow_id, id, name, occurred, payload, related, resource, run_id, seq
list_flows	flows	description, error, id, live, name, options, parameter_schema, project, tags
list_runs	runs	attempt, backfill_id, crash_count, created_at, created_by, end_time, engine_id, engine_pid, external_id, failure_count, flow_id, flow_name, group, id, name, parameters, parent_run_id, priority, project, report_seq, schedule_id, scheduled_time, start_time, state, tags, task_counts, total_run_time
list_schedules	schedules	active, catchup, catchup_max, flow, id, next_fire, paused_reason, paused_until, project, schedule, source
run_logs	logs	id, level, logger, message, run_id, task_run_id, timestamp

Resources

resources/list returns none: both resources are templates, listed by resources/templates/list and fetched with resources/read.

URI template	Name	Content	MIME type
cereyan://runs/{id}/logs	Run logs	Log lines of a run as JSON	application/json
cereyan://runs/{id}/artifacts	Run artifacts	Artifacts of a run as JSON	application/json

Prompts

Prompt	Arguments	Purpose
diagnose_run	run_id (The run id, required)	Explain why a run failed and what to do about it

diagnose_run renders one message:

user: Run of a cereyan pipeline needs a diagnosis. Call the explain_failure tool with run_id , read the failed task runs, the error log lines, and the events, then summarise the root cause in two sentences and suggest one concrete next step (rerun with run_flow, fix the code, or adjust a schedule).