aethis-mcp
Advanced tools
MCP server for the Aethis developer API — eligibility checks via Claude, Cursor, Windsurf
MCP server for the Aethis decision engine. Compile legislation, policy, contracts, and regulation into deterministic logic — same input, same answer, every time, with a full audit trail.
Install · Skills · Quick start · Tools · Setup · Authoring · DSL · Troubleshooting
Authoring is in private beta. Decision tools (
aethis_decide,aethis_schema,aethis_explain,aethis_next_question) are public — no key required. Authoring tools (rule generation, test refinement, publishing) require an invite. Request access at aethis.ai/developer-access.
Recommended — one command via aethis-cli:
uv tool install aethis-cli
aethis mcp install --target all
Wires the server into claude-code, cursor, claude-desktop, or windsurf. Idempotent. Restart your editor to pick up the change. Re-run after aethis account generate rotates a key. Full options: aethis mcp install --help.
Manual install:
claude mcp add aethis -- npx -y aethis-mcp
For Cursor / Claude Desktop / Windsurf manual config, see Setup.
Onboarding an AI coding agent end-to-end? See docs.aethis.ai/agents/onboarding — install + verify + auth + workflow patterns in one page.
After the MCP server is installed, add reusable agent workflows with aethis-skills:
npx skills add Aethis-ai/aethis-skills
The skills package provides workflows for policy-to-ruleset authoring, test/refine/publish loops, decisions with trace, and regression comparison. It calls the MCP tools in this package; it does not replace the MCP server.
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)"
}
}
Public rulesets work without a key. Browse: aethis_discover_rulesets({}) or docs.aethis.ai.
Engine determinism + accuracy benchmarks: Aethis-ai/confidently-wrong-benchmark.
35 tools across six groups.
| Group | Access | Tools |
|---|---|---|
| Decision | public | aethis_decide, aethis_schema, aethis_next_question, aethis_explain, aethis_explain_failure, aethis_graph |
| Discovery — public catalogue | public | aethis_discover_rulesets |
| Discovery — your tenant | private beta | aethis_list_projects, aethis_list_rulesets, aethis_list_rulebooks, aethis_rulebook_schema |
| Authoring — rulebooks | private beta | aethis_create_rulebook, aethis_update_rulebook |
| Authoring — sections & fields | private beta | aethis_discover_sections, aethis_refine_sections, aethis_validate_sections, aethis_set_field_spec, aethis_discover_fields, aethis_refine_fields, aethis_validate_fields |
| Authoring — generation | private beta | aethis_create_ruleset, aethis_set_tests, aethis_add_guidance, aethis_list_guidance, aethis_generate_and_test, aethis_generation_status, aethis_cancel_generation, aethis_refine, aethis_publish, aethis_add_domain_guidance, aethis_list_domain_guidance |
| Management | private beta | aethis_archive_project, aethis_archive_ruleset |
aethis_graph is public for a public showcase ruleset (ruleset_id) and tenant-scoped for a rulebook (rulebook_id) — it returns the ruleset-map graph ({nodes, edges, sections, stats}, each node's display.sentence/display.routes/display.expr) plus a ready-to-render mermaid diagram string. Pass include_graph_overlay: true to aethis_decide to get that same graph back with a specific decision's per-criterion status (satisfied/not_satisfied/pending) stamped onto it (graph_overlay in the response) — a "you are here" map for those inputs.
aethis_create_rulebook / aethis_update_rulebook manage a Rulebook's identity (name/domain/slug/description) and robot_hints — beat-keyed natural-language guidance for the conversational agent. Active beats: general_context, preamble, session_start, postamble, session_end, stuck. Reserved (accepted, not yet acted on): persona, conversational_style, section_transition. Composition (bridging rulesets via outcome_logic) is a separate, larger surface not covered by these two tools yet.
Evaluate eligibility (2 calls):
aethis_schema(ruleset_id) → fields needed
aethis_decide(ruleset_id, fields) → eligible / not_eligible / undetermined
Pass include_trace: true for the per-criterion evaluation trail. Pass include_explanation: true for human-readable rule descriptions.
aethis_decide accepts either ruleset_id (single ruleset, may be public) or rulebook_id (composed multi-ruleset rulebook) — the two are mutually exclusive. Rulebook decide always requires an API key (AETHIS_API_KEY); anonymous callers get HTTP 401. aethis_graph follows the same ruleset_id/rulebook_id split for the underlying map.
Conversational eligibility (next-question routing):
aethis_next_question(ruleset_id, field_values)
Returns the most informative remaining question and the optimal_path of remaining questions. Call again after each answer; the engine recomputes from the updated state. Stops when a decision is reachable.
Authoring (private beta): see Authoring.
| Prompt | Description |
|---|---|
aethis-author | Step-by-step TDD authoring workflow |
aethis-decide | Decision workflow guide; accepts optional ruleset_id |
Decision tools work with no key. For invited authoring access, run aethis login, then install with aethis mcp install --target <client>. The installer references a saved profile so the host configuration does not contain the API key.
# Decision tools only
claude mcp add aethis -- npx -y aethis-mcp
# With authoring access
claude mcp add aethis -e AETHIS_PROFILE=default -e XDG_CONFIG_HOME=/absolute/path/to/config -- 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"]
}
}
}
For authoring, add "env": { "AETHIS_PROFILE": "default", "XDG_CONFIG_HOME": "/absolute/path/to/config" }. Use your saved profile name and the absolute directory containing aethis/credentials (normally your home directory’s .config).
Add to ~/.cursor/mcp.json or ~/.codeium/windsurf/mcp_config.json (same JSON shape).
AETHIS_PROFILE — non-secret saved profile name. It pins the account and endpoint used by this registration, even if the CLI’s active_profile later changes.XDG_CONFIG_HOME — absolute config directory containing aethis/credentials. Relative values and credentials symlinks escaping your home/config directory are refused; credential files must have no group/other permission bits (normally 0600).AETHIS_API_KEY — optional deliberate process-environment override for the platform key. Prefer saved-profile references when installing; avoid putting raw keys in host config or command arguments. The host must securely supply the process environment; it may not inherit your shell environment.ANTHROPIC_API_KEY — forwarded per-request to aethis_generate_and_test. Used per-call, never stored. See Passing your Anthropic key safely below — prefer the env-var or keychain reference forms over passing the raw key as a tool argument.aethis account generate + aethis account revoke <key_id>. Mint one key per machine for surgical revocation.MCP parses the CLI credentials file as YAML. AETHIS_PROFILE selects a named profile; otherwise the file’s active_profile (or default) selects it. The profile supplies both its API key and base_url, with https://api.aethis.ai as the default endpoint. With an explicit AETHIS_PROFILE, AETHIS_API_KEY and AETHIS_BASE_URL deliberately override their respective values. Without an explicit profile selector, AETHIS_API_KEY uses AETHIS_BASE_URL or the default endpoint, ignoring the implicitly active profile (including implicit anonymous). Missing or malformed explicitly selected profiles fail visibly, including when environment overrides are present. Explicit AETHIS_PROFILE=anonymous always stays unsigned. After anonymous setup, run aethis login and install again to reference the saved authoring profile, then restart the host.
A saved profile outranks old macOS Keychain entries. If no profile is configured and no explicit name is selected, MCP can use the legacy default keychain entry, then the older flat credentials.yaml file. Flat api_key/base_url files at aethis/credentials remain supported. A configured profile awaiting login stays unsigned instead of borrowing another stored key.
The server keeps its authenticated startup key and endpoint paired until restart. If it started without a key, an authenticated tool can pick up a later login for the same endpoint. A changed endpoint causes a visible refusal: restart the MCP host to load the new pair. Startup stderr reports only the credential source, never key values.
Authoring tools (aethis_generate_and_test, aethis_refine, aethis_discover_fields, aethis_refine_fields, aethis_discover_sections, aethis_refine_sections) need an Anthropic API key per call. Three accepted forms — listed in preferred order:
anthropic_key_env (recommended). Name of an env var (set in the MCP client config) that holds the key. The raw value never appears in the tool call payload, so it does not land in the MCP host's session transcript on disk.
// claude_desktop_config.json
{
"mcpServers": {
"aethis": {
"command": "npx",
"args": ["aethis-mcp"],
"env": {
"AETHIS_PROFILE": "default",
"XDG_CONFIG_HOME": "/absolute/path/to/config",
"ANTHROPIC_API_KEY": "sk-ant-..." // never echoed back to the LLM
}
}
}
}
aethis_generate_and_test({ project_id, anthropic_key_env: "ANTHROPIC_API_KEY" })
anthropic_key_keychain (macOS). A keychain reference — either "account" (service defaults to aethis-anthropic-key) or "service:account". Store the key once with security add-generic-password -U -s aethis-anthropic-key -a my-anthropic -w 'sk-ant-...', then call:
aethis_generate_and_test({ project_id, anthropic_key_keychain: "my-anthropic" })
anthropic_key (deprecated). Pass the raw key as a tool argument. Accepted for backwards compatibility, but the raw value is written verbatim to the host's session transcript JSONL on disk. If a key was ever passed this way, rotate it before relying on the safer forms.
Authoring requires an invite. Request access. Decision tools (above) are public.
Three-phase workflow. Phases 1–2 are for multi-section domains; skip them for single-section rules and go straight to Phase 3.
aethis_discover_sections({ domain, sources: [{ name, content }, ...] })
aethis_validate_sections({ domain, expected_sections, discovered_sections })
aethis_refine_sections({ domain, feedback, sources })
aethis_set_field_spec({
project_id,
expected_fields: [{ key, sort, enum_values? }, ...]
})
aethis_discover_fields({ project_id }) // auto-validates against the spec if set
aethis_refine_fields({ project_id, feedback })
aethis_validate_fields({ project_id, expected_fields })
aethis_create_ruleset({
name, section_id, domain?, source_text,
test_cases: [{ name, field_values, expected_outcome }, ...]
})
aethis_generate_and_test({ project_id })
aethis_refine({ project_id, feedback }) // iterate until tests pass
aethis_publish({ project_id }) // refuses if tests fail; returns ruleset_id on success
If generation polling times out, call aethis_generation_status({ project_id })
before retrying: use its telemetry_availability, server-authoritative
worker_lifecycle, and retry_readiness, and retry only when readiness is
ready. An old heartbeat alone is not proof that the worker died. Call
aethis_cancel_generation({ project_id, job_id, confirm_job_id }) only after
showing the observed job_id and receiving explicit confirmation to abandon
that active run. It releases the project's job ownership, but worker shutdown
may be cooperative rather than immediate; inspect the returned detail. It is a
destructive, API-key-protected mutation. The response distinguishes a new
cancelled transition from the idempotent already_cancelled result.
Targeted hints without regenerating, plus cross-section principles for a domain:
aethis_add_guidance({ project_id, guidance_text, process_type })
aethis_list_guidance({ project_id })
aethis_add_domain_guidance({ domain, guidance_text, process_type, notes? })
aethis_list_domain_guidance({ domain })
process_type is rule_generation (default) or field_extraction.
aethis_explain_failure({
ruleset_id, field_values, expected_outcome, test_name
})
// Returns criterion statuses, the failing rule, and a targeted fix hint.
[!IMPORTANT] Tests are the publish gate.
aethis_publishrefuses to publish a ruleset with a failing test. SMEs write the tests; the LLM generates the rules from source text + guidance; the platform refuses to ship rules that don't satisfy the tests. Better tests = faster convergence.
[!IMPORTANT] Anthropic key required for authoring. Prefer
anthropic_key_env(env var name) oranthropic_key_keychain(macOS keychain ref) over the rawanthropic_keyargument — see Passing your Anthropic key safely. Used per-request, never stored server-side; the raw form, however, lands in the MCP host's session transcript on disk.
[!IMPORTANT] DATE fields use integer ordinals (
date.toordinal()), not ISO strings.2025-04-13=739354. Quick conversion:python3 -c "from datetime import date; print(date(2025,4,13).toordinal())".
| Type | Description |
|---|---|
Bool | True / false |
Int | Integer (counts, money as pence, percentages as integers) |
Enum | Closed set of named values |
Date | Integer ordinal — date.toordinal() |
Duration | Integer days |
String | Free text — prefer Enum for known sets |
| Category | Operators |
|---|---|
| Logic | AND, OR, NOT, IMPLIES |
| Comparison | =, ≠, <, ≤, >, ≥ |
| Membership | IN [v1, v2, ...] |
| Arithmetic | +, − for Int/Date; * for Int |
| Aggregation | min(...), max(...) |
days_between(date_a, date_b) → Intyears_between(date_a, date_b) → Int — completed whole years between the two dates (leap-correct). Use this for age from a date-of-birth field; never derive age as days_between(...) / 365.min(a, b, ...), max(a, b, ...) → Int5 * 365 → 1825)Int / Bool)eligible / not_eligible / undetermined)| Error | Cause | Fix |
|---|---|---|
API key is required | AETHIS_API_KEY not set (authoring) | Configure in MCP client settings, not shell profile |
X-Anthropic-Key header is required | Missing Anthropic key | Pass anthropic_key_env (preferred) / anthropic_key_keychain / anthropic_key on the tool call. See Passing your Anthropic key safely. |
Ruleset not found (404) | Wrong ID or archived | aethis_list_projects → aethis_list_rulesets |
Rate limit exceeded (429) | Daily limit | Client retries automatically. eng@aethis.ai for higher tier |
Cannot publish: tests failing | Tests don't pass | aethis_refine until all tests pass |
| Generation timeout (504) | Server still generating (5–15 min normal) | Wait, then aethis_list_rulesets({ project_id }) to check. Don't re-trigger |
Expected an integer for <field>, got str | DATE field passed as ISO string | Use date.toordinal() integer |
git clone https://github.com/Aethis-ai/aethis-mcp.git
cd aethis-mcp && npm install && npm test && npm run build
MIT
FAQs
MCP server for the Aethis developer API — eligibility checks via Claude, Cursor, Windsurf
The npm package aethis-mcp receives a total of 54 weekly downloads. As such, aethis-mcp popularity was classified as not popular.
We found that aethis-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
Lovable’s OJ rewrites Vite’s dev server in Rust, reducing memory use and preview times as AI lowers the cost of open source reimplementation.
Security News
It has been one year since Shai-Hulud made its first appearance on npm.
Research
/Security News
Operators behind PolinRider used a compromised GitHub account to plant malware in four development versions of a Packagist package with 700,000+ downloads.