> 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

Environment setup and endpoint tests are async, because the underlying work 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.

When a job reaches a terminal status (`healthy`, `failed`, `cancelled`, or `needs_user_feedback`), its result is available via both `kerno_job` and `GET /mcp/jobs`. Completed jobs are retained up to the last 50 by recency, and `job_id`s are not retired on first read. Retention is enforced lazily, when new jobs launch or when the job list is 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`.

{% hint style="warning" %}
**`kerno_job` does not surface feedback gates.** When an endpoint test pauses to ask for plan approval or an answer, `kerno_job` keeps reporting `running` and the job looks stuck. Check `kerno_feedback_pending`, or read the endpoint-test resource with `kerno_get_state`. This is the single most common false alarm.
{% endhint %}

### Tools

#### Guidance

| Tool          | Description                                                                                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kerno_guide` | Returns guidance for your agent. Topics: `endpoint_test_intent` (default), `rules_template`, `env_visibility`, `scenario_philosophy`. Also published as MCP resources at `kerno://guide/<topic>`. |

#### Workspace management

| Tool                    | Description                                                                                                                                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kerno_sync_workspace`  | Sync Kerno's view of the workspace with the current state of code on disk. Cancels running Kerno operations, takes a fresh snapshot, and re-runs workspace analysis. Call this after making code changes. |
| `kerno_list_workspaces` | List the workspaces Kerno is managing, including snapshot state (branch, commit, uncommitted changes) and active jobs.                                                                                    |
| `kerno_clear_cache`     | Clear cached workspace analysis. Pass `application_id` to clear a single application.                                                                                                                     |

#### Discovery

| Tool                     | Description                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kerno_healthcheck`      | Check agent health, Docker, git, authentication, and codegraph. `workspace_path` is optional; defaults to the agent workspace.                                        |
| `kerno_get_applications` | Analyze the workspace and list applications Kerno detected, split into supported and unsupported, with each app's current config summary and recommended next action. |
| `kerno_list_endpoints`   | List HTTP routes for an application, with `existingTests` flags per route. Requires a `scope`.                                                                        |

#### Environment

| Tool                       | Description                                                                                                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kerno_save_config`        | Persist how to reach your application: `target_environment` (`local` or `remote`), `sut_url`, and optional datastore credential blocks. Kerno probes reachability from inside its sandbox before saving. |
| `kerno_environment_setup`  | Probe the application and prepare it for endpoint testing. Synchronous.                                                                                                                                  |
| `kerno_environment_status` | Report readiness. Check `ready_for_endpoint_test` before running a test.                                                                                                                                 |

Kerno does not build or run your application. You start it yourself, then tell Kerno where it is. See [Environment Setup](/docs/core-concepts/environment-setup.md).

#### Endpoint testing

| Tool                         | Description                                                                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `kerno_endpoint_test`        | Async. Generate, validate, or update tests for a single endpoint. Returns `job_id` (kind: `endpoint_test`).                            |
| `kerno_ignore_potential_bug` | Record that a reported potential bug is known or intended. Future runs of that endpoint document the behaviour instead of flagging it. |

`kerno_endpoint_test` arguments:

| Argument                  | Required | Values                                           |
| ------------------------- | -------- | ------------------------------------------------ |
| `workspace_path`          | yes      | absolute path                                    |
| `app`                     | yes      | application id from `kerno_get_applications`     |
| `endpoint_method`         | yes      | e.g. `GET`                                       |
| `endpoint_path`           | yes      | e.g. `/api/users`                                |
| `type`                    | yes      | `generate` \| `validate` \| `update`             |
| `effort`                  | no       | `low` \| `medium` \| `high` — default `high`     |
| `box_testing_strategy`    | no       | `black_box` \| `white_box` — default `white_box` |
| `tags`                    | no       | `validation` (default) and/or `security`         |
| `test_generation_context` | no       | free-text guidance for this endpoint             |
| `scenario_ids`            | no       | target specific scenarios only                   |
| `interactive`             | no       | boolean, default `false`                         |

See [Testing modes](/docs/references/testing-modes.md) for what each of these changes.

The launch response echoes a `resolved_intent` object showing which values Kerno used and which it had to default.

#### Feedback gate

When Kerno needs input — a plan approval, a planner question, missing credentials — it opens a feedback request on the relevant resource.

| Tool                      | Description                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kerno_feedback_pending`  | Read-only snapshot of pending feedback for one app, covering compose plan and endpoint-test plan reviews. Returns `{request_id, prompt, schema, resource_id}` when a question is open, or `{status: "none"}`. Call when a state shows `open_feedback`, or when a status sits at `awaiting_feedback`, `awaiting_approval`, `generating`, or `plan_proposed`. |
| `kerno_feedback_answer`   | Answer by `workspace_path` + `app` + `request_id`. Payload is free-text `{"answer":"..."}` or approval `{"approved":true}` / `{"approved":false,"reason":"..."}`. Returns `accepted` once queued.                                                                                                                                                           |
| `answer_feedback_request` | Answer by `resource_id` (the `.../feedback` subresource) + `request_id`. Same payload shape. Use this when you already have the `resource_id` from `kerno_get_state`.                                                                                                                                                                                       |

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

