MCP server overview

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

Quick install (recommended)

If you have aethis-cli installed, one command wires up the MCP server in your editor’s config — picks up the API key cached by aethis login, drops a canonical aethis server entry into the right config file for each target, and preserves any other MCP servers you already have.

# All four clients 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 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. Re-run after aethis account generate rotates your key — the entry updates in place. 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)

Claude Code
Claude Desktop
Cursor / Windsurf

# Decision tools only (no key needed)
claude mcp add aethis -- npx -y aethis-mcp

# With authoring access
claude mcp add aethis -e AETHIS_API_KEY=ak_live_... -- npx -y aethis-mcp

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "aethis": {
      "command": "npx",
      "args": ["-y", "aethis-mcp"],
      "env": {
        "AETHIS_API_KEY": "ak_live_..."
      }
    }
  }
}

Omit the env block if you only need decision tools.

Add to .cursor/mcp.json or .windsurf/mcp.json — same JSON structure as Claude Desktop above.

The API key must be set in the MCP client’s config file, not in your shell profile. The MCP server process doesn’t inherit shell environment variables.

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

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

{
  "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.

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.

Authoring access

Authoring is invite-only private beta — request 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"`	`AETHIS_API_KEY` not set	Set in MCP client config (not shell profile). Decision tools don’t 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	Fix with `aethis_refine`, or pass `force: true` to override (not recommended for production).
Rate limit exceeded (429)	Operation-class limit hit (rolling 24h)	Wait and retry. Contact 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.
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.

Help improve this pageIf 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. Evaluating Aethis for a regulated workflow? Contact us directly.

Getting started (no key)

AI coding agents

Interfaces

Recipes

Authoring (invite-only)

Reference

Changelog

MCP server overview

What it is

Quick install (recommended)

Manual install (without aethis-cli)

Prompts

Try it — no API key required

Authoring with a coding agent

Authoring access

Troubleshooting

​What it is

​Quick install (recommended)

​Manual install (without aethis-cli)

​Prompts

​Try it — no API key required

​Authoring with a coding agent

​Authoring access

​Troubleshooting

What it is

Quick install (recommended)

Manual install (without aethis-cli)

Prompts

Try it — no API key required

Authoring with a coding agent

Authoring access

Troubleshooting