Skip to main content
Glama
alethia-mcp

alethia-mcp

Official
by vitron-ai

Alethia MCP

AI agents can write software. Vitron makes sure it works.

Vitron is building execution and verification infrastructure for AI-powered software development. Alethia connects an AI agent to an application so it can run workflows, check behavior, inspect results, and iterate with evidence.

Alethia is available to MCP-compatible clients as a local server. Give your agent plain-English instructions such as “open the sign-in page, submit the test account, and confirm the dashboard appears.” The agent receives step results and can continue based on what happened.

npm version Bridge license: MIT Source

Related MCP server: mcp-policy-gateway

Get started

Install for Claude Code

The Claude Code plugin installs the MCP server and its workflow skill:

/plugin marketplace add vitron-ai/alethia-mcp
/plugin install alethia@vitronai

Restart Claude Code or run /reload-plugins.

To install only the skill, use alethia-mcp --install-skill after installing the package, or follow the manual skill instructions.

Install for another MCP client

Alethia requires Node.js 18 or later. Install the bridge:

npm install -g @vitronai/alethia

Add it to your MCP client's configuration:

{
  "mcpServers": {
    "alethia": {
      "command": "alethia-mcp"
    }
  }
}

For a temporary or always-current install, configure the client to run npm's package binary:

{
  "mcpServers": {
    "alethia": {
      "command": "npx",
      "args": ["-y", "@vitronai/alethia@latest"]
    }
  }
}

The bridge checks for compatible updates in the background unless ALETHIA_SKIP_AUTO_UPDATE=1. The @latest npx configuration resolves the latest published bridge when the client starts and may take longer on a cold cache.

Common client configuration locations:

Client

Configuration

Claude Code

~/.claude/mcp.json

Claude Desktop (macOS)

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop (Windows)

%APPDATA%\Claude\claude_desktop_config.json

Claude Desktop (Linux)

~/.config/Claude/claude_desktop_config.json

Cursor

Settings → MCP

Other clients

The client's MCP server configuration

Restart the client after changing its configuration. The proprietary runtime downloads on first use and is verified before it is installed. By default, the cockpit is visible while the agent works. Set ALETHIA_HEADLESS=1 to hide it; CI environments are detected automatically.

What your agent can do

Ask for an outcome; your agent selects and combines the tools.

Tool

Purpose

alethia_tell

Run newline-separated, plain-English instructions and return per-step results.

alethia_compile

Preview how instructions compile without executing them.

alethia_propose_tests

Inspect a page and suggest candidate test flows.

alethia_assert_safety

Check how the runtime's safety policy handles destructive actions on a page.

alethia_audit_wcag

Run an axe-core accessibility audit against WCAG 2.1 AA rules.

alethia_audit_nist

Check a page against selected NIST SP 800-53 Rev. 5 controls.

alethia_export_session

Export session records with SHA-256 integrity data.

alethia_tell_parallel

Run flows concurrently against multiple URLs.

alethia_screenshot, alethia_eval

Capture the current page or evaluate a JavaScript expression in that page.

alethia_status, alethia_activate_kill_switch

Check runtime status or halt automation.

alethia_serve_demo

Serve a built-in demo page on localhost.

alethia_show_cockpit, alethia_hide_cockpit

Show or hide the runtime's oversight window.

Accessibility and NIST audit tools require a valid runtime license. Some runtime builds include a bundled, time-limited trial for these tools; its expiry comes from the license issue date, so it may have expired before you download the build. Contact Vitron for current access.

The parallel tool supports up to two concurrent flows by default; a valid license can raise the limit to ten.

Sensitive inputs are blocked by default. The optional allowSensitiveInput: true setting is for legitimate authentication or payment tests.

Audit results are technical findings, not a certification or a claim of compliance.

Example prompts:

  • “Run a smoke test on my local app and confirm the checkout confirmation appears.”

  • “Preview these test instructions before running them.”

  • “Audit this page for accessibility issues and summarize findings by impact.”

  • “Check this admin page for destructive controls and report how the safety policy responds.”

  • “Export the session evidence when the checks are complete.”

