Using Kerno MCP

Kerno MCP connects your AI assistant to your backend workspace: it can analyze the repo, start a local stack from cold, record HTTP test baselines, and re-run those tests against the running services.

Start your local environment

Tool: kerno_start_environment

This kicks off a background job that prepares Docker-style configuration for one application in your project and brings the dependent services up (databases, caches, the service itself, and whatever else Kerno infers). It returns immediately with a job id and a log location; the work itself often takes several minutes and can run longer than a single chat round-trip, so your assistant should check progress using the job tool rather than expecting an instant “done.”

Example prompts

You can ask in plain language; the assistant should map that to the right tool calls (including listing applications first if needed).

• “Use Kerno to start the local environment for our main API. List applications if you’re not sure which one, then start the environment for the backend service that serves HTTP.”

• “Spin up Kerno’s Docker stack for the payments service module in this workspace and tell me when it’s healthy or if something failed.”

• “I need a full local backend for development—use Kerno start environment on the supported app that matches our Node API (not the worker-only package).”

What “application” means and how to choose one

Kerno scans your repository and splits what it finds into applications: units it can treat as a service boundary (typically something that exposes HTTP or is the “main” backend you run locally). You will see:

• Supported applications — Kerno can generate and run a local stack for these.

• Unsupported entries — Kerno explains why (for example not yet compatible); you cannot drive kerno_start_environment for those in the same way.

Each supported application has an id and a name. For kerno_start_environment you must pass one of them as app:

• Use the name when it clearly matches what you mean (“api”, “backend”, a package folder name).

• Use the id when two modules look similar or when listing endpoints or tests complains about ambiguity—id is the stable, unambiguous choice.

If you are unsure, ask your assistant to run kerno_get_applications first and pick the supported row that matches the service you want running locally.

Tip: Only one start-environment job runs per workspace + application at a time. Wait for that job to finish before asking to bring the same stack up again or to use other compose actions for that app.

---

List applications and HTTP routes

kerno_get_applications — Run this early. It analyzes the workspace and returns the application list, a workspace identifier, and a suggested next step.

kerno_list_endpoints — After you know your applications, this lists HTTP routes Kerno discovered (grouped by where they are implemented in code). It also shows which routes already have saved scenario tests. You must pass a scope (see below); use all when you want every route for the apps you care about.

Use the same scope here as you plan for baseline capture or validation so you see exactly the routes that will be included.

---

Baseline tests (capture behaviour)

Tool: kerno_capture_baseline

Use this when you want Kerno to create or refresh integration-style HTTP tests and store baselines (reference behaviour) for endpoints. It runs as a long background job and should only be used once the local environment for the relevant application is up and healthy.

Scopes — what you can ask for

The scope tells Kerno how much of the API to cover in this run. Pick the smallest scope that matches your goal:

Scope	What it means for you
all	Cover every HTTP endpoint Kerno has analyzed (optionally limited to one application if you pass app). Use when onboarding a service or establishing baselines across the whole API.
file: your/path/to/handler.ts	Only endpoints implemented in that source file (path is relative to the project root, in the same form Kerno shows when listing endpoints). Use when you changed one handler file and want tests only for that area.
endpoint: METHOD path	A single route, for example endpoint:POST /api/orders. Use for a tight loop on one API change.

If Kerno reports that the target is ambiguous (the same route exists in more than one module), pass app using the application id from kerno_get_applications.

Optional user_message lets you add plain-language hints (for example “focus on error responses for invalid payloads”) that flow into Kerno’s planning step.

Practical flow: After code or API changes, prefer validation first; if tests are missing or hopelessly out of date, run baseline capture again with the same scope rather than manually editing generated test files.

---

Validation (re-run tests against the running stack)

Tool: kerno_validate

This runs existing HTTP scenario tests against your live local stack and checks them against saved baselines when they exist. It is the right tool right after you change handlers or response shapes.

Scopes overlap with baseline capture, with one extra option:

Scope	What it means for you
all	Run scenarios for every analyzed endpoint (optionally one app).
changed	Only endpoints touched by your current git changes (compared to the last commit). Ideal for “did my PR break anything?” without running the entire suite.
file: path	Only endpoints tied to that source file.
endpoint: METHOD path	Only that route.

If listing endpoints shows no tests for routes in scope, run kerno_capture_baseline for that scope first (with the environment healthy).

---

Following background jobs

Tool: kerno_job

Long operations (kerno_start_environment, kerno_capture_baseline, kerno_validate) return a job id. Use kerno_job to see status, read progress, and learn when the job succeeded or failed. Chat clients often limit how long a single tool call can wait; your assistant may need to check the job a few times or follow the log path Kerno provides, rather than blocking on one call until completion.

When a job finishes, treat that job id as done—do not reuse it for further checks.

---

Other Kerno tools (overview)

Tool	In brief
kerno_healthcheck	Confirms prerequisites (for example Docker and authentication) before heavier steps.
kerno_compose_up / kerno_compose_down	Start or stop an already-generated stack for one application—typically after a successful start-environment job, unless your team uses a different runbook.
kerno_environments_status	See status across applications without starting anything.
kerno_compose_status / kerno_compose_logs	Inspect one application’s compose state or service logs.
kerno_approve / kerno_reject	Optional workflow step to record that you accept or reject validation results (for example in a review checklist).

---

Code search and navigation

Kerno also exposes tools to explore the codebase structurally: discover modules, see where libraries and symbols are used, jump from a line in a file to its definition or references, and walk downstream call chains from a selected piece of code.

Typical flow at a high level:

1. Scan the workspace to list code modules and their roots.

2. Index a module you care about (first run can take time; later runs reuse the index).

3. Use heatmaps to see where dependencies and specific symbols concentrate across folders.

4. Find usages, find definition, find references, and call hierarchy to narrow down impact and navigate like in an IDE.

Use the exact symbol names your assistant receives from the heatmap tools when searching for usages—approximate names usually will not match.

---

Summary

• Start with kerno_get_applications to understand applications, then kerno_start_environment with a clear app choice to bring one service stack online.

• Use kerno_list_endpoints with an explicit scope to see routes and existing tests.

• kerno_capture_baseline defines what to cover via scope (whole API, one file, or one endpoint).

• kerno_validate re-runs tests; changed scope fits day-to-day edits.

• Use kerno_job to track long-running work; use code search tools for navigation and impact exploration beyond HTTP tests.