Skip to content

Model Context Protocol (MCP) Tools

This page describes the tools exposed by the Ennodia Model Context Protocol (MCP) server. The normal entrypoint is ennodia_run. It starts a visible orchestration and returns a run ID. Use ennodia_get_run to poll status, events, child task IDs, Judge + Result Advisor state, and the final answer.

GoalTool sequence
Check local setupennodia_list_harnesses
Preview route and costennodia_estimate_budget
Preview compositional shard costennodia_estimate_compositional_budget
Request a tailored team, inspect it, then launch itennodia_start_plan_advice -> ennodia_get_plan_advice -> ennodia_start_advised_plan
Start a visible end-to-end runennodia_run -> ennodia_get_run
Start focused review shardsennodia_start_compositional -> ennodia_get_compositional_status
Debug raw child tasksennodia_start -> ennodia_get_task
Judge completed outputs and advise on the resultennodia_start_compare -> ennodia_get_compare
Install bundled skillsennodia_list_skills -> ennodia_install_skills
Inspect terminal receipts after restartennodia_history

For harness IDs and setup notes, see Supported Harnesses. For budget request examples, see Budgets and Limits.

ennodia_plan, ennodia_estimate_budget, ennodia_start, and ennodia_run use local harness discovery plus either a caller-provided category or a lightweight keyword fallback. Pass category when the agent caller knows the task type. Pass refresh: true to re-scan installed commands before planning or starting work.

ennodia_start and ennodia_run also accept skillIds. Ennodia treats skills as native Agent Skills: folders containing SKILL.md, installed in paths supported by each harness. It does not inline full skill content into the delegated prompt. Task and run views include selected skill metadata in appliedSkills.

ennodia_estimate_budget, ennodia_estimate_compositional_budget, ennodia_start, ennodia_run, ennodia_start_compare, ennodia_start_plan_advice, and ennodia_start_advised_plan support a budget object for local preflight enforcement. Budgeting is an input-token estimate plus child-task count guard. It does not claim to know provider billing, output tokens, cache behavior, harness-internal context, or private subscription quota.

Ennodia uses category before keyword classification. Valid categories are code, research, browser, image, and general. The fallback classifier uses strong browser, image, code, and research signals. Bare words such as review or page do not route on their own. Pass harnessId to skip adapter choice and target a specific adapter.

harnessId forces a specific adapter. Current adapter IDs are:

Each adapter starts a supported command-line interface (CLI).

IDTool
claude-codeClaude Code
codexCodex CLI
opencodeOpenCode
kiloKilo Code
kiroKiro CLI
clineCline CLI
hermes-agentHermes Agent
antigravityAntigravity

Fields named maxOutputChars, maxAnswerChars, or maxCandidateChars bound returned text. 0 omits that text while still returning status, IDs, timing, and character counts.

Detects supported local artificial intelligence (AI) tools and reports availability, runnable state, command path, version, capabilities, and adapter notes.

InputDefaultMeaning
refreshfalseIgnore the short discovery cache and re-scan.

Use this first when a client setup, command path, or adapter is not behaving as expected.

Discovers native Agent Skills from supported harness locations, plus bundled Ennodia skills that can be installed into those locations:

  • Codex and agent-compatible: .agents/skills, ~/.agents/skills
  • Claude Code: .claude/skills, ~/.claude/skills
  • OpenCode native: .opencode/skills, ~/.config/opencode/skills
  • OpenCode compatible: .agents/skills, ~/.agents/skills, .claude/skills, ~/.claude/skills
  • Antigravity: .agent/skills, ~/.gemini/antigravity/skills
  • Ennodia bundled installable skills under skills

The list response returns summaries, searched directories, installation metadata, and load warnings. It does not return full instruction text.

InputDefaultMeaning
cwdserver process cwdOptional working directory to locate project-specific skills.

Installs bundled Ennodia skills into native harness skill directories. It defaults to dryRun: true, so callers can inspect planned writes first.

InputDefaultMeaning
skillIdsall bundledBundled skill IDs to install.
harnessIdsCodex, Claude Code, OpenCode, AntigravityNative harness locations to target.
scopeprojectproject or user.
cwdrequired for project scopeProject directory used for project installs.
overwritefalseReplace existing target skill folders.
dryRuntruePreview without copying files.

Classifies a prompt and previews the route Ennodia would take without starting a child process.

InputDefaultMeaning
promptrequiredTask text to classify.
categoryfallback classifierOptional caller-provided category: code, research, browser, image, or general.
refreshfalseRe-scan harness discovery before planning.
includeMermaidtrueInclude a presentational Mermaid route diagram. Set false for compact machine reads.