For complete prompts and workflows, see the agent cookbook.

Use Alethia in a project or CI

No project-local package is required. Configure the MCP server once, then ask your agent to create a .alethia file in your repository and run it.

# tests/e2e/login.alethia
name login flow
navigate to http://localhost:5173
assert "Sign in" is visible
click Sign in
assert dashboard is visible

To run the file directly from a shell or CI job:

alethia run tests/e2e/login.alethia

The command exits with code 0 when all steps pass, 1 when a run fails, and 2 for invalid input. You can also pipe a test file into stdin:

cat tests/e2e/login.alethia | alethia run -

On Windows, use a file or stdin for multi-step runs. npm command shims may truncate real newlines passed as an argument. For a short inline test, separate steps with literal \n:

alethia run --nlp "navigate to http://localhost:5173\\nassert the page loaded"

PowerShell stdin example:

Get-Content tests\e2e\login.alethia -Raw | alethia run -

More CI guidance is in examples/github-actions.yml; project examples are in examples.

Run the MCP integration smoke test

The optional smoke test launches this bridge, calls its MCP tools, serves the bundled TaskFlow demo, and asks Alethia to verify that the page loads:

npm run test:alethia

This downloads and starts the proprietary runtime on first use, so it needs network access and an eligible local evaluation setup. The flow only opens the bundled local demo and checks that “TaskFlow” is visible. Keep it separate from npm test, which remains the fast, deterministic bridge test suite. Set ALETHIA_E2E_TIMEOUT_MS to change the default five-minute tool-call timeout.

Product and licensing

The npm package in this repository is the MIT-licensed MCP bridge. It is open source and does not contain the Alethia execution runtime.

The Alethia runtime is proprietary and closed source. The bridge downloads it separately from Alethia releases. Using this bridge does not grant rights to the runtime beyond the applicable runtime license. Review the runtime evaluation terms. Use beyond evaluation—including production or customer-facing use, non-local origins, or third-party reliance on generated audits or evidence—requires a separate written commercial license. Contact team@vitron.ai.

The Themis project is open source and is a separate testing and verdict layer: vitron-ai/themis. Themis does not include or open-source the Alethia runtime.

Configuration

These environment variables are optional:

Variable

Default

Purpose

ALETHIA_HEADLESS

unset

Set to 1 to hide the cockpit.

ALETHIA_HIGHLIGHTS

enabled for tell

Set to 0 to disable per-step highlights.

ALETHIA_RUNTIME_VERSION

latest release

Pin the runtime version.

ALETHIA_RUNTIME_DIR

~/.alethia/runtime

Set the runtime install directory.

ALETHIA_TIMEOUT_MS

60000

Set the per-request timeout in milliseconds.

ALETHIA_DEBUG

unset

Set to 1 for bridge diagnostics on stderr.

ALETHIA_SKIP_AUTO_UPDATE

unset

Set to 1 to disable bridge self-updates.

ALETHIA_BRIDGE_VERSION

latest compatible version

Pin the bridge version and skip its registry update check.

ALETHIA_BRIDGE_SRI

unset

Require a matching SHA-512 integrity value for an auto-updated bridge.

ALETHIA_HOST / ALETHIA_PORT

127.0.0.1 / 47432

Configure the local runtime endpoint.

The runtime and bridge version pins are useful for reproducible CI runs. Bridge updates do not automatically cross major-version boundaries.

Troubleshooting

The client does not show Alethia tools. Check the MCP configuration, restart the client, and run alethia-mcp --health-check. Set ALETHIA_DEBUG=1 to print bridge diagnostics to stderr.

The runtime is missing or cannot start. Run alethia-mcp --health-check to check availability. On first use, the runtime must be downloaded from GitHub Releases. Check network access and review any verification or extraction error printed by the bridge.

