> For the complete documentation index, see [llms.txt](https://kerno.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kerno.gitbook.io/docs/references/kerno-mcp.md). # Kerno MCP ### 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](#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_id`s 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 `/feedback`. 4. User approves: call `answer_feedback_request` on `/feedback` with `{"approved":true}`. User wants changes: `{"approved":false,"reason":""}` — 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/` or `workspace//module/`). 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//module//composeplan workspace//module//securityanalysis workspace//module//externalservicesanalysis workspace//module//buildanalysis /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=` and `?status=` (repeatable) filters. See [Job snapshots](#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. ```json { "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=` — return only jobs where `lastActivityAt >= since`. * `?status=` — 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](#compose-plan) 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://kerno.gitbook.io/docs/references/kerno-mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.