Returns the category, routing reasons, ordered candidate harness IDs, selected harness, parallel execution guidance, Judge + Result Advisor guidance, and, by default, a Mermaid route diagram. Run and polling views do not embed that diagram.

Plan Advisor turns a natural-language task into a suggested team without making that suggestion executable by itself. Plan Advisor sees a frozen inventory of allowed harnesses, caller-approved models, installed skills, and hard size limits. It can propose only explicit worker slices containing a prompt, harness, optional model, and skill IDs. It cannot choose cwd, environment variables, arguments, permissions, isolation, timeouts, retries, or budgets.

The lifecycle is deliberately two-phase: request and inspect advice first, then launch the exact validated plan in a separate call. Ennodia rejects invalid Plan Advisor output as a whole and revalidates the plan digest and current inventory before starting any worker.

Starts one Plan Advisor task. It starts no proposed worker task and returns an advice id for polling with ennodia_get_plan_advice.

InputDefaultMeaning
promptrequiredWork for which Plan Advisor proposes a team.
cwdserver process cwdTarget directory used only to inventory project skills. The Plan Advisor task runs in a separate empty temporary directory.
refreshfalseRe-scan harnesses before freezing the inventory snapshot.
advisorHarnessIdharness priorityHarness used for the single Plan Advisor task.
advisorModelPlan Advisor harness defaultOptional model override for the Plan Advisor task.
allowedHarnessIdsall runnable public adaptersWorker harness IDs the proposal may select.
allowedModels{}Exact caller-approved worker model IDs grouped by harness. An omitted worker model means the harness default.
maxSlices8Maximum explicit worker slices. Capped at 64 and by budget.maxChildTasks when supplied.
maxSkillsPerSlice8Maximum native skills on one slice. Capped at 64.
maxTotalSkillAssignments32Maximum skill assignments across the plan. Capped at 1024.
timeoutMs300000Timeout for the one Plan Advisor task, capped at 1 hour.
budget.maxEstimatedInputTokensnoneFail before Plan Advisor starts, or reject its proposal, if the estimate exceeds this value.
budget.maxChildTasksnoneBound both the Plan Advisor start and proposed worker count.

The returned view begins in advising. Terminal states are ready, consumed, invalid, failed, and cancelled. Only ready advice can be authorized. Authorization changes the status to consumed. A consumed plan cannot run again. A ready view has a validated plan and planDigest.

Returns Plan Advisor status, validation issues, inventory snapshot ID, proposal, validated inert plan, and plan digest. It also returns budget checks, events, timing, and estimated time of arrival (ETA). A consumed view also returns consumedAt.

InputDefaultMeaning
adviceIdrequiredID returned by ennodia_start_plan_advice.
includeProposaltrueInclude the untrusted model-authored proposal when available.
includePlantrueInclude the validated inert plan when ready.
includeEventstrueInclude bounded lifecycle events.
maxEvents100Maximum events to return. Capped at 300. Use 0 to omit them.

Explicitly launches the exact plan from a ready advice result. Before the first worker starts, Ennodia checks the supplied digest and refreshes the inventory. It validates every harness and skill again. It confirms that explicit models remain in the unchanged caller allowlist and enforces the caller-owned runtime budget.

Provider model availability remains unverified until its harness runs. Digest mismatch, inventory drift, or deterministic validation failure starts zero workers. Successful authorization consumes the advice before task launch. The same advice cannot authorize a second launch.

InputDefaultMeaning
adviceIdrequiredReady advice ID returned by ennodia_start_plan_advice.
expectedPlanDigestrequiredExact planDigest returned by ennodia_get_plan_advice.
cwdinventoried directoryWorking directory for worker tasks.
isolateCwdfalseRun each worker against an ephemeral isolated copy of cwd. Isolation fails before task spawn if the copied tree contains a symbolic link. The reported task cwd is an execution trace. Ennodia deletes the temporary copy after the task becomes terminal.
timeoutMs300000Per-worker timeout, capped at 1 hour.
budget.maxEstimatedInputTokensnoneFail before any worker starts if the exact plan estimate exceeds this value.
budget.maxChildTasksnoneFail before any worker starts if the exact slice count exceeds this value.

The response reports the frozen plan and digest, task IDs mapped to slice IDs, execution controls, and the budget check. It also reports unrequested installed skills observed on the selected harnesses. This operation does not automatically run the Judge and Result Advisor comparison.

Cancels an advising request and its single Plan Advisor task. Pass adviceId from ennodia_start_plan_advice. Calling it for a terminal request returns the existing terminal view.

