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.
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
aethis-cli is not installed, fall back to the per-client manual command:
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"]
}
}
}
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:
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)"
}
}
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, passed as anthropic_key to aethis_generate_and_test / aethis_refine 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
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
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 |
npx skills add Aethis-ai/aethis-skills. The skills assume the Aethis MCP tools are already wired up.
25 tools across decision, authoring, discovery, and management groups. Full list with parameters: 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