#### State plane

These tools let your agent read and watch the state of Kerno resources without polling a job.

| Tool                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kerno_get_state`   | Read a resource's current state by `resource_id`. Returns `{resource_id, state}` where `state.status` is the variant tag, or `state=null` if the resource has never started. Pass `until_status` to long-poll until the status enters that set; when you do, `wait_timeout_ms` defaults to 600000 ms, which is also the maximum. Without `until_status` the call returns immediately. `timed_out=true` is a normal outcome — re-issue with the same `until_status`. Waiting states surface `open_feedback {resource_id, request_id, prompt}`. |
| `kerno_list_state`  | List every started resource under an optional `prefix`, matched at path-segment boundaries. Returns `{resources: [{resource_id, state}]}`. Resources that have never started do not appear.                                                                                                                                                                                                                                                                                                                                                   |
| `kerno_poll_events` | Replay domain events since a cursor. Returns `{stream_epoch, next_cursor, gap, events: [{seq, resource_id, event}]}` oldest-first. Start at `cursor=0`, then pass `next_cursor` back verbatim. If `stream_epoch` changes, the agent restarted — reset to 0. If `gap=true`, events fell off the buffer — re-read state. Accepts `max_events` (default 256) and `wait_timeout_ms` (maximum 600000 ms). There is no default wait here — omit `wait_timeout_ms` for an immediate return.                                                          |

**Resource id formats.** Endpoint tests use a different shape from analyses, so match carefully:

```
workspace/<ws>/app/<app>/endpoint/<METHOD>/<path>/endpointtest
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
```

Note `app/` in the endpoint-test form versus `module/` in the others.

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

### Job snapshots

`GET /mcp/jobs` returns an array of `McpJobSnapshot`. Use it for lightweight HTTP polling, or to retrieve a completed job's result after the MCP session has ended.

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

| Field             | Type               | Notes                                                                                                                                                                                 |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobId`           | string             | Same ID returned by the launching MCP tool.                                                                                                                                           |
| `kind`            | string             | One of: `endpoint_test`, `start_environment`, `plan_baseline`, `implement_baseline`, `validate`, `compose_plan`, `build_analysis`, `external_services_analysis`, `security_analysis`. |
| `app`             | string             | Application the job targets.                                                                                                                                                          |
| `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 `endpoint_test` and the validation job kinds. 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`). Only completed jobs are evicted, and eviction also deletes the on-disk log. Snapshots are read-only — use `kerno_cancel` to cancel a running job.

### MCP resources

The Kerno agent publishes MCP resources alongside its tools:

```
kerno://guide/<topic>
kerno://scenarios/{path}
kerno://preconditions/{path}
```

### Common patterns

A typical first run looks like this.

1. `kerno_healthcheck` to confirm Docker, git, and auth.
2. `kerno_get_applications` to discover applications and pick one.
3. Start your application yourself, using its own dev flow.
4. `kerno_save_config` with `target_environment`, `sut_url`, and any datastore credentials.
5. `kerno_environment_setup`, then `kerno_environment_status` until `ready_for_endpoint_test` is true.
6. `kerno_list_endpoints` with a scope to see what is testable.
7. `kerno_endpoint_test` with `type: generate` for the endpoint you care about.
8. `kerno_job` with `wait=false` on a sparse cadence, **and** `kerno_feedback_pending` to catch the plan-approval gate.
9. Approve the plan via `kerno_feedback_answer`.

After a code change: `kerno_sync_workspace`, then `kerno_endpoint_test` with `type: validate`. If the endpoint changed on purpose and the tests should follow, use `type: update`.

### 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`.
* **Watch for feedback gates separately from jobs.** A gated job reports `running`.
* Do not manually edit scenario files under `.kerno/scenarios/`. To change them, run `kerno_endpoint_test` with `type: update` or `type: generate`.
* Only one `environment_setup` job can run per `(workspace, application)` at a time. Endpoint tests dedupe on workspace, app, method, path, and type.
* After making code changes, call `kerno_sync_workspace` before `kerno_list_endpoints` or `kerno_endpoint_test`.
* For long-poll calls, `timed_out=true` is a normal outcome — re-issue immediately with the same parameters.

### Legacy tool surface

Earlier versions of Kerno exposed a larger set of tools for orchestrating Docker Compose, planning and implementing baselines as separate steps, and approving or rejecting diffs: `kerno_start_environment`, `kerno_compose_plan`, `kerno_compose_up`, `kerno_compose_down`, `kerno_compose_status`, `kerno_compose_logs`, `kerno_environments_status`, `kerno_plan_baseline`, `kerno_implement_baseline`, `kerno_validate`, `kerno_approve`, `kerno_reject`, plus a set of code-navigation tools.

These are no longer part of the default tool surface. Their functionality is covered by `kerno_save_config`, `kerno_environment_setup`, and `kerno_endpoint_test`. If your agent references any of them, it is working from outdated instructions.