InputDefaultMeaning
adviceIdrequiredID returned by ennodia_start_plan_advice.

Lists recent Plan Advisor requests from the current MCP server process.

InputDefaultMeaning
includeProposalfalseInclude model-authored proposals.
includePlanfalseInclude validated inert plans.
includeEventsfalseInclude bounded event history.
maxEvents25Maximum events per item when included. Capped at 300.

Plans a run without starting child tasks, then estimates preflight input tokens and checks optional limits.

InputDefaultMeaning
promptrequiredTask text to classify, route, and estimate.
categoryfallback classifierOptional caller-provided category.
harnessIdplanner choiceForce one adapter by ID.
modeautoauto, single, or parallel.
compareautoInclude the Judge + Result Advisor pass in the estimate.
refreshfalseRe-scan harness discovery before planning.
maxOutputCharseffective 24000Characters assumed for each successful task in Compare. Ennodia estimates values above the Judge prompt cap at 24000.
budget.maxEstimatedInputTokensnoneMark the estimate exceeded above this input-token count.
budget.maxChildTasksnoneMark the estimate exceeded above this child-task count.

The response includes the route plan, selected harness IDs, estimate assumptions, subscription-limit check status, and exceeded issues.

Resolves focused compositional slices to harnesses, then estimates preflight input tokens and child task count without starting child processes.

InputDefaultMeaning
promptrequiredOverall task or question that every slice belongs to.
slices[].idgeneratedOptional stable slice ID. Supplied IDs must be unique.
slices[].titlenoneOptional short label for the slice.
slices[].promptrequiredFocused task prompt for the slice.
slices[].categoryfallback classifierOptional caller-provided route category for this slice.
slices[].harnessIdslice planner choiceOptional adapter ID for this slice.
slices[].modeladapter defaultOptional model override retained in the resolved slice summary.
slices[].skillIdsinheritedSlice-specific native skill IDs. An explicit list, including [], replaces batch skillIds.
cwdserver process cwdOptional working directory used to validate requested native skills.
refreshfalseRe-scan harness discovery before resolving slice routes.
skillIds[]Default installed native skill IDs for slices that omit slices[].skillIds.
includeCompareEstimatetrueInclude a later Judge + Result Advisor pass in the returned budget estimate.
maxOutputCharseffective 24000Characters assumed for each successful slice in Compare. Ennodia estimates values above the Judge prompt cap at 24000.
budget.maxEstimatedInputTokensnoneMark the estimate exceeded above this input-token count.
budget.maxChildTasksnoneMark the estimate exceeded above this child-task count.

The response includes resolved slice summaries, selected harness IDs, budget assumptions, subscription-limit check status, and exceeded issues.

Starts the full orchestration. It plans and executes one or more child tasks. It can run the Judge + Result Advisor over successful outputs. It exposes the final answer through ennodia_get_run.

Runs usually take minutes. Poll ennodia_get_run at sensible intervals. Trust remainingMs and etaConfidence. Do not give up after a few seconds.

InputDefaultMeaning
promptrequiredTask sent to the selected local AI tools.
categoryfallback classifierOptional caller-provided category.
harnessIdplanner choiceForce one adapter by ID.
modeautoauto, single, or parallel.
cwdserver process cwdWorking directory for child commands.
isolateCwdfalseRun each selected harness against an ephemeral isolated copy of cwd. Isolation fails before task spawn if the copied tree contains a symbolic link. The reported task cwd is an execution trace. Ennodia deletes the temporary copy after the task becomes terminal.
modeladapter defaultOptional model override passed to task harnesses.
timeoutMs300000Timeout for each child task, capped at 1 hour.
compareautoauto, true, or false.
refreshfalseRe-scan harness discovery before planning.
judgeHarnessIdCompare priorityHarness used for the Judge pass.
judgeModelJudge defaultOptional Judge model override.
advisorHarnessIdJudge harnessHarness used for the Result Advisor pass.
advisorModelResult Advisor harness defaultOptional Result Advisor model override.
synthesizerHarnessIddeprecatedCompatibility alias for advisorHarnessId. Ennodia rejects conflicting values.
synthesizerModeldeprecatedCompatibility alias for advisorModel. Ennodia rejects conflicting values.
maxOutputChars80000Characters per successful task loaded for Compare before the 24000-character Judge prompt cap.
skillIds[]Optional installed native skill IDs for selected harnesses.
budget.maxEstimatedInputTokensnoneFail before starting if estimated input tokens exceed this value.
budget.maxChildTasksnoneFail before starting if selected child tasks exceed this value.

