Onboarding for AI coding agents

You are either an AI coding agent, or the human controlling one. This page wires Aethis into Claude Code, Cursor, Windsurf, Claude Desktop, or another MCP-compatible client. After setup, the human gives natural-language instructions; the agent calls Aethis tools for decisions, traces, test authoring, ruleset creation, generation, refinement, and publishing. If you are the human, you do not need to hand-write API calls. Connect the MCP server once, restart your editor, then talk to your coding agent.

Quick prompt — verify and run a decision

Copy this prompt and paste it directly into Claude Code, Cursor, or Windsurf. It verifies your MCP install and runs a live decision in one step — no setup knowledge required.

1. Run `claude mcp list` and confirm an `aethis` server appears with a connected status.
2. Call aethis_decide with:
     ruleset_id: "aethis/spacecraft-crew-certification"
     field_values: { "space.crew.species": "Vogon" }
     include_trace: true
3. Report the decision outcome and the reason in plain language.

If your editor isn’t Claude Code, your agent may surface the MCP server under a slightly different name — check the client’s tools list for aethis_decide.

The human workflow

Your job is to provide judgement. The agent’s job is to handle the mechanical calls.

Connect the MCP server.
Restart the editor so the agent can see the tools.
Ask the agent for the task in plain English.
Approve checkpoints: source sections, field names, test cases, guidance hints, and publication.

For example:

Use Aethis MCP to check whether a Vogon is eligible for spacecraft crew certification.
The ruleset_id is aethis/spacecraft-crew-certification.
Call aethis_decide with include_trace: true and explain the failing criterion.

For authoring:

Use Aethis MCP to turn this policy into a tested ruleset.
First identify the input fields and write test cases from the examples I give you.
Stop for my approval before generation, and do not publish until all tests pass.

If you already know the ruleset_id, include it in the prompt. That avoids the agent wasting a turn trying to browse your private tenant projects.

Setup

If aethis-cli is available on the user’s machine, one command wires up the MCP server in their editor’s config:

aethis mcp install --target all
# or one editor at a time: --target claude-code | cursor | claude-desktop | windsurf

If aethis-cli is not installed, fall back to the per-client manual command:

Claude Code
Claude Desktop / Cursor / Windsurf

claude mcp add aethis -- npx -y aethis-mcp

Add to the client’s MCP config file (paths in MCP server overview):

{
  "mcpServers": {
    "aethis": {
      "command": "npx",
      "args": ["-y", "aethis-mcp"]
    }
  }
}

After install, restart the editor. Decision tools (aethis_decide, aethis_schema, aethis_explain, aethis_next_question) are now available with no key. In Claude Code, you can verify the server is visible with:

claude mcp list

Look for an aethis server with a connected status. For routing nuance (which interface for which task), see Which interface to use.

Verify

Ask the agent to make one decision against a public ruleset. If you are the agent, call:

aethis_decide({
  ruleset_id: "aethis/spacecraft-crew-certification",
  field_values: { "space.crew.species": "Vogon" },
  include_trace: true
})

{
  "decision": "not_eligible",
  "fields_provided": 1,
  "fields_evaluated": 11,
  "trace": {
    "species_check": "FAIL — species is 'Vogon' (disqualifying, Section 3)"
  }
}

If you get this response, the install is working. Browse public showcase rulesets with aethis_discover_rulesets({}). Use aethis_list_projects followed by aethis_list_rulesets only for the user’s authenticated private tenant.

Auth model

Decision tools (aethis_decide, aethis_schema, aethis_explain, aethis_next_question) are public — no key required. Authoring tools require an invite (request access). The user’s AETHIS_API_KEY (ak_live_...) goes in the MCP client’s config file, not the shell — the MCP server doesn’t inherit shell env. Generation tools also need an Anthropic key. Prefer passing it by reference — anthropic_key_env (the name of an env var holding the key) or anthropic_key_keychain (a macOS keychain item) — to aethis_generate_and_test / aethis_refine, rather than the deprecated raw anthropic_key, which lands verbatim in the host’s session transcript. Either way it is used only for that request and never stored.

Workflow patterns

Common tasks an agent will be asked to do. Each maps to one MCP prompt or a short tool sequence.

1. User asks: “Check whether X is eligible for Y”

Use the aethis-decide prompt, or run the two-call sequence directly:

aethis_schema({ ruleset_id: "..." })          // discover required fields
aethis_decide({ ruleset_id, field_values })   // returns eligible | not_eligible | undetermined

Pass include_trace: true for the per-criterion evaluation trail. Pass include_explanation: true for human-readable rule descriptions. If the user provides facts conversationally rather than as a complete struct, switch to pattern 4.

2. User asks: “Why did this come out this way?”

Two tools, depending on the question:

Explain a decision (rule-text) — aethis_explain({ ruleset_id }) returns the rules in human-readable form. Use this when the user wants to understand the rule structure before or after a decision.
Diagnose a failing test — aethis_explain_failure({ ruleset_id, field_values, expected_outcome, test_name }) returns the criterion that failed and a targeted fix hint. Use this during authoring when a test doesn’t pass.

