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 and Content-Type: application/json (any other type answers 415); 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 (19)

Tool	Arguments	Returns
list_flows	group (string) — Only flows of this group: the one a flow declared, else its project 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	attributes (string) — Comma-separated key=value pairs the run's attributes (set_attributes) must match flow (string) group (string) — Only runs of flows in this group: the one a flow declared, else its project limit (integer, 1 to 200, default 20) name (string) — Exact run name params (string) — Comma-separated key=value pairs the run's parameters must match, e.g. day=2026-09-01; searches the last 30 days unless start bounds are given 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, task_state
compare_runs	other_run_id (integer, required) — The run in question run_id (integer, required) — The baseline, usually the last good run	What changed between two runs: parameters and attributes, duration, each task's state and duration, the first task that diverged, error lines and the failure message new on the second run, and artifact differences. The first run is the baseline. Response keys: artifacts, attributes, duration, first_divergence, left, new_errors, parameters, right, same_flow, summary, tasks
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, whether it was declared in the flow's code, created in the interface, or created by an agent, and for a continuous schedule its loop state (waiting, in_line, running, or paused). 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
list_waiting_runs	flow (string) — Flow name, or project/flow when the name exists in several projects limit (integer, 1 to 500, default 50) project (string)	Runs that are Paused waiting for input or a message, with their prompt, topic, and the flow they belong to. Response keys: —
list_backfills	flow (string) — Flow name, or project/flow when the name exists in several projects project (string)	Backfills, newest first, each with its counts of runs by state. Response keys: backfills
get_backfill	backfill_id (integer, required)	One backfill with its counts of runs by state. Response keys: backfill
get_flow_source	flow (string, required) — Flow name, or project/flow when the name exists in several projects project (string)	The Python source of the module that registered a flow, read from the flow's own source directory and cut at 64 KB. Response keys: bytes, flow, module, path, project, source, truncated
server_health	none	The server's state in one call: engines and what they are running, processors (the engine pool size, its CPU cap, and how many engines run, idle or drain), remote workers, queue length, resource usage, schedule count, whether the scheduler is paused, and whether a token is required or the server is exposed. Response keys: as_of, auth, engines, exposed, paused, processors, queued, read_only, resources, schedules, served_dir, version, workers
list_variables	none	Every variable's name, tags, and timestamps; the value only when it is not a secret. Response keys: variables
list_resources	none	Resource totals from [resources] and what is in use. Response keys: resources
flow_dependencies	flow (string, required) — Flow name, or project/flow when the name exists in several projects project (string)	What a flow runs after (its upstreams and batch key) and which flows run after it. Response keys: batch_key, flow, project, triggers, upstreams
check_flows	none	Run cereyan check --json on the served directory in a child process and return its report: import failures, unknown upstreams, invalid schedules with previews, unlisted resources, and route conflicts. Takes a few seconds. Response keys: directory, errors, findings, flows, modules, now, ok, routes, rules, warnings

Tools that change state (17)