Returns a run view with id, status, selected harnesses, child task IDs, comparison ID when one exists, events, timing, ETA, and budget estimate/check. It also returns the final answer when available. The important value is id. Poll it with ennodia_get_run.

Returns the current run state.

InputDefaultMeaning
runIdrequiredID returned by ennodia_run.
includeEventstrueInclude run event history.
maxEvents100Maximum run events to return. Capped at 300.
maxAnswerChars80000Maximum final-answer characters. Capped at 200000.

Terminal run states are succeeded, failed, and cancelled. A run is not complete before it reaches one of those states.

Cancels a high-level run and any active child task, Judge, or Result Advisor.

InputDefaultMeaning
runIdrequiredID returned by ennodia_run.

Cancellation is explicit. Do not present a run with cancelled status as a normal model failure.

Lists runs started by the current MCP server process.

InputDefaultMeaning
includeEventsfalseInclude bounded event history.
maxEvents25Maximum events per run. Capped at 300.
maxAnswerChars2000Maximum answer characters per run. Capped at 200000.

Live run history is bounded and in-memory. Restarting the MCP server clears in-progress state. Terminal receipts remain available through ennodia_history when history is enabled.

Lists terminal run snapshots persisted under the local history directory. Use it after a restart to inspect previous final answers and Judge disagreement analysis.

InputDefaultMeaning
limit20Maximum persisted run snapshots to return, newest first. Capped at 500.

History is enabled by default for createDefaultEnnodiaCore, written under ~/.ennodia/history/runs.jsonl, and capped to the most recent 500 terminal runs. Set ENNODIA_HISTORY=0 to opt out.

Starts one or more raw child tasks without a run-level Judge + Result Advisor pass. Use it for debugging adapters or manual comparison workflows.

InputDefaultMeaning
promptrequiredTask sent to the selected local AI tools.
categoryfallback classifierOptional caller-provided category.
harnessIdplanner choiceForce one adapter by ID.
modesinglesingle or parallel.
cwdserver process cwdWorking directory for child commands.
isolateCwdfalseRun each task against an ephemeral isolated copy of cwd. Isolation fails before task spawn if the copied tree contains a symbolic link. The reported task cwd is an execution trace. Ennodia deletes the temporary copy after the task becomes terminal.
modeladapter defaultOptional model override.
timeoutMs300000Timeout for each child task, capped at 1 hour.
refreshfalseRe-scan harness discovery before planning.
skillIds[]Optional installed native skill IDs for selected harnesses.
budget.maxEstimatedInputTokensnoneFail before starting if estimated input tokens exceed this value.
budget.maxChildTasksnoneFail before starting if selected child tasks exceed this value.

Returns started task IDs, the route plan, and the budget estimate/check.

Starts one focused child task per slice. Use it for large reviews where each agent can inspect a smaller part of the problem. The tool returns task IDs. poll them with ennodia_get_task, then pass the useful completed task IDs to ennodia_start_compare.

InputDefaultMeaning
promptrequiredOverall task or question that every slice belongs to.
slices[].idgeneratedOptional stable slice ID. Supplied IDs must be unique.
slices[].titlenoneOptional short label for the slice.
slices[].promptrequiredFocused task prompt for the slice.
slices[].categoryfallback classifierOptional caller-provided route category for this slice.
slices[].harnessIdslice planner choiceOptional adapter ID for this slice.
slices[].modeladapter defaultOptional model override for this slice.
slices[].skillIdsinheritedSlice-specific native skill IDs. An explicit list, including [], replaces batch skillIds.
cwdserver process cwdWorking directory for child commands.
isolateCwdfalseRun each slice against an ephemeral isolated copy of cwd. Isolation fails before task spawn if the copied tree contains a symbolic link. The reported task cwd is an execution trace. Ennodia deletes the temporary copy after the task becomes terminal.
timeoutMs300000Timeout for each slice task, capped at 1 hour.
refreshfalseRe-scan harness discovery before resolving slice routes.
skillIds[]Default installed native skill IDs for slices that omit slices[].skillIds.
includeCompareEstimatetrueInclude a later Judge + Result Advisor pass in the returned budget estimate.
maxOutputCharseffective 24000Characters assumed for each successful slice in Compare. Ennodia estimates values above the Judge prompt cap at 24000.
budget.maxEstimatedInputTokensnoneFail before starting if estimated input tokens exceed this value.
budget.maxChildTasksnoneFail before starting if slice child tasks exceed this value.

Returns slice task IDs, resolved harness IDs, the budget estimate/check, and a ready-to-use compareNext object for the later ennodia_start_compare call.

Inspects multiple shard task IDs at once, groups their states, and returns the successful non-empty task IDs ready for a Judge + Result Advisor comparison.

