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

# MCP server overview

> Install and configure aethis-mcp for Claude Code, Codex, Claude Desktop, Cursor, and Windsurf.

## What it is

MCP (Model Context Protocol) is an open standard that lets AI coding agents call external tools directly from a conversation — no shell, no files. `aethis-mcp` implements this protocol, exposing tools for evaluating eligibility and for authoring rules from legislation.

Install it once. After that, your coding agent can call `aethis_decide`, `aethis_create_ruleset`, `aethis_generate_and_test`, and `aethis_publish` as naturally as it calls any other tool.

**Decision tools** (evaluate, schema, explain, graph, catalogue) work with no API key.\
**Authoring tools** (create, generate, publish) require an invite-only API key — [request access](https://aethis.ai/developer-access).

The generated per-tool inventory, with the access tier of each tool and the exact count the shipped server exposes, is on [Capabilities and access](/reference/capabilities#mcp-tool-inventory).

The canonical, case-sensitive MCP Registry server identity is
`io.github.Aethis-ai/aethis-mcp`. The npm package and install command remain
lowercase: `aethis-mcp` and `npx -y aethis-mcp`.

***

## Quick install (recommended)

If you have [`aethis-cli`](/interfaces/cli) installed, one command wires up the MCP server in your editor's config — records the selected credential-profile reference from `aethis login`, adds a canonical `aethis` server entry into the right config file for each target, and preserves any other MCP servers you already have.

```bash theme={null}
# All supported clients (including Codex) at once:
aethis mcp install --target all

# Or one at a time:
aethis mcp install --target claude-code      # writes ./.mcp.json (project-local)
aethis mcp install --target codex           # uses codex mcp add
aethis mcp install --target cursor           # ~/.cursor/mcp.json
aethis mcp install --target claude-desktop   # ~/Library/Application Support/Claude/...
aethis mcp install --target windsurf         # ~/.codeium/windsurf/mcp_config.json
```

Restart your editor to pick up the change. Restart after changing credentials. Re-run installation when selecting a different profile; only non-secret profile/configuration references are written. Reverse with `aethis mcp uninstall --target <client>` (only removes the `aethis` entry).

Don't have `aethis-cli`? Use the manual install below.

***

## Manual install (without aethis-cli)

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

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add aethis -- npx -y aethis-mcp
    codex mcp list
    codex mcp get aethis
    ```
  </Tab>

  <Tab title="Claude Desktop / Cursor / Windsurf">
    Add an Aethis entry to your client's MCP configuration:

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

    The Aethis CLI handles the client-specific paths, including `~/.codeium/windsurf/mcp_config.json` for Windsurf.
  </Tab>
</Tabs>

Public decisions need no key. For authoring, use a saved Aethis profile and the CLI installer to pin its non-secret reference. Manual launches use the selected profile in the credential file unless an explicit process-environment override applies. Never put key values in chat, command arguments or project configuration. The MCP child receives the environment supplied by its host; a desktop host launched elsewhere may not inherit variables from your terminal.

See [the staged agent guide](/agents/onboarding) for installing and invoking the four skills and transitioning from anonymous decisions to invited authoring.

***

## Prompts

MCP prompts are pre-built workflow guides that compatible clients can surface as selectable templates.

| Prompt | Description |
| - | - |
| `aethis-author` | Step-by-step TDD workflow: gather requirements → create ruleset → generate → refine → publish |
| `aethis-decide` | Decision workflow: find ruleset → get schema → evaluate. Accepts optional `ruleset_id` argument |

***

## Try it — no API key required

Decision tools work immediately. Two examples you can try now:

**UK Free School Meals — child eligibility:**

> Is a 10-year-old at a state-funded school eligible for Free School Meals?

```
aethis_decide({
  ruleset_id: "aethis/uk-fsm/child-eligibility",
  field_values: { "child.age": 10, "child.school_type": "state_funded" },
  include_trace: true
})
```

```json theme={null}
{
  "decision": "eligible",
  "fields_provided": 2,
  "fields_evaluated": 2,
  "trace": {
    "age_check": "PASS — age 10 is within 4–15 (FSM Regulations 2014, Regulation 3(1))",
    "school_type_check": "PASS — school_type is state_funded (FSM Regulations 2014, Regulation 3(2)(b))"
  }
}
```

**Spacecraft crew certification — Vogon applicant:**

> Is a Vogon eligible for spacecraft crew certification?

```
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)"
  }
}
```

One field provided. The engine determined a Vogon was disqualified without asking about flight hours, medical certificates, or anything else. It found the shortest path to a decision from the facts it already had.

***

## Authoring with a coding agent

Paste a policy document into Claude Code, Cursor, or Windsurf and ask the agent to author rules. The agent runs the tool calls; you confirm section boundaries, field names, test cases, and domain corrections at checkpoints. Full procedural flow: [Author a rule from legislation](/recipes/author-a-rule).

```text theme={null}
Use Aethis MCP to turn this policy into a tested ruleset.
Draft the input fields and test cases first, then stop for my approval.
Do not publish until all tests pass.
```

For the human-facing workflow, see [AI coding agent onboarding](/agents/onboarding).

***

## Authoring access

Authoring is invite-only private beta — [request access](https://aethis.ai/developer-access). Generation tools call an Anthropic model on your behalf and accept the key per request; it is used only for that request and never stored. Prefer passing the key **by reference** — `anthropic_key_env` (the name of an env var that holds the key) or `anthropic_key_keychain` (a macOS keychain item) — rather than the deprecated raw `anthropic_key`, which lands verbatim in the host's session transcript.

***

## Troubleshooting

| Error | Cause | Fix |
| - | - | - |
| `"API key is required"` | No authoring identity is available to the MCP process | Save and select your named CLI profile, reinstall for your chosen host, then restart the host. If using an explicit process environment, verify it reaches MCP securely; never copy the key into host configuration or the conversation. Decision tools do not need a key. |
| `"Ruleset not found"` (404) | Wrong ID or archived ruleset | For public showcase rulesets, use `aethis_discover_rulesets`; for private tenant rulesets, use `aethis_list_projects` → `aethis_list_rulesets`. |
| `"Cannot publish: tests failing"` | Tests don't pass | Diagnose the failed case, refine from the source, preserve reviewed expectations and rerun the complete suite before publishing. |
| Rate limit exceeded (429) | Operation-class limit hit (rolling 24h) | Wait and retry. Contact [eng@aethis.ai](mailto:eng@aethis.ai) for a higher tier. |
| Generation timeout (504) | Client timed out — normal for complex rules (5–15 min server-side) | See [Handling generation timeouts](/authoring/rule-generation#handling-generation-timeouts). |
| Date field named in `field_errors` | Value is neither ISO `"YYYY-MM-DD"` nor an integer ordinal | Pass either form (ISO accepted since engine 0.31.0; rulebooks need ordinals) — see [Date field values](/reference/errors#date-field-values). |

<Note>
  **Help improve this page**

  If something here is unclear or missing an example, use the feedback button at the bottom of the page.

  Found a bug? [Open a GitHub issue](https://github.com/Aethis-ai/feedback/issues). Evaluating Aethis for a regulated workflow? [Contact us directly](https://aethis.ai/developer-access).
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.