A multi-step inline run loses later steps on Windows. Use a .alethia file or pipe it to alethia run -. Literal \n separators also work for short inline input.

A page cannot be reached. Allowed destinations are set by the runtime build. A license file does not add origins. Contact Vitron if you need a different deployment scope.

A destructive action is blocked. Review the policy result and test against an application and data you control. Do not try to bypass a safety decision through a different prompt.

A licensed audit feature is unavailable. Audit access requires a valid runtime license. Contact team@vitron.ai for licensing help.

Learn more

The runtime is proprietary software and patent pending. This repository contains the MIT-licensed MCP bridge. The MIT license does not grant a license to the runtime or any patent rights.

Available Tools

15 tools
alethia_activate_kill_switchA
Destructive

Halt all current and queued automation immediately. The per-step VITRON-EA1 policy gate stays armed; subsequent tell() calls will be blocked with reason KILL_SWITCH_ACTIVE until reset. Use this when an agent appears to be acting unsafely, when human review is required, or to enforce a hard boundary at the end of a controlled test run.

Inputs: reason.

alethia_assert_safetyA
Read-only

Navigate to a URL, discover every destructive / write-high action on the page, and verify the VITRON-EA1 policy gate blocks each one. Returns a per-action report with block/allow status. This is the automated policy-verification primitive — proves the safety gate works on a real page without the agent or human having to click each destructive button manually. Use it as a compliance check before releasing an agent-driven workflow against a customer environment.

Inputs: url (required).

alethia_audit_nistA
Read-only

Run a NIST SP 800-53 Rev. 5 web application security controls audit on the current page. Checks 8 controls across 3 families: AC (login lockout, security banners, session timeout), IA (unmasked passwords, weak password constraints, MFA indicators), SI (input validation, error information leakage). Call after navigating with alethia_tell. Returns findings with control IDs and severity levels.

Inputs: no named parameters.

alethia_audit_wcagA
Read-only

Run a WCAG 2.1 AA accessibility audit on the current page, powered by axe-core. Checks alt text, form labels, keyboard access, color contrast, ARIA usage, heading structure, and the rest of the axe-core ruleset — not a fixed checklist. Call after navigating with alethia_tell. Returns findings with rule IDs, impact levels, and issue counts.

Inputs: no named parameters.

alethia_compileA
Read-only

Compile natural-language test instructions to Alethia Action IR text, without executing anything. Returns the compiled IR, per-line confidence scores (0-1), and warnings for any lines the compiler could not parse. Use this to preview what tell() will run, debug coverage gaps, or generate reproducible IR scripts for CI pipelines.

Inputs: instructions (required).

alethia_evalA

Evaluate a JavaScript expression in the page under test and return the result. Runs in the context of the navigated page, not the Alethia host UI. Use this for queries the NLP compiler cannot express — counting elements, reading computed styles, checking localStorage, or any DOM inspection that needs raw JS.

Inputs: expression (required).

alethia_export_sessionA
Read-only

Export the full session recording as a signed evidence pack. Contains every tool call made during this session with timestamps, inputs, outputs, policy decisions, and a SHA-256 integrity hash. Use at the end of an agent loop to produce cryptographic proof of everything the agent did. Designed for compliance review and chain-of-custody.

Inputs: no named parameters.

alethia_hide_cockpitA
Idempotent

Hide the Alethia cockpit window. The runtime keeps running and continues to accept tool calls; only the visible window is dismissed.

Inputs: no named parameters.

alethia_propose_testsA
Read-only

Navigate to a URL, scan the page for interactive elements (headings, buttons, forms, links, destructive actions), and generate a candidate NLP test suite ready to pass to alethia_tell. Returns an array of plain-English test blocks, including an auto-generated "EA1 Safety Gate Verification" block that uses "expect block: " for every destructive control on the page. Use this to bootstrap test coverage for a new page or to discover what the safety gate should be watching.

Inputs: url (required).

