Aletheia MCP is a safety filter server that intercepts and blocks dangerous AI-agent tool calls before they execute.
Set or tighten operational mandates with aletheia_set_mandate (write/network/destructive permissions, allowed paths/tools, risk tolerance; loosening requires operator secret).
Inspect the current safety mandate with aletheia_get_mandate.
Pre-flight any tool call through aletheia_intercept to get an ALLOW/BLOCK verdict against scope-creep (S3) and prompt-injection (S2b) signatures.
Safely execute shell commands with aletheia_safe_bash, blocking destructive deletes, fork bombs, credential harvesting, privilege escalation, and unauthorized network egress.
Validate or run SQL with aletheia_safe_sql, blocking destructive DDL, unbounded DML, and privilege tampering.
Monitor safety telemetry with aletheia_get_telemetry, including block rates, latency percentiles, and violation summaries.
Act as a transparent MCP proxy to wrap other servers with fail-closed filtering.
Read live resources like telemetry summaries, audit logs, and mandate details, and use the mandate-enforcer prompt to keep agents within bounds.
Provides safety filtering for MySQL query tool calls, blocking unsafe operations such as LOAD DATA INFILE, INTO OUTFILE, and other destructive or unbounded mutation patterns.
Provides safety filtering for PostgreSQL query tool calls, blocking dangerous operations such as COPY PROGRAM, pg_read_file, and lo_import, as well as unbounded mutations and other destructive SQL patterns.
Provides safety filtering for SQLite query tool calls, blocking unsafe operations such as ATTACH DATABASE and other destructive or unbounded mutation patterns.
Click on "Install 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., "@aletheia-mcp wrap my MCP server with pre-execution safety filtering"
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.
Sub-millisecond runtime filter that blocks scope-creep and prompt-injection tool calls before an AI agent can run them.
Aletheia MCP intercepts tool calls from Claude Code, Claude Desktop, and any other MCP-compatible agent before they execute and blocks the destructive ones, with sub-millisecond (~25 µs) overhead and no LLM in the hot path.
It scores each call against the Aletheia research paper's taxonomy of nine behavioral signatures: recurring LLM failure patterns, each with an ID, derived from the interfaces through which a model touches its environment (output/reality, input/trust, task/scope, and so on). This server enforces two of them:
S3 (Scope Creep Beyond Mandate): the agent acts outside the task it was actually given, writing files outside its workspace, reaching into unrelated systems, quietly widening what it was asked to do.
S2b (Adversarial Prompt Injection): instructions smuggled in through tool results, file contents, or fetched data that try to hijack what the agent does next.
The paper validates those nine signatures against 2,571 entries across three independent corpora: the AI Incident Database (AIID + hand-curated supplement, n=1,134), the AVID AI Vulnerability Database (n=767), and the MIT AI Risk Repository (n=670). The per-model detection-rate figures from that research are reported in the paper with their methodology; treat them as directional context for why these signatures matter, not as an independently-audited benchmark of this codebase.
Aletheia MCP is a deterministic, pattern-based lexical and structural filter, iteratively hardened through many rounds of adversarial red-teaming against the shell, SQL, filesystem, and network surfaces it inspects. Each round of testing has turned up real gaps, and each has been fixed and re-verified. That process is ongoing, not finished, and it never fully finishes: this is honest heuristic pattern-matching over Bash and SQL, not a formal parser or a proof of completeness.
What this is, and isn't:
Aletheia is a fast, first-line pre-execution filter: single-digit-to-low-tens-of-microseconds overhead, deterministic, no LLM in the hot path. It catches a wide and continually growing set of known destructive, exfiltration, SSRF, and privilege-escalation patterns before they execute.
Aletheia is not a sandbox, not a formal guarantee, and not a substitute for least-privilege credentials, non-root system users, scoped database grants, or containerized/VM-level isolation (Docker, gVisor, Firecracker). Because it works by recognizing known-dangerous patterns in shell and SQL text rather than by parsing and fully understanding either language, a sufficiently novel or obfuscated construct can, in principle, always be found that the current pattern set doesn't yet cover. This is an inherent property of pattern-based filtering against a Turing-complete shell, not a bug that a future patch will finally close for good.
Aletheia does not perform DNS resolution, so a domain name an attacker controls and points at a private IP or cloud metadata endpoint is outside what a string-based filter can ever detect at this layer; that requires DNS-aware egress control (see SECURITY.md).
The right way to run this: treat Aletheia as one layer that removes the easy, common failure modes cheaply, combined with OS/network-level sandboxing as the actual security boundary, not instead of it.
Detection is enumerated over known dangerous functions, flags, and syntax shapes (e.g., specific SQL functions, specific shell obfuscation idioms). Sibling or novel variants not yet added to the pattern set will not be caught until they are found and added.
No DNS resolution: SSRF protection is limited to literal IPs/hostnames in the request text, not what a domain name actually resolves to.
S2b (prompt-injection) detection is keyword- and pattern-based; it is not a semantic classifier and can be evaded by sufficiently novel phrasing.
This is a single, actively-iterated implementation; it has not yet had independent, adversarial third-party review beyond the iterative self-testing documented in this repository's commit history.
Related MCP server: SentinelGate
When autonomous agents are granted tool execution access (Bash, SQL, filesystem mutation, API calls), the primary failure mode is Scope Creep Beyond Mandate:
Destructive Shell Mutation: An agent asked to "inspect git diff" runs git reset --hard or rm -rf * to resolve a conflict.
Credential Harvesting: An agent reading code probes ~/.ssh/id_rsa, .env, or AWS credentials to resolve connection errors.
Unbounded Database Writes: An agent executes DELETE FROM accounts; or UPDATE users SET role='admin'; without WHERE predicates (or with tautological WHERE 1=1).
Interpreter Escape Hatches: An agent runs shell commands wrapped inside python3 -c "os.system('...')" or node -e "fs.rmSync('/')".
SSRF & Cloud Metadata Leaks: An agent probing network endpoints makes calls to 169.254.169.254 (AWS metadata) or internal RFC1918 subnets.
Self-Mandate Escalation: A prompt-injected or drifting agent attempting to rewrite its own safety policy.
Existing defenses rely on LLM-as-a-judge evaluators that add 1,500–3,000 ms to every tool call. Aletheia MCP provides deterministic, multi-stage lexical and structural filtering in single-digit microseconds.
The list below reflects what the pattern set currently catches, built up through iterative adversarial testing rather than designed upfront as a complete taxonomy. See Known Limitations above for what it does not (yet, or ever, in the DNS case) cover.
⚡ Sub-Millisecond (~25 µs p99) Overhead: 100,000+ evaluations per second. Zero perceived latency in agent loops.
🛡️ Monotonic Mandate Escalation Guard: Prevents autonomous agents from self-granting write, destructive, or network permissions. Mandates can be tightened voluntarily, but loosening requires an operatorSecret.
🎯 Evasion-Hardened Engine:
Database OS & Filesystem Primitives: Blocks PostgreSQL COPY ... PROGRAM, pg_read_file(), lo_import(); MySQL LOAD DATA INFILE, INTO OUTFILE; SQLite ATTACH DATABASE; and SQL Server xp_cmdshell.
Scheme-less & Malformed URL SSRF Defense: Normalizes protocol-relative and scheme-less endpoints (169.254.169.254/latest), enforcing strict fail-closed rejection on invalid URLs and direct cloud metadata access under offline mandates.
Direct Shell Metadata & Network Tool Neutralization: Scans direct IP references in curl / wget without URL schemes, and blocks socat raw socket exfiltration channels.
Wildcard Credential & Sensitive Directory Boundaries: Enforces wildcard protection across all .env.* variants (.env.secrets, .env.staging, .env.test) and sensitive config roots (~/.kube/, ~/.docker/, ~/.gnupg/, .git-credentials).
Linear O(N) Normalization: Token-based non-backtracking brace expansion and bounded parameter resolution ensures sub-millisecond execution on 100KB+ payloads.
Bash Socket Pseudo-Device Interception: Inspects /dev/tcp/HOST/PORT and /dev/udp/HOST/PORT redirections, halting cloud metadata SSRF and covert exfiltration channels directly on shell inputs.
SQL CTE & Procedural Block Interception: Enforces unbounded mutation guards across Common Table Expressions (WITH ... DELETE) and PL/pgSQL anonymous blocks (DO $$ ... $$).
Dynamic Linker Hijacking Defense: Neutralizes LD_PRELOAD, DYLD_INSERT_LIBRARIES, and runtime environment variable hijacking.
Quote & Backslash Stripping: Defeats split-token evasion (r'm' -rf /, r\m -rf /).
Variable Indirection & Default Fallbacks: Resolves shell variable substitutions (X=rm; $X -rf /) and default parameter expansions (${X:-rm} -rf /).
Positional Parameter & IFS Normalization: Neutralizes $IFS$9 word-splitting.
Dual-Representation SQL Analysis: Defeats inline comment evasion (DROP/**/TABLE, DR/**/OP, and # MySQL comment).
Interpreter Escape Interception: Recursively normalizes string concatenations ('r'+'m'), inspects dynamic imports (import("node:fs")), and parses code passed via -c/-e/-r flags across python, node, ruby, perl, php, and sh.
Automated Hex & Base64 Decoding: Automatically extracts, decodes, and recursively evaluates hex (bytes.fromhex(...)) and base64-encoded command payloads.
Unicode NFKC & Zero-Width Sanitization: Neutralizes invisible characters (\u200B, \u200C, \uFEFF) and confusable fullwidth/math-bold jailbreaks in prompt injections (S2b).
IPv4-Mapped IPv6 SSRF Translation: Converts compressed hex IPv6 notations ([::ffff:a9fe:a9fe]) to canonical dotted-decimal bytes (169.254.169.254).
Percent-Encoded Path Traversal: Multi-pass URL decoding catches %2e%2e%2f.env and ..%2f.ssh%2fid_rsa.
Generalized Fork Bombs: Detects recursive piped background processes across arbitrary function identifiers.
SetUID Privilege Elevation: Halts chmod u+s, chmod 4755, and privilege tampering.
Tautological SQL Predicates: Flags WHERE 1=1, WHERE true, and tautologies as unbounded mutations.
Polymorphic Argument Inspection: Safely inspects strings, arrays, and objects fail-closed across both native and unrecognized third-party tools.
🛡️ Two Operating Modes:
Direct Guard Tools: Standalone tools (aletheia_set_mandate, aletheia_intercept, aletheia_safe_bash, aletheia_safe_sql).
Fail-Closed Transparent Proxy: Middleware that wraps ANY downstream MCP server (Postgres, Filesystem, Bash), intercepting both single tools/call and JSON-RPC 2.0 batch arrays with strict fail-closed boundaries.
📊 Real-Time Observability Resources: Exposes live audit logs, block rates, and latency distributions via aletheia://telemetry/summary.
🔒 Zero External API Calls: Zero LLM-as-a-judge latency on the hot execution path.
Measured on 10,000 consecutive multi-domain evaluations (Bash de-obfuscation, SQL pattern validation, path verification, SSRF check, prompt injection). Numbers below are from a representative local run; p50 is stable across runs, p99 varies with system load (observed range ~24–70 µs) since it's sensitive to GC pauses at microsecond scale; both are still comfortably within the sub-millisecond target:
Metric | Measured Value | Target |
p50 (Median) | ~0.0085 ms (8.5 µs) | < 0.500 ms |
p95 Latency | ~0.0180 ms (18 µs) | < 0.800 ms |
p99 Latency | ~0.024–0.070 ms (24–70 µs) | < 1.000 ms |
Throughput | 100,000+ evals / second | > 10,000 / s |
Hot-Path External APIs | 0 (Deterministic local engine) | 0 |
Run locally via npm run benchmark. Results will vary by machine; treat the specific microsecond figures as illustrative of "comfortably sub-millisecond," not as a precise SLA.
By default, Aletheia starts fully locked down (read-only, no network, no loopback) and stays that way, on purpose. If your agent needs to write files or make network calls, grant that up front with --allow-write / --allow-network / --allow-loopback (and scope writes to a directory with --allowed-paths), as shown below. These flags set the initial mandate at server startup and are not gated by operatorSecret; that gate only applies to changing an already-running session's mandate mid-flight (e.g. an agent calling aletheia_set_mandate to loosen its own permissions, which is deliberately blocked). Most users want the startup flags below, not operatorSecret.
# Read-only (safe default; can inspect but not modify anything):
claude mcp add aletheia -- npx -y aletheia-mcp
# Practical default for a coding agent that needs to edit files in your project:
claude mcp add aletheia -- npx -y aletheia-mcp --allow-write --allowed-paths /path/to/your/projectAdd to your claude_desktop_config.json:
{
"mcpServers": {
"aletheia": {
"command": "npx",
"args": ["-y", "aletheia-mcp", "--allow-write", "--allowed-paths", "/path/to/your/project"]
}
}
}Wrap existing downstream MCP servers with Aletheia safety filtering:
{
"mcpServers": {
"secure-filesystem": {
"command": "npx",
"args": [
"-y",
"aletheia-mcp",
"--allow-write",
"--proxy",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/dir"
]
}
}
}Tool | Mode | Annotation | Description |
| State |
| Establish or tighten operational safety envelope. Loosening requires |
| Observability |
| Retrieve active mandate, allowed paths, and risk tolerance. |
| Gatekeeper |
| Pre-flight check for candidate tool calls. Returns |
| Execution |
| Verified shell executor. Blocks |
| Audit |
| Validates SQL against |
| Observability |
| Emits evaluation counts, block rate %, and microsecond latency percentiles. |
resources/read)Clients can inspect server state on-demand via standard MCP resources/read:
aletheia://telemetry/summary: Real-time evaluation counters, block rate %, and microsecond latency distribution.
aletheia://telemetry/audit-log: Rolling log of the last 50 tool clearance requests with inputs, verdicts, violation signatures, and timestamps.
aletheia://mandate/current: Active session mandate parameters, allowed tool lists, path boundaries, and permission toggles.
aletheia://signatures/s3: Specification, risk taxonomy, and benchmark failure rate data for Signature S3 (Scope Creep).
prompts/get)aletheia_mandate_enforcer: System prompt directive that establishes operational safety boundaries and instructs the agent to route risky actions through Aletheia before execution. Accepts task_description (required), workspace_root (optional), and allow_write (optional).
┌───────────────────────────────────────────────┐
│ Claude / Agent Host Runtime │
└───────┬───────────────────────────────┬───────┘
│ │
Mode 1: Guard Tools Mode 2: Transparent Proxy
(aletheia_intercept, (Intercepts tools/call
aletheia_safe_bash) to downstream MCPs)
│ │
▼ ▼
┌───────────────────────────────────────────────────────────────┐
│ Aletheia MCP Server │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ S3 Scope Creep Engine (<10µs) │ │
│ │ ├─ Multi-stage Token Unquoting & De-obfuscation │ │
│ │ ├─ Variable Indirection Resolver │ │
│ │ ├─ Positional IFS & Brace Expansion Normalizer │ │
│ │ ├─ Dual-Representation SQL Comment Analyzer │ │
│ │ ├─ Interpreter Escape Filter (python -c, node -e) │ │
│ │ ├─ Destructive Filter (rm -rf, fork bombs, find -del) │ │
│ │ ├─ SetUID / Privilege Escalation Guard │ │
│ │ ├─ Credential & Sensitive File Access Guard │ │
│ │ ├─ SSRF & Cloud Metadata Validator │ │
│ │ ├─ SQL DDL & Tautological Predicate Guard (WHERE 1=1) │ │
│ │ ├─ Monotonic Mandate Escalation Guard (operatorSecret) │ │
│ │ └─ S2b Adversarial Prompt Injection Filter │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Telemetry & Audit Stream (aletheia://telemetry/summary) │ │
│ └─────────────────────────────────────────────────────────┘ │
└───────────────────────────────┬───────────────────────────────┘
│
[ALLOW] │ [BLOCK]
┌───────────────────────┴───────────────────────┐
▼ ▼
Execute Tool Safely Emit Structured Policy Breach
(Explains boundary violation)Aletheia MCP is developed by Vikas Shivpuriya as part of the broader Aletheia AI Safety Research Core. The underlying behavioral failure signatures are motivated by incidents cataloged in the AI Incident Database (AIID), the AVID AI Vulnerability Database, and the MIT AI Risk Repository. The per-model detection rates referenced for frontier systems (Claude Sonnet 4.6, GPT-4o, Gemini 2.5 Flash) come from that paper's evaluation harness; treat them as directional context for why Signature S3 matters rather than as a verifiable benchmark of this codebase.
What is independently verifiable in this repository: the test suite (npm test), the latency benchmark (npm run benchmark), and the commit history documenting each round of adversarial testing and the fixes it produced.
Research Paper & Taxonomy: github.com/vikasny30/aletheia-paper
License: Apache 2.0
Retrieve the current operational safety mandate, permissions, and active boundary constraints.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. The verb 'Retrieve' implies a read-only, non-destructive operation, and the description names the returned content areas (mandate, permissions, boundary constraints). However, it does not disclose possible error conditions, whether a mandate must already exist, or any return format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It states the action and the resource immediately, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description is nearly complete: it says what is retrieved and implies the result categories. It lacks minor context such as whether the mandate is always available and how the result relates to set_mandate, but these are not needed to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so parameter documentation is not a concern. The description adds meaning by clarifying what the empty invocation returns, which is exactly what an agent needs for a no-argument retrieval tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and identifies a clear resource: the current operational safety mandate, permissions, and active boundary constraints. It is readily distinguishable from sibling tools like aletheia_set_mandate and aletheia_get_telemetry, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention that aletheia_set_mandate should be used for modifying the mandate, nor does it clarify whether this is a prerequisite or companion call to other safety tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve runtime safety telemetry: total tool calls evaluated, block rate %, latency percentiles (p50, p95, p99 < 1ms), and violation counts broken down by signature.
| Name | Required | Description | Default |
|---|---|---|---|
| auditLogLimit | No | Number of recent audit records to include (default: 20). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of explaining behavior. It does disclose the main response contents and 'Retrieve' implies a read-only operation, but it does not explicitly state whether there are side effects, auth requirements, rate limits, or how failures surface. The mention of latency percentiles under 1ms is also slightly ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one front-loaded sentence that uses a colon-delimited list to pack in the exact payload of metrics. There is no filler, and the structure makes the return contents easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the headline telemetry metrics well but omits any mention of audit records, even though the auditLogLimit parameter indicates the response includes recent audit records. Since there is no output schema, the description should have explained this component to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single optional parameter auditLogLimit is already fully documented in the schema with its default value and purpose. The description adds nothing about this parameter, but it does not need to; a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object ('Retrieve runtime safety telemetry') and then enumerates the exact metrics returned, so there is no ambiguity about what the tool does. Its focus on telemetry also clearly separates it from sibling tools like aletheia_get_mandate or aletheia_intercept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'runtime safety telemetry' implies a monitoring/observability use case, and the sibling names make alternatives visible, but the description never explicitly states when to choose this tool over aletheia_get_mandate or aletheia_intercept, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Universal sub-millisecond safety gatekeeper. Evaluates any proposed tool invocation against Signature S3 (Scope Creep) and S2b (Prompt Injection) to block destructive, out-of-boundary, or compromised actions before execution.
| Name | Required | Description | Default |
|---|---|---|---|
| tool_args | Yes | The argument dictionary intended for the tool call. | |
| tool_name | Yes | The name of the tool intended to be called (e.g. 'bash', 'execute_sql', 'write_file'). | |
| mandate_override | No | Optional one-off overrides to apply to the evaluation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It says the tool evaluates and blocks, but does not state what the tool returns when a call is allowed or blocked, whether interception has side effects, how mandate overrides affect behavior, or what failure modes exist. The mention of 'block destructive, out-of-boundary, or compromised actions' is helpful but too abstract for an agent to predict the actual result of calling this tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the tool's role efficiently. It wastes little space, though phrases like 'sub-millisecond' and the signature identifiers are somewhat ornamental rather than essential. Overall, it is concise without being vague.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations and no output schema, so the description is the sole source of behavioral and return-value context. It does not describe what the tool returns, how a blocked invocation is represented, when an override is permitted, or how this relates to the sibling mandate tools. For a safety-critical interception tool with nested parameters, this is a significant completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented by the schema. The description adds only general context that tool_name and tool_args represent a proposed invocation; it does not enrich the meaning of mandate_override or provide any additional format, constraints, or usage details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a gatekeeper that evaluates proposed tool invocations and blocks unsafe actions before execution. It states the verb ('evaluates'/'block'), the resource ('any proposed tool invocation'), and the 'universal' scope, which distinguishes it from sibling tools like aletheia_safe_bash and aletheia_safe_sql. The internal signature labels 'Signature S3' and 'S2b' add jargon, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Evaluates any proposed tool invocation ... before execution' clearly signals when the tool should be used: as a pre-execution safety check for any tool call. The 'universal' qualifier implies no exclusions. However, it does not explicitly contrast itself with sibling tools or describe when to bypass interception, so alternatives are not directly addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a shell/bash command with inline sub-millisecond Signature S3 scope creep protection. Blocks destructive deletes (rm -rf), disk formatting, fork bombs, credential harvesting, privilege escalation, and unauthorized network egress.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for execution. Defaults to current directory. | |
| command | Yes | The shell command line to evaluate and safely execute. | |
| timeoutMs | No | Maximum execution time in milliseconds (default: 15000). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must explain behavior, and it does: it lists several categories of commands that will be blocked (rm -rf, formatting, fork bombs, credential harvesting, privilege escalation, unauthorized network egress). It could add what happens when a command is blocked or what the shell/environment looks like, but the core safety behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the identifying verb and resource. The phrase 'inline sub-millisecond Signature S3 scope creep protection' is somewhat jargon-heavy, but the rest of the sentence is dense and useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter executor, the schema plus the safety block list cover most invocation needs. However, there is no output schema and no description of return/error behavior when a command is blocked, which is a meaningful gap for a shell-execution tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents command, cwd, and timeoutMs clearly. The description adds no parameter-level detail beyond restating that commands are safely evaluated, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ('Execute a shell/bash command') and goes on to list the protected operations, so an agent immediately knows what the tool does. The 'bash' focus differentiates it from clearly distinct siblings such as aletheia_safe_sql.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the tool's intended use obvious: run shell/bash commands under a safety wrapper. It does not explicitly name alternatives or state when not to use it, but the bash-versus-SQL distinction among siblings plus the explicit safety scope gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit or execute a database query with Signature S3 safety filters. Detects destructive DDL (DROP, TRUNCATE), unbounded DML (DELETE/UPDATE without WHERE), and privilege tampering.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The SQL statement to evaluate. | |
| database_type | No | Database dialect ('postgres', 'mysql', 'sqlite', 'snowflake'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose that the tool can audit or execute and detects specific unsafe SQL patterns, which is useful, but it does not say what happens when an unsafe query is detected (block, warn, audit report), whether execution can mutate data, or what the response looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the core purpose and then specific safety detections. Every sentence adds information, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the parameter schema is fully described, there is no output schema and the description does not clarify the ambiguity between 'audit' and 'execute' modes, the default behavior, or the result format. Since this tool can have side effects (executing a query), an agent lacks enough context to know exactly what will happen when it invokes it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'query' and 'database_type' documented. The description adds no additional meaning beyond restating that this is a database query, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb phrase ('Audit or execute a database query') and resource type (SQL), then names the concrete safety checks it performs (destructive DDL, unbounded DML, privilege tampering). This clearly distinguishes it from sibling aletheia tools that target mandates, bash, telemetry, and interception.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for safely auditing or executing SQL queries but does not explicitly state when to prefer this tool over an alternative or mention any exclusion criteria. An agent can infer the domain from the name and context, but there is no comparative timing or selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Establish or update the active operational safety mandate for this agent session. Declares permissible boundaries, allowed tools, filesystem directories, write permissions, and risk tolerance. Loosening restrictions requires operatorSecret.
| Name | Required | Description | Default |
|---|---|---|---|
| allowWrite | No | Authorize filesystem modifications or database write operations (default: false). | |
| allowNetwork | No | Authorize outbound network connectivity and external API calls (default: false). | |
| allowedPaths | No | Permitted filesystem root directories. Operations outside these paths will be flagged. | |
| allowedTools | No | Whitelisted tool names. Use ['*'] to allow all non-disallowed tools. | |
| riskTolerance | No | Threshold policy: 'low' blocks any potential drift; 'high' permits warnings for non-critical risks. | |
| allowSubshells | No | Authorize nested subshell execution ($() or backticks) (default: false). | |
| operatorSecret | No | Operator authentication token required to loosen permissions on a locked mandate. | |
| disallowedTools | No | Explicitly prohibited tool names. | |
| taskDescription | Yes | Concise summary of the current user-authorized task/objective. | |
| allowDestructive | No | Authorize destructive commands like file deletions or schema changes (default: false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full disclosure burden. It transparently reveals that loosening restrictions requires operatorSecret and that the tool declares scope boundaries. It does not, however, disclose side effects such as overwriting an existing mandate, session persistence, or what happens if an even stricter mandate is already in effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three purposeful sentences with zero filler. The main action is front-loaded, the second sentence summarizes the parameter landscape, and the third captures a critical authorization constraint. It is efficient and well-ordered for an agent scanning multiple tool definitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with ten parameters, no annotations, and no output schema, the description provides a solid high-level purpose and the key auth constraint. However, it is silent on what the tool returns (confirmation vs. full mandate object), whether the mandate persists for the whole session, and how conflicts like allowedTools overlapping disallowedTools are resolved. These gaps matter for a tool that fundamentally governs agent behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds modest value by grouping parameters into conceptual categories (boundaries, allowed tools, directories, write permissions, risk tolerance) and by linking operatorSecret to the loosening case, but it does not deepen the semantics of any individual parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('Establish or update the active operational safety mandate') and immediately enumerates what the mandate declares: permissible boundaries, allowed tools, filesystem directories, write permissions, and risk tolerance. This clearly distinguishes it from sibling tools like aletheia_get_mandate (retrieval) and aletheia_safe_bash/aletheia_safe_sql (execution).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this tool is for establishing or updating the session mandate and notes the operatorSecret requirement for loosening restrictions. However, it does not explicitly mention when not to use it or point to aletheia_get_mandate as the alternative for reading the current mandate, leaving usage routing implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0aletheia_get_mandatealetheia_get_telemetryaletheia_interceptaletheia_safe_bashaletheia_safe_sqlaletheia_set_mandateEach tool has a clearly distinct role: mandate retrieval/update, telemetry, safe shell execution, safe SQL execution, and universal interception. Even though safe_bash and safe_sql both enforce safety, their execution targets are explicit and non-overlapping; intercept is described as evaluation-only, so an agent can tell them apart.
All tools share the aletheia_ prefix and snake_case, but the pattern is not uniform: get/set tools use verb_object, safe_bash/safe_sql use a modifier prefix, and intercept is a bare verb. This is readable and mostly predictable, with only minor deviations.
Six tools is well-scoped for a focused safety/governance MCP. Each tool addresses a distinct concern: mandate configuration, safe execution in two runtimes, telemetry, and universal interception, with no redundant extras.
The surface covers the core lifecycle: mandate get/set, safe execution, telemetry, and a universal gatekeeper. Minor gaps exist such as no dedicated safe file or HTTP action, but bash and SQL coverage plus intercept likely covers most operational needs.
Security firewall for AI agents — scans MCP calls for injection, secrets, and risks.
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
The WAF for agents. Pattern-based + heuristic firewall scans prompts, RAG documents, tool argume...
AgentGuard — 20-tool AI safety MCP: policy preflight, risk scoring, audit logging, rate limits.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/vikasny30/aletheia-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