InputDefaultMeaning
taskIdsrequiredShard task IDs returned by ennodia_start_compositional.
promptnoneOptional comparison prompt included in compareNext when the minimum outputs are ready.
minSuccessfulTasksForCompare2Minimum successful non-empty outputs required for compareReady.
includeOutputfalseInclude bounded stdout and stderr previews for known tasks.
maxOutputChars2000Maximum stdout and stderr characters per task when output is included.

The response includes readyTaskIds, runningTaskIds, failedTaskIds, cancelledTaskIds, emptySucceededTaskIds, and missingTaskIds. It includes grouped counts, compact task summaries, and compareNext when a comparison prompt was supplied and the minimum task outputs are ready.

Returns task status, captured output, events, timing, and ETA.

InputDefaultMeaning
taskIdrequiredID returned by a raw, compositional, advised-plan, run, Plan Advisor, or Compare start.
includeOutputtrueInclude bounded stdout and stderr.
includeEventstrueInclude bounded task events.
maxOutputChars20000Maximum stdout and stderr characters. Capped at 200000.
maxEvents100Maximum task events. Capped at 300.

A task is terminal only after the child process exits and stdout/stderr have drained or timed out visibly.

Cancels a running task by task ID.

InputDefaultMeaning
taskIdrequiredID returned by a task start.

Lists recent tasks started by the current MCP server process. By default it returns a compact view. Request output or events only when you need them.

InputDefaultMeaning
includeOutputfalseInclude bounded stdout and stderr previews for each task.
includeEventsfalseInclude bounded task events for each task.
maxOutputChars4000Maximum stdout and stderr characters per task. Capped at 200000.
maxEvents25Maximum events per task. Capped at 300.

The existing ennodia_*_compare tool names remain for compatibility. Their public workflow is Judge + Result Advisor: the Judge analyzes the candidates, then Result Advisor produces the final recommendation. Result Advisor can degrade visibly to candidate-only advice when Judge analysis is unavailable.

Runs a Judge pass and then a Result Advisor pass over completed Ennodia tasks or caller-supplied responses.

InputDefaultMeaning
promptrequiredOriginal user task or question the candidates answer.
taskIds[]Completed Ennodia task IDs to compare.
responses[]Caller-supplied responses with IDs, labels, and text.
judgeHarnessIdCompare priorityHarness used for the Judge pass.
judgeModelJudge defaultOptional Judge model override.
advisorHarnessIdJudge harnessHarness used for the Result Advisor pass.
advisorModelResult Advisor harness defaultOptional Result Advisor model override.
synthesizerHarnessIddeprecatedCompatibility alias for advisorHarnessId. Ennodia rejects conflicting values.
synthesizerModeldeprecatedCompatibility alias for advisorModel. Ennodia rejects conflicting values.
cwdserver process cwdWorking directory for the Judge and Result Advisor tasks.
timeoutMs300000Timeout for each child task. Capped at 1 hour.
maxOutputChars80000Characters per task candidate loaded for Compare before the 24000-character Judge prompt cap.
budget.maxEstimatedInputTokensnoneFail before starting if estimated Judge/Result Advisor input tokens exceed this value.
budget.maxChildTasksnoneFail before starting if the Judge plus Result Advisor task count exceeds this value.

Compare requests that the Judge map agreements, contradictions, unique insights, blind spots, and risks. The Result Advisor uses that analysis plus the original candidates to return a typed answer, basis, confidence, and open questions. This is model-led comparison, not formal voting.

Returns comparison status, candidate inputs, Judge analysis, and typed Result Advisor output, child task IDs, degradation events, timing, and ETA. Deprecated synthesis fields remain available for compatibility.

InputDefaultMeaning
compareIdrequiredID returned by ennodia_start_compare or ennodia_run.
includeCandidatestrueInclude bounded candidate response previews.
includeEventstrueInclude bounded Judge and Result Advisor events.
maxCandidateChars8000Maximum characters per candidate. Capped at 200000.
maxEvents100Maximum comparison events. Capped at 300.

Cancels a running Judge + Result Advisor comparison and its active child task.

InputDefaultMeaning
compareIdrequiredID returned by ennodia_start_compare or ennodia_run.

Lists recent Judge + Result Advisor comparisons started by the current MCP server process.

InputDefaultMeaning
includeCandidatesfalseInclude bounded candidate response previews for each comparison.
includeEventsfalseInclude bounded Judge and Result Advisor events.
maxCandidateChars2000Maximum characters per candidate. Capped at 200000.
maxEvents25Maximum events per comparison. Capped at 300.