> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aethis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding for AI coding agents

> Connect Aethis to an AI coding agent, verify the MCP tools, then use natural-language prompts for decisions and rule authoring.

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

```text theme={null}
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.
```

<Tip>
  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`.
</Tip>

***

## The human workflow

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

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

For example:

```text theme={null}
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:

```text theme={null}
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.
```

<Tip>
  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.
</Tip>

## Setup

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

```bash theme={null}
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:

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add aethis -- npx -y aethis-mcp
    ```
  </Tab>

  <Tab title="Claude Desktop / Cursor / Windsurf">
    Add to the client's MCP config file (paths in [MCP server overview](/mcp-server/overview)):

    ```json theme={null}
    {
      "mcpServers": {
        "aethis": {
          "command": "npx",
          "args": ["-y", "aethis-mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

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:

```bash theme={null}
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](/interfaces/which-to-use).

***

## Verify

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

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

```json theme={null}
{
  "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](https://aethis.ai/developer-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`](/mcp-server/overview#prompts) prompt, or run the two-call sequence directly:

```js theme={null}
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`](/mcp-server/overview#prompts) prompt and follow [Author a rule from legislation](/recipes/author-a-rule). 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:

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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.
```

<Warning>
  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.
</Warning>

***

## Skills

The [`aethis-skills`](https://github.com/Aethis-ai/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

25 tools across decision, authoring, discovery, and management groups. Full list with parameters: [MCP server tools](/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](/mcp-server/overview#prompts).

***

## Going deeper

* [MCP server overview](/mcp-server/overview) — install variants, key management, troubleshooting
* [Which interface to use](/interfaces/which-to-use) — when to use MCP vs CLI vs SDK vs REST
* [Recipes](/recipes/evaluate-a-case) — agent-consumable end-to-end flows
* [Decision envelope](/concepts/decision-envelope) — the structure of `aethis_decide` responses
* [How it works](/concepts/how-it-works) — the build-time vs decision-time split
* [Errors](/reference/errors) — error codes and recovery patterns