Kerno MCP

Kerno's MCP tools are the API your coding agent uses to drive Kerno.

Async job pattern

Many Kerno tools are async because the underlying work (environment build, baseline capture, validation) can take minutes. Async tools return a job_id, a log_path, and a kind identifying the operation. Call kerno_job to wait for the result.

MCP hosts typically enforce a ~60-second timeout on a single tool call, so a single kerno_job call may not outlast a long-running job. Use wait=false for non-blocking polling, read log_path directly, or poll GET /mcp/jobs over HTTP (see Job snapshots below).

When a job reaches a terminal status (healthy, failed, or cancelled), its result is available via both kerno_job and GET /mcp/jobs. Completed jobs are retained (up to the last 50 by recency) — job_ids are not retired on first read.

To cancel an in-flight async job, call kerno_cancel with the job_id. Cancellation is fire-and-forget. The next kerno_job call returns status: cancelled.

Tools

Workspace management

Tool	Description
kerno_sync_workspace	Sync Kerno's view of the workspace with the current state of code on disk. Cancels all running Kerno operations, takes a fresh snapshot of the repository, and re-runs workspace analysis. Call this after making code changes so subsequent tools work against the latest code.
kerno_list_workspaces	List all workspaces Kerno is managing, including snapshot state (branch, commit, uncommitted changes, pending changes since snapshot) and currently active jobs. Use to check whether the workspace needs re-syncing before running other tools.

Discovery

Tool	Description
kerno_healthcheck	Check agent health, Docker, git, and authentication. workspace_path is optional; defaults to the agent workspace.
kerno_get_applications	Analyze the workspace and list applications Kerno detected.
kerno_list_endpoints	List HTTP routes for an application, with existingTests flags per route. Requires a scope.

Environment

Tool	Description
kerno_start_environment	Async. Build and start the test environment for an application. Returns job_id (kind: start_environment). Requires an approved compose plan (composeplan status=ready) — run the compose plan flow below first: trigger with kerno_compose_plan, watch via kerno_get_state, answer feedback via answer_feedback_request.
kerno_compose_up	Start or restart the compose project using existing Kerno-generated files on disk. Use this instead of kerno_start_environment when compose files already exist and no regeneration is needed.
kerno_compose_down	Stop a compose project.
kerno_compose_status	Get the status of a compose project. Check ready_for_validation before running validate or implement — status: Up alone is not sufficient.
kerno_compose_logs	Returns the current state of the compose project. Same response shape as kerno_compose_status.
kerno_environments_status	List all applications and their environment status.

Compose plan

The compose plan flow must complete before kerno_start_environment. Trigger plan generation, watch the resource state, answer any questions the planner raises, then approve the final plan.

Tool	Description
kerno_compose_plan	Async trigger. Submits a compose-plan generate command and returns immediately with status=accepted and resource_id. Cascades any missing or stale build, external-services, and security analyses before generating. Watch progress via kerno_get_state.

Compose plan flow:

1. kerno_compose_plan — trigger, returns resource_id.

2. kerno_get_state with that resource_id and until_status: ["plan_proposed","ready","failed"] — long-poll until the plan is proposed or complete. States cycle through: resolving_analyses → awaiting_analyses → plan_requested → generating → plan_proposed → ready | failed.

3. At plan_proposed: the state includes plan markdown. Show it to the user. If the planner raised questions during generating, open_feedback appears in the state — answer via answer_feedback_request on <resource_id>/feedback.

4. User approves: call answer_feedback_request on <resource_id>/feedback with {"approved":true}. User wants changes: {"approved":false,"reason":"<instruction>"} — a revised plan is proposed; repeat from step 2.

5. Once ready: call kerno_start_environment.

If kerno_start_environment returns needs_user_feedback, the result is auto-relayed to the compose plan as a rejection. Watch the composeplan resource via kerno_get_state, answer the revised plan via answer_feedback_request, then retry kerno_start_environment.

State plane

These tools let your agent read and watch the FSM state of Kerno resources (analyses, compose plan) without polling a job. Use them after kerno_compose_plan and whenever you need to observe resource progress or check for pending feedback.

