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., "@Enzo Decompose the question: is our authentication flow secure?"
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.
Enzo is not another autonomous-agent framework. The LLM keeps responsibility for reasoning, strategy, and deciding what to investigate. Enzo makes each next question precise enough to test.
The name is inspired by the Japanese Zen ensō (円相), the hand-drawn circle. Enzo uses that image as a reasoning metaphor: begin with the large circle of a problem, then reduce it into smaller circles until each contains exactly one independently falsifiable claim.
large question → smaller question → atomic claim → evidence → semantic resultMost reasoning systems are comfortable producing an answer. Enzo is designed to apply pressure before that answer exists:
Common failure | Enzo's response |
One question hides several claims | Decompose it into independently testable atoms |
Missing information becomes vague confidence | Return |
Semantic judgment overrides a test | Deterministic evidence remains authoritative |
Conclusions lose their history | Preserve evidence, provenance, revisions, and dependencies |
A tool quietly sends context outside the process | Require consent for every external Jev observation |
Related MCP server: deep-research
flowchart LR
A[Large question] --> B{One falsifiable claim?}
B -- No --> C[Independent child claims]
C --> B
B -- Yes --> D[Collect typed evidence]
D --> E{Deterministic evidence resolves it?}
E -- Yes --> G[Constrained result]
E -- No --> F[Jev semantic sensor]
F --> G
G --> H[LLM chooses what to ask next]The responsibilities stay deliberately separate:
Component | Responsibility |
LLM | Intelligence, strategy, interpretation, and choosing the next question |
Enzo | Atomicity, evidence contracts, state transitions, and decomposition pressure |
Jev | Typed semantic sensing against supplied context and evidence |
Deterministic tools | Tests, schemas, AST inspection, type checking, and runtime measurements |
Requirements: Python 3.11+ and uv.
git clone https://github.com/mahawi1992/enzo-mcp.git
cd enzo-mcp
uv sync --group dev
uv run enzo-mcpJev is optional for deterministic workflows. To enable it, create a local .env
file containing:
TYPESAFE_API_KEY=your-keyThe file is ignored by Git. Every external observation still requires
allow_external_jev=true; configuring a key alone never authorizes a send.
Add this to ~/.codex/config.toml, replacing the path with your checkout:
[mcp_servers.enzo]
command = "uv"
args = ["run", "--env-file", ".env", "enzo-mcp"]
cwd = "/absolute/path/to/enzo-mcp"Restart Codex. Enzo will expose exactly three tools.
Tool | Purpose |
| Admit one atomic claim, safely decompose it, or request refinement |
| Evaluate typed evidence and optionally invoke Jev with explicit consent |
| Return canonical investigation history, derived status, and the current frontier |
Atomicity has three outcomes:
ATOMIC — one operationalized predicate can be evaluated independently.
DECOMPOSE — multiple safe, explicit child claims can vary independently.
NEEDS_REFINEMENT — the claim appears composite or vague, but a mechanical split
could change its meaning.
Observation has four honest outcomes:
VERIFIED
CONTRADICTED
UNKNOWN
INSUFFICIENT_EVIDENCE
UNKNOWN is a useful result: it tells the LLM what must be learned next.
Ask Enzo to atomize a compound security question:
{
"request": {
"root_goal": "Determine whether the production session cookie is hardened",
"question": "Does the cookie set Secure and HttpOnly?",
"subject": "the production session cookie",
"predicate": "sets Secure=true; sets HttpOnly=true",
"scope": "production session configuration",
"expected_value": true,
"evidence_requirements": [
{
"description": "Inspect the production cookie configuration",
"accepted_kinds": ["SCHEMA_VALIDATION"],
"deterministic_required": true
}
],
"verification_method": "SCHEMA_VALIDATION"
}
}Enzo returns DECOMPOSE and creates two independently falsifiable children:
Does the production session cookie set Secure=true?
Does the production session cookie set HttpOnly=true?Each child can now receive its own evidence, result, provenance, and parent impact.
PydanticJevSensor uses Pydantic AI's TypeSafe provider and maps Enzo's answer
contracts to Jev primitives:
Enzo answer type | Jev primitive |
|
|
|
|
|
|
Jev's native probability or confidence is preserved in sensor evidence. Enzo does not manufacture an aggregate confidence score. A deterministic instrument is used first whenever it can resolve the atom more reliably.
For an explicitly authorized observation, Jev receives a structured claim object
containing the question, subject, predicate, scope, operator, expected answer,
answer contract, operational definition, verification method, and evidence
requirements. This keeps Jev's semantic judgment grounded in the same atomic
contract that Enzo validated instead of asking it to infer the claim from a short
question alone.
Prior sensor output is never sent back into a later Jev request, preventing semantic feedback loops. Exact observation retries are idempotent, while dependency changes correctly invalidate replayed results.
One atom tests exactly one independently falsifiable semantic claim.
Atomicity is semantic, not a measure of sentence length.
Deterministic evidence outranks semantic judgment.
Assumptions remain visibly distinct from facts.
Parent conclusions are derived from their dependency graph.
Contradictions remain explicit.
Unknowns expose gaps instead of becoming invented certainty.
The MCP surface stays small enough to understand.
uv sync --group dev
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
uv buildThe current suite contains 55 tests covering contracts, atomicity, dependency derivation, revision history, consent, Jev answer validation, replay safety, and the stdio MCP surface.
Semantic observations are local-only by default. Setting
allow_external_jev=true authorizes that single request to send its supplied
claim contract, context, and non-sensor evidence to TypeSafe/Jev. Redact
credentials, personal data, and unrelated sensitive information from all three
before enabling an external observation.
Enzo is a focused v0.1 implementation. Its three-tool surface is intentional; the contracts may evolve as real investigations expose better invariants.
Focused issues and pull requests are welcome. If the idea of turning large circles into testable small ones is useful to you, consider starring the repository.
MIT © 2026 Martin Harold Williams
Validate one proposed claim and admit, decompose, or request refinement.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
| Name | Required | Description |
|---|---|---|
| atom | Yes | |
| reasons | Yes | |
| children | No | |
| decision | Yes | |
| investigation_id | Yes | |
| next_atom_needed | Yes | |
| validation_basis | No | |
| refinement_questions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral burden. It names the three possible actions but does not explain what 'admit', 'decompose', or 'request refinement' do in practice, whether the tool mutates state, or what prerequisites apply. This is insufficient for a validation/decomposition decision 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 sentence that front-loads the verb and immediately names the three possible decisions. It contains no filler or redundant restating of the tool name.
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?
Despite an output schema being present, the tool has a highly complex input schema with nested types and enums, no annotations, and a one-line description. Critical context is missing: what constitutes a valid proposed claim, what triggers each outcome, how it relates to the sibling tools, and what state changes occur. The description is not self-sufficient for safe invocation.
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 0%, with one complex 'request' parameter buried in a large $defs structure. The description adds only the generic phrase 'one proposed claim' and does not explain how to fill the required AtomizeRequest fields or how they relate to the validation outcomes, so it fails to compensate for the absence of schema descriptions.
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 action ('validate one proposed claim') and lists the three expected outcomes ('admit, decompose, or request refinement'), so an agent has a clear idea of what the tool accomplishes. It does not explicitly distinguish itself from sibling tools enzo_observe or enzo_state, so it loses the top score.
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?
No guidance is given for when to choose this tool over enzo_observe or enzo_state, nor are the alternatives mentioned. The one sentence implies use when a proposed claim has been formed, but there are no exclusions or condition-based routing instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate typed evidence for one admitted atomic claim.
Deterministic evidence is authoritative. With TYPESAFE_API_KEY configured, semantic-only questions are evaluated by Pydantic AI's TypeSafe/Jev provider.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
| Name | Required | Description |
|---|---|---|
| source | Yes | |
| status | Yes | |
| atom_id | Yes | |
| evidence | Yes | |
| provenance | Yes | |
| parent_impact | Yes | |
| missing_information | No | |
| verification_method | Yes | |
| violated_constraints | No | |
| satisfied_constraints | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral disclosure burden. It adds meaningful context: deterministic evidence is authoritative, and semantic-only questions are routed to Pydantic AI's TypeSafe/Jev provider when the API key is present. However, it does not disclose whether the tool has side effects, requires specific authorization, or what happens when the API key is missing, leaving notable gaps.
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 two compact sentences with no filler. Front-loaded with the core purpose, the second sentence adds a useful behavioral condition. It loses one point only because the jargon-laden first sentence is not expanded for clarity.
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?
Given the complexity of the ObserveRequest schema and the absence of annotations, this description is too thin. It does not explain key concepts like 'admitted atomic claim', the evidence kinds, the semantics of constraints fields, or whether the tool returns a judgment or mutates state. While an output schema exists, proper use still requires more contextual guidance.
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 0%, so the description must compensate, but it does very little. It hints at the 'deterministic' flag and maybe 'allow_external_jev', but does not explain how to construct the ObserveRequest, what 'evidence' versus 'missing_information' means, or how constraints are used. The rich schema remains largely unexplained.
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 ('Evaluate') and resource ('typed evidence for one admitted atomic claim'), which clearly distinguishes it from the sibling tools enzo_atomize and enzo_state. However, 'admitted atomic claim' is domain jargon that may be unclear without additional context, so it misses the top score.
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 the tool is used when there is typed evidence for an atomic claim, and it notes a conditional (TYPESAFE_API_KEY configured) for semantic-only questions. It does not explicitly state when to use this tool versus enzo_atomize or enzo_state, nor does it mention exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return canonical history and computed investigation status.
| Name | Required | Description | Default |
|---|---|---|---|
| investigation_id | Yes |
| Name | Required | Description |
|---|---|---|
| atoms | Yes | |
| root_goal | Yes | |
| branch_ids | Yes | |
| unknown_atoms | Yes | |
| contradictions | Yes | |
| verified_atoms | Yes | |
| current_frontier | Yes | |
| investigation_id | Yes | |
| unresolved_atoms | Yes | |
| contradicted_atoms | Yes | |
| insufficient_evidence_atoms | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the behavioral burden. 'Return' and 'computed' imply a read-only snapshot that is derived rather than stored, but the description does not explicitly state whether it has side effects, authorization requirements, rate limits, or freshness guarantees.
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?
One tight sentence with no filler; the main action and result type are front-loaded. Nothing wastes an agent's attention.
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?
Low parameter complexity and an existing output schema reduce the need to spell out return values. Still, the missing usage guidance and lack of explicit read-only/behavioral confirmation leave the definition merely adequate rather than 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?
With 0% schema description coverage, the description partially compensates by tying the result to 'investigation status,' which makes investigation_id's role inferable. However, it adds no format, source, or validity details for the ID beyond what the property name already implies.
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 and resource: returning 'canonical history and computed investigation status.' It is clearly a state-retrieval tool, though it does not explicitly contrast itself with the siblings enzo_atomize and enzo_observe.
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?
There is no guidance on when to use this tool versus enzo_atomize or enzo_observe, no exclusions, and no alternative routing. The only usage signal is the tool name and the terse description.
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.
v0.1.0enzo_atomizeenzo_observeenzo_stateScored across 3 tools
Each tool maps to a distinct stage in the investigation workflow: atomize handles claim validation/admission, observe evaluates evidence against an admitted claim, and state returns the accumulated history and status. There is no meaningful overlap between tool purposes.
All tools share the consistent enzo_ prefix followed by a single lowercase word, creating a predictable enzo_<action> pattern. Even though 'state' is noun-like, the naming convention is uniform across the set.
Three tools is well-scoped for this narrow investigation workflow, and each tool is load-bearing: one for claims, one for evidence evaluation, and one for state. No tool feels redundant or missing for the stated purpose.
The server covers the full claim-investigation loop: claim validation/decomposition, evidence evaluation, and canonical history/status retrieval. An agent can iterate between atomize and observe and consult state at any point without hitting a dead end.
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
MCP-native web evidence and claim verification: cited, source-grounded evidence for AI agents.
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
Free OpenAI-compatible inference with signed provenance receipts and 3 focused MCP tools.