3. User asks: “Encode these rules from a policy doc” (private beta)

Use the aethis-author prompt and follow Author a rule from legislation. Stop and confirm with the user at the end of each phase — a rule that ships wrong returns wrong decisions to every caller. The human should supply:

Source text or source files
Example cases with expected outcomes
Domain corrections when the agent chooses the wrong section boundary or field name
Approval before generation and publication

The agent should handle:

Creating the draft ruleset with aethis_create_ruleset
Turning examples into test_cases
Running aethis_generate_and_test
Adding guidance when tests fail
Publishing only after the test gate is green

4. User wants a guided eligibility interview

For decisions where the user supplies facts one at a time:

let field_values = {}
loop:
  next = aethis_next_question({ ruleset_id, field_values })
  if next.is_eligible !== undefined: break    // decision reachable, stop asking
  ask the user next.question
  field_values[next.field_id] = parsed_answer

The engine computes the optimal next question after each answer — minimum questions to a reachable decision. Different applicants get different question paths.

Prompt patterns that work

Use these when you are the human driving the agent.

Known public ruleset

Use Aethis MCP only. The ruleset_id is aethis/uk-fsm/child-eligibility.
First call aethis_schema, ask me only for missing fields, then call aethis_decide
with include_trace: true. Explain the decision from the trace, not from general knowledge.

Browse before deciding

Use Aethis MCP only. Browse public showcase rulesets with aethis_discover_rulesets.
Choose the closest ruleset for this question, tell me which one you chose, then call
aethis_schema and aethis_decide.

Author from a policy document

Use Aethis MCP to author this policy as a ruleset. Draft the field vocabulary and
test cases first. Stop for my approval before generation. If tests fail, add targeted
guidance from the source text and iterate. Do not publish until every test passes.

Do not ask the agent to “figure it out” from memory. Make it use Aethis tools and source text. For regulated rules, the agent should cite the trace, the source clause, or the failing test, not its general-language reasoning.

Skills

The aethis-skills package provides higher-level workflows on top of the raw tools. Install once, then invoke by skill name:

Skill	Public/private	What it does
`decide-with-trace`	public	Run a decision with schema validation, full trace, and explanation in one go
`policy-to-ruleset`	private beta	Create or reuse a project, discover fields, write test-first scenarios, generate the first ruleset
`train-validate-publish`	private beta	Iterative guidance loop until tests pass, then publish
`regression-compare`	private beta	Compare decision behaviour between rule versions on a stable corpus, highlight regressions

Install: npx skills add Aethis-ai/aethis-skills. The skills assume the Aethis MCP tools are already wired up.

Tool reference

The full tool inventory, with each tool’s access tier (no key vs invite-only authoring key) and whether it writes, is generated from the shipped server: Capabilities and access. Parameters and worked examples: MCP server tools. Two MCP prompts: aethis-author (TDD authoring) and aethis-decide (decision lookup). Surfaced as selectable templates in compatible clients. Documented at MCP server overview — Prompts.

Going deeper

MCP server overview — install variants, key management, troubleshooting
Which interface to use — when to use MCP vs CLI vs SDK vs REST
Recipes — agent-consumable end-to-end flows
Decision envelope — the structure of aethis_decide responses
How it works — the build-time vs decision-time split
Errors — error codes and recovery patterns

Getting started (no key)

AI coding agents

Interfaces

Recipes

Authoring (invite-only)

Reference

Changelog

Onboarding for AI coding agents

Quick prompt — verify and run a decision

The human workflow

Setup

Verify

Auth model

Workflow patterns

1. User asks: “Check whether X is eligible for Y”

2. User asks: “Why did this come out this way?”

3. User asks: “Encode these rules from a policy doc” (private beta)

4. User wants a guided eligibility interview

Prompt patterns that work

Known public ruleset

Browse before deciding

Author from a policy document

Skills

Tool reference

Going deeper

​Quick prompt — verify and run a decision

​The human workflow

​Setup

​Verify

​Auth model

​Workflow patterns

​1. User asks: “Check whether X is eligible for Y”

​2. User asks: “Why did this come out this way?”

​3. User asks: “Encode these rules from a policy doc” (private beta)

​4. User wants a guided eligibility interview

​Prompt patterns that work

​Known public ruleset

​Browse before deciding

​Author from a policy document

​Skills

​Tool reference

​Going deeper

Quick prompt — verify and run a decision

The human workflow

Setup

Verify

Auth model

Workflow patterns

1. User asks: “Check whether X is eligible for Y”

2. User asks: “Why did this come out this way?”

3. User asks: “Encode these rules from a policy doc” (private beta)

4. User wants a guided eligibility interview

Prompt patterns that work

Known public ruleset

Browse before deciding

Author from a policy document

Skills

Tool reference

Going deeper