Tool	Description
kerno_get_state	Read a resource's current FSM state by resource_id. Returns {resource_id, state} where state.status is the variant tag, or state=null if the resource has never started. Long-poll: pass until_status (array of statuses to wait for, e.g. ["ready","failed"]) and optional wait_timeout_ms (default 45000 ms, max 50000 ms). timed_out=true is a normal outcome — re-issue with the same until_status. Waiting states surface open_feedback {resource_id, request_id} when a feedback request is open.
kerno_list_state	List every started resource under an optional prefix (matched at path-segment boundaries, e.g. workspace/<ws> or workspace/<ws>/module/<app>). Returns {resources: [{resource_id, state}]}. Resources that have never started do not appear. Use to discover what exists before reading or polling.
kerno_poll_events	Replay domain events since a cursor. Returns {stream_epoch, next_cursor, gap, events: [{seq, resource_id, event}]} oldest-first; each event's variant tag is its type field. Start at cursor=0, then pass next_cursor back verbatim on each subsequent call. If stream_epoch changes between calls, the agent restarted — reset cursor to 0. If gap=true, events fell off the retention buffer — re-read current state with kerno_get_state or kerno_list_state. Long-poll: pass wait_timeout_ms to suspend until ≥1 matching event arrives or timeout (max 50000 ms; 45000 ms recommended). timed_out=true with events:[] is a normal outcome — re-issue with the same cursor.

Resource id format:

workspace/<ws>/module/<app>/composeplan
workspace/<ws>/module/<app>/securityanalysis
workspace/<ws>/module/<app>/externalservicesanalysis
workspace/<ws>/module/<app>/buildanalysis
<any of the above>/feedback        ← feedback subresource

Feedback gate

When Kerno needs input from the user — a planner question, an approval request, an ambiguous config — it opens a feedback request on the relevant resource. These tools let your agent discover and answer those requests.

