alethia-mcp
OfficialThis server provides an MCP interface for agent-driven browser E2E testing with a verifiable safety gate, plus audits, evidence export, and parallel multi-page runs — all local-first.
Run natural-language E2E tests (
alethia_tell): execute plain-English test steps while destructive actions are blocked and sensitive inputs require explicit opt-in.Compile test instructions (
alethia_compile): preview the Action IR and confidence scores without executing anything.Check runtime status (
alethia_status): health probe, policy profile, kill-switch state, and current page domain.Halt automation (
alethia_activate_kill_switch): immediately stop queued/running tests; only resettable from the cockpit.Take screenshots (
alethia_screenshot): capture the current page as a base64 PNG.Evaluate JavaScript (
alethia_eval): query the page DOM, computed styles, localStorage, or run any JS expression.Run accessibility audit (
alethia_audit_wcag): WCAG 2.1 AA check via axe-core.Run security/compliance audit (
alethia_audit_nist): NIST SP 800-53 Rev. 5 web controls across AC/IA/SI families.Export signed evidence pack (
alethia_export_session): tamper-evident session recording with SHA-256 hash for compliance/chain-of-custody.Run parallel tests (
alethia_tell_parallel): execute multiple test flows concurrently against different URLs.Serve demo pages (
alethia_serve_demo): start a localhost server for built-in demo pages.Propose test suite (
alethia_propose_tests): scan a URL and auto-generate candidate NLP test blocks, including safety-gate verification.Verify safety gate (
alethia_assert_safety): automatically confirm every destructive action on a page is blocked by the VITRON-EA1 gate.Show/hide cockpit (
alethia_show_cockpit,alethia_hide_cockpit): control the visible oversight window during sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@alethia-mcp test the login flow on localhost:3000"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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@vitronaiRestart 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/alethiaAdd 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 Desktop (macOS) |
|
Claude Desktop (Windows) |
|
Claude Desktop (Linux) |
|
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 |
| Run newline-separated, plain-English instructions and return per-step results. |
| Preview how instructions compile without executing them. |
| Inspect a page and suggest candidate test flows. |
| Check how the runtime's safety policy handles destructive actions on a page. |
| Run an axe-core accessibility audit against WCAG 2.1 AA rules. |
| Check a page against selected NIST SP 800-53 Rev. 5 controls. |
| Export session records with SHA-256 integrity data. |
| Run flows concurrently against multiple URLs. |
| Capture the current page or evaluate a JavaScript expression in that page. |
| Check runtime status or halt automation. |
| Serve a built-in demo page on localhost. |
| 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 visibleTo run the file directly from a shell or CI job:
alethia run tests/e2e/login.alethiaThe 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:alethiaThis 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 |
| unset | Set to |
| enabled for | Set to |
| latest release | Pin the runtime version. |
|
| Set the runtime install directory. |
|
| Set the per-request timeout in milliseconds. |
| unset | Set to |
| unset | Set to |
| latest compatible version | Pin the bridge version and skip its registry update check. |
| unset | Require a matching SHA-512 integrity value for an auto-updated bridge. |
|
| 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 toolsalethia_activate_kill_switchADestructive
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_safetyARead-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_nistARead-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_wcagARead-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_compileARead-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_sessionARead-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_cockpitAIdempotent
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_testsARead-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_screenshotARead-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_demoAIdempotent
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_cockpitAIdempotent
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_statusARead-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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Governed MCP: agent audit, provenance, deterministic checks, and receipt-backed FragGate execution.
Remote MCP for A2A failure replay MCP, structured receipts, audit logs, and reviewer-ready evidence.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP 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
- AlicenseAqualityCmaintenanceEnables policy-governed MCP interactions with deterministic authorization, tenant isolation, minimized PII exposure, and human approval gates for sensitive mutations, while producing structured audit events.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables transparent MCP proxying with a hash-chained effect ledger, classifying agent actions by reversibility, enforcing approval gates, and dry-run previews of sessions.MIT
- AlicenseAqualityBmaintenanceOwner-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.3MIT