Tool	Arguments	Returns
run_flow	at (string) — Start at this time, ISO 8601, instead of now delay_seconds (number) — Start this many seconds from now; not with at 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, or at a later time with at or delay_seconds. Creates the run immediately and returns without waiting; follow it with get_run. Parameters are validated against the flow's schema. Response keys: conflict, 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
send_message	payload (any JSON, required) — The message payload, any JSON run_id (integer, required) topic (string, required)	Send a message to a Paused run on a topic. Resumes the run immediately if it is waiting for this topic, or queues the message for the next receive() call. Response keys: —
backfill	concurrency (integer, default 1) dry_run (boolean, default true) end (string) extra_parameters (object) flow (string, required) — Flow name, or project/flow when the name exists in several projects force (boolean) — Restate: the runs ignore targets, caches, checkpoints and bulk_complete interval (string) — Seconds or a duration such as 1d or 12h (default 1d) missing_only (boolean) — Leave out values whose latest run completed parameter (string, required) reverse (boolean) start (string) — YYYY-MM-DD or RFC 3339; not needed with values values (array of string) — Explicit parameter values instead of a range	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) catchup_window (integer) — Seconds; missed fires older than this are not caught up (0 is off) cron (string) — Five-field cron expression, for kind cron day_or (boolean) — For cron, OR day-of-month with day-of-week (default true) delay (number) — Seconds from the end of one run to the next joining the line, for kind continuous flow (string, required) — Flow name, or project/flow when the name exists in several projects interval (number) — Seconds between fires, for kind interval jitter (integer) — Seconds; each run is due up to this long after its fire time, deterministically (0 is off) kind (string, required) — Which kind of schedule project (string) rrule (string) — RFC 5545 RRULE, for kind rrule start_deadline (integer) — Seconds; a run not started this long after it was due is skipped (0 is off) 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. Kind continuous runs the flow again delay seconds after each run ends, one run at a time, and takes no catch-up options. Returns the schedule and the next few times it will fire (none for a continuous schedule). Response keys: next_fires, schedule
edit_schedule	anchor (integer) catchup (string) catchup_max (integer) catchup_window (integer) — Seconds; 0 turns it off cron (string) day_or (boolean) delay (number) — Seconds a continuous schedule waits after each run ends interval (number) jitter (integer) — Seconds; 0 turns it off rrule (string) schedule_id (integer, required) start_deadline (integer) — Seconds; 0 turns it off 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
pause_scheduler	reason (string) — Shown in the UI banner and recorded on the scheduler.paused event suppress_rules (boolean, default false) until (string) — When to resume on its own, ISO 8601; omit to hold until resume_scheduler	Pause every schedule at once, for maintenance or an incident. Nothing scheduled starts until resume_scheduler or until; running runs, manual runs and backfills continue. With suppress_rules, rules that would fire are recorded as suppressed instead of acting. Response keys: —
resume_scheduler	none	End the global pause: held runs start and each schedule catches up the fires it missed under its own policy. Response keys: —
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
cancel_backfill	backfill_id (integer, required)	Cancel a backfill: its queued runs are cancelled at once and its running runs are asked to stop. Response keys: backfill, note
list_workers	none	The remote workers registered with this server: each one's name, status (online, draining, offline), processors, labels, cereyan version, the modules whose code differs from the server's, and when it was last heard from. Read-only; draining, resizing and forgetting workers is done in the UI or the HTTP API. Response keys: —
rerun_run	from (string) — failure, start, or a task's dynamic key such as transform-0; omit for a fresh run run_id (integer, required)	Start a new run of the same flow with the original run's parameters and tags. With from, the new run is a retry linked to the original that replays its completed tasks from their checkpoints and executes from the failure, from the start, or from the named task and everything after it. Returns the new run; follow it with get_run. Response keys: note, rerun_of, run
flow__agent__etl	day (string, default "2026-09-06") n (integer, default 1)	Start a run of flow agent/etl. Arguments are the flow's parameters. Returns the run; follow it with get_run. Response keys: note, run

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
check_flows	findings	flow, kind, level, message
check_flows	flows	findings, fingerprint, name, project, runs_on, schedules
compare_runs	artifacts	changed, key, kind, left, right
compare_runs	parameters	changed, key, left, right
compare_runs	tasks	delta, key, left, name, right, state_changed
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, input_hash, name, parents, pass, project, result_ref, 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_backfills	backfills	cancelled, concurrency, counts, created_at, end_value, external_id, extra_parameters, flow_id, id, interval_secs, parameter, start_value, tag, total
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, attributes, backfill_id, crash_count, created_at, created_by, end_time, engine_id, engine_pid, external_id, failure_count, flow_id, flow_name, group, host, id, lease, name, parameters, parent_run_id, priority, processor, project, report_seq, schedule_id, scheduled_time, source_hash, start_time, state, tags, task_counts, total_run_time, unique_key
list_schedules	schedules	active, catchup, catchup_max, flow, id, loop_state, next_fire, paused_reason, paused_until, project, schedule, source
list_variables	variables	created_at, name, secret, tags, updated_at, value
run_logs	logs	id, level, logger, message, run_id, task_run_id, timestamp
server_health	engines	adopted, current_run, exit_requested, id, isolated, module, nice, pid, runs_done, source_dir, uptime_secs

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
health_check	none	Report what needs attention on this server: engines, queue, failed runs, and schedules
plan_backfill	flow (Flow name, or project/flow, required) parameter (The date or datetime parameter, required) start (First value, YYYY-MM-DD or RFC 3339, required) end (Last value, inclusive, required)	Plan a backfill as a dry run, review the range and count, then create the runs

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