alethia_screenshotA
Read-only

Capture a PNG screenshot of the current page and return it as a base64-encoded image. Use this to visually verify what the browser is showing after running test steps with alethia_tell.

Inputs: no named parameters.

alethia_serve_demoA
Idempotent

Start a local HTTP server for the built-in Alethia demo pages and return the base URL. Use this to serve demo pages on localhost so they appear in preview panels (Claude Code, VS Code, etc.). The server runs on a random available port on 127.0.0.1. Call this before alethia_tell to get a localhost URL instead of a file:// path. Returns the base URL and a list of available demo pages.

Inputs: no named parameters.

alethia_show_cockpitA
Idempotent

Show the Alethia cockpit window — the oversight surface where the target app is driven and each step is highlighted live (green = pass, blue = type, red = EA1 block). Use this to pop the UI into view during a headless-launched session for demos, review, or partner walkthroughs.

Inputs: no named parameters.

alethia_statusA
Read-onlyIdempotent

Health and identity probe. Returns runtime version, the default VITRON-EA1 policy profile in effect, kill switch state, driver statistics (queued plans, run count, audit count), the current page domain, and runtime capabilities. Use this for liveness checks before sending tell() calls, and to verify the runtime is in a known-good state at the start of an agent loop.

Inputs: no named parameters.

alethia_tellA

Execute natural-language E2E test instructions against the page Alethia is currently driving. Returns per-step results, policy audit records, and a SHA-256 integrity hash. Destructive actions (delete, purchase, transfer, etc.) are blocked unconditionally. Sensitive input (passwords, credit cards, SSN) is blocked unless allowSensitiveInput is true. ~13 ms per step on average.

Inputs: instructions (required), name, allowSensitiveInput.

alethia_tell_parallelA

Run multiple test flows concurrently — each against a different URL. Takes an array of test specs, spawns a browser instance per spec, runs them in parallel, and returns all results together. Use this to verify multiple pages simultaneously.

Inputs: specs (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: executing tests, compiling, monitoring, UI control, safety override, capturing state, JS query, audits, session export, parallel execution, demo server, test proposal, safety assertion, and cockpit control. Even related tools like audit_wcag and audit_nist target different standards.

    Naming Consistency4/5

    All tools share the 'alethia_' prefix and use snake_case, making the pattern highly predictable. However, a few names (status, screenshot, eval) are nouns or abbreviations rather than verbs, which slightly deviates from a strict verb_noun convention.

    Tool Count4/5

    With 15 tools, the server sits at the upper boundary of a well-scoped set. Each tool addresses a distinct need in the automation workflow, though some are auxiliary (e.g., cockpit controls, demo server) and could be trimmed without losing core functionality.

    Completeness5/5

    The tool set provides comprehensive coverage for the stated purpose: compile/preview, execute, observe (screenshot/eval), audit (WCAG/NIST), safety verification, session export, and parallel execution. There are no obvious dead ends or missing critical operations.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that gates agent tool calls by normalizing intent, denying unknown/unattended destructive actions, and requiring HITL prove approval for high-risk operations. It maintains an append-only hash-chained Action Ledger and exposes gate_check and ledger_verify tools without ever executing tools.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables policy-governed MCP interactions with deterministic authorization, tenant isolation, minimized PII exposure, and human approval gates for sensitive mutations, while producing structured audit events.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables transparent MCP proxying with a hash-chained effect ledger, classifying agent actions by reversibility, enforcing approval gates, and dry-run previews of sessions.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Owner-signed authorization before agent actions. Hosted Vizier v0.5.13 MCP: https://vizier.agendamcp.dpdns.org/mcp. ALLOW/BLOCK/REVIEW; anonymous calls never ALLOW. Your integration enforces the decision. SDK v0.5.13: https://www.npmjs.com/package/@agenda-intelligence/vizier-sdk. Grants are signed; legacy receipts are unsigned. Python stdio is a separate catalog.
      3
      MIT