Tool	Description
kerno_feedback_pending	Read-only snapshot of pending feedback for one app, across all its resources (analyses and composeplan, including the planner's pre-proposal questions). Returns {request_id, prompt, schema, resource_id} when a question is open, or {status: "none"} when nothing is pending. Call when a state shows open_feedback or a waiting status stalls.
kerno_feedback_answer	Answer a pending feedback request by workspace_path + app + request_id. Payload is a JSON string conforming to the schema from kerno_feedback_pending: free-text {"answer":"..."} or approval {"approved":true} / {"approved":false,"reason":"..."}. Returns accepted once queued. After answering, poll kerno_get_state on the resource to confirm it resumes.
answer_feedback_request	Answer a feedback request by resource_id (the .../feedback subresource) + request_id. Same payload shape as kerno_feedback_answer. Use this when you have the resource_id directly from kerno_get_state's open_feedback field or from kerno_compose_plan's response.

kerno_feedback_answer and answer_feedback_request reach the same action — use whichever is more convenient given the context you already have.

Validation

Tool	Description
kerno_plan_baseline	Plan scenarios for an endpoint or set of endpoints. Async (with scope) or sync (with method and path). Returns job_id (kind: plan_baseline) or plan_sync data. Accepts plan_review_instructions for iterative refinement.
kerno_implement_baseline	Async. Implement and run the planned scenarios. Returns job_id (kind: implement_baseline).
kerno_validate	Async. Re-run scenarios after a code change. Returns job_id (kind: validate).
kerno_approve	Sync. Acknowledge that a validation diff is intentional. Optional reason.
kerno_reject	Sync. Acknowledge that a validation diff is unintended. Optional reason.

Code search and navigation

These tools let your agent explore the codebase structurally. They are not prefixed with kerno_.

Run scan_workspace first to discover modules, then index_module to make a module queryable. After indexing, you can use find_definition, find_references, find_usages, and call_hierarchy against symbols in that module. Heatmap tools work on indexed modules too.

Tool	Description
scan_workspace	Scan the repository and list modules and their roots. Required before indexing modules.
index_module	Index a module so the rest of the navigation tools can query it.
package_heatmap	Show where packages and external dependencies are used across the codebase.
symbol_heatmap	Show where specific symbols (functions, classes, etc.) are used across the codebase.
find_usages	Find all usages of a symbol across the codebase.
find_definition	Find the definition of a symbol at a specific file location. Requires the module to be indexed.
find_references	Find all references to a symbol.
call_hierarchy	Walk downstream call chains from a piece of code.
list_build_files	List the build configuration files in a module.

Job lifecycle

Tool / Endpoint	Description
kerno_job	Wait for or snapshot an async job. wait=true (default) blocks until terminal or the server budget elapses. wait=false returns the current state. Pass the job_id returned by the launching tool.
kerno_cancel	Cancel an in-flight async job by job_id. Fire-and-forget. The next kerno_job call returns status: cancelled.
GET /mcp/jobs	HTTP endpoint. List active and recently-completed jobs as McpJobSnapshot objects. Supports ?since=<ISO-8601> and ?status=<value> (repeatable) filters. See Job snapshots.

Job snapshots

GET /mcp/jobs returns an array of McpJobSnapshot. Use it for lightweight HTTP polling, for tooling that needs to observe running jobs without blocking an MCP call, or to retrieve a completed job's result after the MCP session has ended.

{
  "jobId": "abc123",
  "kind": "validate",
  "status": "healthy",
  "startedAt": "2026-06-03T10:00:00Z",
  "lastActivityAt": "2026-06-03T10:02:15Z",
  "completedAt": "2026-06-03T10:02:15Z",
  "activityLogTail": ["...last 20 lines of the activity log..."],
  "scope": {
    "endpoints": [
      { "app": "myapp", "method": "GET", "path": "/api/items" }
    ]
  },
  "terminalPayload": { }
}

Field	Type	Notes
jobId	string	Same ID returned by the launching MCP tool.
kind	string	One of: start_environment, plan_baseline, implement_baseline, validate, compose_plan, compose_up, build_analysis, external_services_analysis, security_analysis.
status	string	running, healthy, failed, cancelled, or needs_user_feedback.
startedAt	ISO-8601 timestamp
lastActivityAt	ISO-8601 timestamp	Updated on each activity log write and on completion.
completedAt	ISO-8601 timestamp	Null while running.
activityLogTail	string[]	Last 20 lines of the activity log. Read log_path for the full log.
scope	object (nullable)	Resolves once the job starts processing. Lists the endpoints targeted by this job.
terminalPayload	object (nullable)	Present on completion for validate, plan_baseline, and implement_baseline. Mirrors the payload returned by kerno_job.

Query params:

• ?since=<ISO-8601> — return only jobs where lastActivityAt >= since.

• ?status=<value> — filter by status. Repeatable: ?status=running&status=failed.

Completed jobs are retained in a ring buffer (last 50 by lastActivityAt). Snapshots are read-only — use kerno_cancel to cancel a running job.

Scopes

Several tools accept a scope parameter to target a subset of endpoints. See Scopes for the four scope strings and when to use each.

Common patterns

A typical validation flow looks like this.

1. kerno_healthcheck to confirm Docker, git, and auth.

2. kerno_get_applications to discover applications.

3. kerno_compose_plan to trigger compose plan generation. Watch progress via kerno_get_state on the returned resource_id. Answer any planner questions and the final approval via answer_feedback_request. See the compose plan flow above for the full sequence.

4. kerno_start_environment once the plan is approved (composeplan status=ready). Wait via kerno_job.

5. kerno_plan_baseline and kerno_implement_baseline to capture an initial baseline. Wait via kerno_job between each step.

6. After code changes, kerno_sync_workspace to re-index, then kerno_validate with scope: changed. Wait via kerno_job.

7. Review diffs and call kerno_approve or kerno_reject.

Notes for agent integrators

• Use absolute workspace paths when tools request workspace_path.

• Do not poll kerno_job in a tight loop. Use wait=false with a sparse cadence (every few minutes), read log_path directly, or use GET /mcp/jobs for lightweight HTTP polling.

• Do not manually edit scenario files under .kerno/scenarios/. After code changes, call kerno_validate (and kerno_plan_baseline / kerno_implement_baseline if scenarios need regenerating).

• Only one start_environment job can run per (workspace, application) at a time. Only one of plan_baseline, implement_baseline, or validate can run per (workspace, scope, application).

• After making code changes, call kerno_sync_workspace before running kerno_list_endpoints, kerno_validate, or kerno_plan_baseline to ensure Kerno is working against the latest code.

• For kerno_get_state and kerno_poll_events long-poll calls, use wait_timeout_ms of 45000 ms or less. timed_out=true is a normal outcome — re-issue immediately with the same parameters.