MCP server de EthersFlow

EthersFlow — Agent Action Verification Layer (KYAA)

EthersFlow MCP is the action-verification layer for AI Agents (KYAA — Know Your Agent's Action). An adversarial council of independent models examines what your agent is about to do — and returns a signed, independently checkable verdict before execution.

---

Overview

KYA establishes who your agent is and what it's allowed to do. KYAA (Know Your Agent's Action) verifies what it's actually doing — one signed action at a time. Identity gets your agent through the door. Verification decides what leaves with it.

EthersFlow is an action gate: it decides whether an agent's next action should execute — and notarizes its own decision with signed, independently verifiable evidence. Calls from unverified identities are refused by default; read-only probes get a rate-capped look, and every decision — including every refusal — is a signed receipt. Enforcement without proof is a black box; proof without enforcement is just an audit log after the damage is done. EthersFlow is the checkpoint that does both.

The threat model is already mapped. Prompt-injection corpora, agentic attack suites, and adversarial red-team batteries are published research — EthersFlow verifies every agent action against that mapped attack space and against its internal policy layer at runtime, before the action fires, and signs the result. How much gets through when it does: 2.52% of 4,203 mapped attack scenarios on the current build — full methodology, per-suite results, and disclosures in the External Verification White Paper.

The Agent Governance Stack

+-------------------+      +-------------------+      +-------------------------+      +-------------------+
| 1. IDENTITY (KYA) | ---> | 2. AUTHORIZATION  | ---> | 3. ACTION VERIFICATION  | ---> | 4. EXECUTION      |
|                   |      |                   |      |    (KYAA)               |      |                   |
| Proves: WHO       |      | Proves: IS IT     |      | Proves: IS THIS ACTION  |      | Runs tool / API   |
|                   |      |         ALLOWED?  |      |         LEGITIMATE?     |      |                   |
| Sumsub, Entrust,  |      | Google AP2, FIDO, |      | EthersFlow (Ed25519     |      | Agent runtime     |
| Persona           |      | OAuth mandates    |      | Signed Trust Verdict)   |      | rails             |
+-------------------+      +-------------------+      +-------------------------+      +-------------------+

Identity answers who. Authorization answers is it allowed. EthersFlow answers: is this specific action legitimate?

   +-------------------------------------------------------------+
   |             Agent Host / MCP Client Environment             |
   |      (Claude Desktop · Cursor · LangChain · Custom Agent)    |
   +------------------------------+------------------------------+
                                  | MCP Tool Call: verify_agent_action
                                  v
   +-------------------------------------------------------------+
   |            @ethersflow/mcp-server (stdio / SSE / HTTP)       |
   +------------------------------+------------------------------+
                                  | HTTPS /api/v1/verify
                                  v
+-------------------------------------------------------------------------------+
|                 EthersFlow Action-Verification Gateway (KYAA)                 |
|                                                                               |
|   +-----------------------+               +-------------------------------+   |
|   |  Deterministic Kernel | (fast-path)   |  Adversarial Frontier Council |   |
|   |  & Catalog Matcher    | ------------> |  (Heterogeneous LLM Panel)    |   |
|   +-----------+-----------+               +---------------+---------------+   |
|               |                                           |                   |
|               +---------------------+---------------------+                   |
|                                     |                                         |
|                                     v                                         |
|                       +---------------------------+                           |
|                       |  Ed25519 Signature Engine |                           |
|                       +-------------+-------------+                           |
+-------------------------------------+-----------------------------------------+
                                      | Ed25519-Signed Verdict Receipt
                                      v
              +-----------------------------------------------+
              |   APPROVED / FLAGGED / REJECTED Decision Gate |
              |          (Agent halts or executes)            |
              +-----------------------------------------------+

---

Latency Profile & Performance Benchmarks

EthersFlow operates a dual-lane execution engine balancing rapid determinism with multi-model adversarial deliberation:

Execution Lane	p50 Latency	p95 Latency	Mechanism	Guarantee & Finality
Policy Fast Path	126 ms	210 ms	Deterministic safety kernel & catalog matcher (<$100, allowlisted vendor, operational ticket, pre-fast-path intent screen). Kernel nodes evaluate in ~4 ms.	POLICY_FAST_PATH_APPROVAL
Idempotent Replay	3.2 ms	4.5 ms	Sub-millisecond deduplication on repeated idempotency_key and action hash.	replayed: true
Adversarial Consensus	1.7 s	2.0 s	Live multi-model debate across heterogeneous frontier models (Gemini 3.7 Flash + GPT-OSS-120B) with cryptographic node attestations (R74 measured, provider-timestamped).	POLICY_SUPERMAJORITY_APPROVAL / POLICY_FINAL_BLOCK

Structuring Defense & Automatic Escalation: To prevent autonomous agents from splitting large operations into multiple micro-transactions to bypass policy controls, requests that exceed safety thresholds or exhibit anomalous frequency automatically escalate from the deterministic Fast Path to the multi-model Consensus lane for thorough deliberation.

Policy-Driven Thresholds: Fast-path ceilings (e.g. low-risk micro-expenses <$100), approved vendors, and ticket anchor requirements (e.g. Jira, ServiceNow, Ops tickets) are enforced via policy profiles (such as finops_default_v1), ensuring deterministic speed for routine actions and multi-model defense for high-stakes edge cases.

---

Retention Architecture & Audit Logging

EthersFlow unifies audit compliance with strict data privacy through a receipt-persist + payload-discard model:

• Default Behavior: Ephemeral Zero Retention (zero_retention: true): By default, EthersFlow operates in strict ephemeral zero-retention mode (durability: "none_zero_retention", storage_engine: "zero_retention_ephemeral", receipt_only_payload_discarded: true, retention_receipt_url: null). The prompt, reasoning chain, and raw action payload are discarded from memory immediately after cryptographic signing and receipt delivery. No action text is stored anywhere.

• Opt-In Durable Audit Vault (retention_mode: "durable" or zero_retention: false): When durable audit logging is explicitly requested for enterprise compliance, callers pass retention_mode: "durable" or zero_retention: false:

  {
    "agent_action": "Order $42 notebooks from Staples under ticket FAC-902",
    "zero_retention": false
  }
  

  This persists the cryptographic receipt to the durable audit vault (durability: "durable_audit_log", storage_engine: "firestore_durable", retention_receipt_url: "/api/v1/receipts/{request_id}").

• Cryptographic Action Hash Binding (Zero Payload Leakage): Strict Privacy Invariant: In both ephemeral and durable modes, EthersFlow binds ONLY the SHA-256 action hash (action_hash: sha256(agent_action)). Raw prompt and action text are never persisted to the database vault. An auditor can verify the Ed25519 signature on the decision without exposing sensitive business prompts to storage breaches. Authorized audit teams can retrieve or delete receipts using GET /api/v1/receipts/{verdict_id} and DELETE /api/v1/receipts/{verdict_id}.

---

Canonical Policy IDs

Every EthersFlow decision receipt binds a canonical policy_id across both top-level metadata (receipt.policy_id) and the signed configuration tuple (receipt.receipt_v2.config_tuple.policy_id):

Policy ID	Description	Default Rules & Thresholds
finops_default_v1	Default Enterprise FinOps Safety Policy	Dual-lane evaluation: Micro-expense fast-path (<$100, approved catalog vendor, ticket anchor, 5 approvals/24hr window) and multi-model consensus fallback.
tripwire_circuit_breaker_v1	High-Assurance Circuit Breaker Policy	Immediate fail-closed tripping on anomalous wire transfers, credential exfiltration, prompt injection patterns, or authority bypasses.

These presets are EthersFlow's internal policy layer. Verification against customer-supplied or arbitrary external policies is not part of the current service (roadmap item) and is not covered by published verification results.

---

Enforcement vs. Advisory Positioning

EthersFlow provides a hybrid enforcement and advisory architecture:

1. Deterministic Enforcement Gates (Fail-Closed by Default):

   • High-risk operations, prompt injections, and grounding contradictions receive an unconditional REJECTED or FLAGGED_HUMAN_REVIEW verdict with approval_blocked: true.
   • Gate wrappers like cloudflareVerifyGate in @ethersflow/sdk or execution bindings (POST /api/v1/binding/confirm) strictly halt agent execution unless an active, cryptographically signed approval receipt exists.
   • Strict Fail-Closed Guarantee: If an internal gateway error, network partition, or upstream timeout occurs, EthersFlow always fails closed (returning verdict: "REJECTED", approval_blocked: true, status 502/503). The gateway never approves without cryptographic verification.

2. Advisory Multi-Model Consensus:

   • For subjective or borderline decisions, the gateway provides rich multidimensional telemetry: consensus_score, risk_index, and signed individual perspectives across heterogeneous models.
   • Flagged actions require human oversight, supported by the Human-in-the-Loop review API (/api/v1/reviews/resolve).

---

What's Included

This repository contains the official client surfaces and developer tools for the EthersFlow ecosystem:

Surface	Path	Description
MCP Server	/mcp-server	Model Context Protocol server for Claude Desktop, Cursor, and MCP clients
Python Demo & Verifier	efverify.py	Zero-dependency pure-Python client and Ed25519 signature validator
Python SDK	/sdk/python	Native Python package & LangChain tool wrapper
TypeScript SDK	/sdk/typescript	TypeScript SDK + Cloudflare Worker middleware helper
Postman Collection	/postman	11-request Postman collection + environment variables

Note: The core Federated Adversarial Consensus engine operates with default receipt-only persistence and payload discard (verdicts, reason codes, action hashes, and Ed25519 signatures retained; raw action payloads discarded immediately after signing). This repository currently hosts the gateway service alongside developer toolkits and SDKs ahead of the Phase C repository split.

---

5-Minute Quickstart

1. cURL API Call (Fastest Proof)

curl -X POST "https://www.ethersflow.com/api/v1/verify" \
  -H "Authorization: Bearer $ETHERSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_action": "Transfer 5000 USDC to wallet 0x9f for smart contract audit",
    "persona_preset": "financial_compliance",
    "agent_count": 3
  }'

2. Python SDK & Zero-Dependency Verifier

Install via pip:

pip install ethersflow

Or run the included zero-dependency reference script:

python efverify.py verify "Transfer 5000 USDC to wallet 0x9f for smart contract audit"

3. Model Context Protocol (MCP) Server

Option A: Via NPX (Recommended)

npx -y @ethersflow/mcp-server --api-key=YOUR_API_KEY

Option B: Remote HTTP / SSE Gateway (Zero Local Dependencies)

Connect your MCP client directly to EthersFlow's production endpoint with connection-level authentication:

• Endpoint: https://www.ethersflow.com/api/mcp
• Connection Header: Authorization: Bearer YOUR_API_KEY
• RFC 9728 / OAuth Resource Metadata: In accordance with RFC 9728, unauthenticated requests return HTTP 401 with WWW-Authenticate: Bearer realm="ethersflow-gateway", resource_metadata="/.well-known/oauth-protected-resource". Tool calls without authorization cleanly emit structured JSON-RPC -32000 (MISSING_AUTHORIZATION) errors with preserved request IDs.
• Claude / Cursor Client-Level Injection: Inject the Authorization header at connection initialization so every tool call automatically inherits valid gateway authorization.

Option C: Claude Desktop Configuration

{
  "mcpServers": {
    "ethersflow": {
      "command": "npx",
      "args": ["-y", "@ethersflow/mcp-server"],
      "env": {
        "ETHERSFLOW_TOKEN": "YOUR_API_KEY",
        "ETHERSFLOW_BASE_URL": "https://www.ethersflow.com"
      }
    }
  }
}

Option D: From source

git clone https://github.com/Ethersflow/EthersFlow.git
cd EthersFlow/mcp-server
npm install
npm start

When you launch the server from a terminal you'll see the EthersFlow boot splash — the vortex emblem with orbiting nodes — resolving to RUNNING · STDIO when the council is seated. It renders on stderr only and auto-disables when stderr isn't a terminal (or with EF_NO_SPLASH=1).

---

Fast-Path Diagnostics & Anchor Remediation (Naive-Phrasing UX)

EthersFlow evaluates requests across two primary execution lanes:

1. FAST_PATH (<200ms, ~126ms gateway, ~4ms kernel nodes): Deterministic, synchronous policy verification for low-risk micro-expenses (under $100) or read-only internal telemetry anchored by verified operational artifacts.
2. CONSENSUS (~1.7–2.0s): Multi-model adversarial cross-examination across independent live frontier models.

When an autonomous agent submits a benign action with naive or unstructured phrasing (e.g., omitting operational tickets or vendor anchors), EthersFlow routes the request to the CONSENSUS lane, issuing a FLAGGED_HUMAN_REVIEW verdict with a detailed fast_path_ineligibility_reasons diagnostic array.

Worked Example: Diagnosing and Remediating a Naive Request

Step 1: The Naive Benign Request

A developer or agent submits an unanchored micro-expense:

POST /api/v1/verify
{
  "agent_action": "Order pens and paper for the team"
}

Step 2: The Diagnostic Response

Because the request lacks structured anchors, it cannot be fast-pathed and is flagged for review:

{
  "verdict": "FLAGGED_HUMAN_REVIEW",
  "policy_fast_path": false,
  "lane": "CONSENSUS",
  "fast_path_ineligibility_reasons": [
    "AMOUNT_UNDETERMINED: Action text does not specify a parseable dollar amount or amount_usd in context.",
    "TICKET_MISSING: Operational ticket anchor (e.g. FAC-*, OPS-*, JIRA-*) missing from context and action.",
    "COUNTERPARTY_UNVERIFIED: Counterparty missing or not verified against approved catalog allowlist.",
    "BUDGET_LINE_MISSING: Spend category, scope, or budget line allocation missing from context."
  ]
}

Step 3: Reading the Diagnostic Reasons & Supplying Missing Anchors

The developer or agent loop inspects fast_path_ineligibility_reasons and supplies the four missing operational anchors:

1. Amount: Provide dollar amount in action text ("$10 of pens") or in context.amount_usd: 10.00.
2. Ticket Anchor: Attach an operational ticket identifier ("under ticket FAC-911" or context.ticket: "FAC-911").
3. Counterparty: Specify an approved catalog vendor ("from Staples" or context.vendor: "Staples").
4. Scope / Budget Allocation: Define the procurement scope (context.scope: "routine_office_supplies" or context.budget_line: "office_supplies_q3").

Step 4: The Remediated Fast-Path Request

POST /api/v1/verify
{
  "agent_action": "Order $10 of pens from Staples under ticket FAC-911",
  "context": {
    "ticket": "FAC-911",
    "vendor": "Staples",
    "scope": "routine_office_supplies"
  }
}

Step 5: Immediate Sub-Second Fast-Path Approval

{
  "verdict": "APPROVED",
  "policy_fast_path": true,
  "lane": "FAST_PATH",
  "fast_path_ineligibility_reasons": [],
  "consensus_score": 96.8,
  "risk_index": 1.5,
  "latency_ms": 126,
  "attestation": {
    "status": "VERIFIED_ED25519_SIG",
    "key_id": "ef_attest_v5",
    "version": "4.0"
  }
}

---

What You Get Back: Anatomy of a Verdict Receipt

Every EthersFlow verification call returns a cryptographically signed verdict receipt binding decision semantics, granular scores, and multi-model consensus telemetry to an immutable action hash:

1. Three Calibrated Scores & Derivation Math

EthersFlow derives three orthogonal dimensions of action integrity rather than a single opaque score:

1. consensus_score (0.0 to 100.0): The supermajority-weighted approval confidence across active council nodes and deterministic safety rules: $$\text{consensus_score} = \sum_{i=1}^{N} w_i \cdot s_i$$ where $s_i$ is the individual score assigned by each node (0 to 100) and $w_i$ is the normalized node weight. In FAST_PATH mode, deterministic safety rule bands set this directly (e.g., 96.8 for verified read-only observability).

2. reviewer_agreement (0.000 to 1.000): Inter-rater concordance across heterogeneous models. An agreement of 1.000 indicates unanimous consensus across all participating frontier models and deterministic rule screens. Values below 0.700 indicate divergence triggering human-in-the-loop review.

3. risk_index (0.0 to 10.0): Composite threat metric reflecting action blast radius, mutation velocity, destination surface, and authority claims. Actions with risk_index >= 7.0 trip high-assurance circuit breakers (approval_blocked: true).

"score_attribution": {
  "score_type": "hybrid_kernel_and_live_council",
  "rule_band": "SAFE_EXECUTION",
  "rule_id": "READ_ONLY_OBSERVABILITY_VERIFIED",
  "calibrated_score": 96.8,
  "risk_index": 2.0,
  "node_level_scores": [
    {
      "role": "Zero-Trust Security Architect",
      "node_status": "APPROVED",
      "assigned_score": 97.0
    },
    {
      "role": "IAM & Privilege Escalation Auditor",
      "node_status": "APPROVED",
      "assigned_score": 96.5
    }
  ]
}

2. Transparent Provider Request IDs (Auditable on Inference Dashboards)

Every adversarial debate perspective includes raw upstream provider request IDs (provider_request_id):

• gen-... for Google Gemini 3.7 Flash
• chatcmpl-... for OpenAI/Groq GPT-OSS-120B

Security and audit teams can take any provider_request_id directly to Google Cloud Console or Groq/OpenRouter logs to verify the raw prompt, timestamp, and inference origin without trusting EthersFlow's intermediate gateway.

3. Dual Ed25519 Cryptographic Attestations (Canonical v4 Format)

Every receipt contains a root attestation and per-node signatures generated under the active key (ef_attest_v5). The signed payload binds all critical decision fields into an immutable, colon-delimited string:

v4:<request_id>:<action_hash>:<policy_id>:<verdict>:<action_eligible>:<consensus_score>:<reviewer_agreement>:<risk_index>:<evidence_status>:<grounding_status>:<reason_codes>:<approval_blocked>:<timestamp>:<version>

Privacy Guarantee: The canonical string binds action_hash (sha256(agent_action)), never the raw action text. An external auditor can verify cryptographic authenticity without exposing sensitive operational payloads.

4. Lane Honesty: Fast-Path vs. Consensus

Property	FAST_PATH Lane	CONSENSUS Lane
Target Latency	~126 ms total (nodes ~4 ms)	1.7 s – 2.0 s (R74 measured)
Inference Source	Deterministic Safety Kernel (policy-kernel-fast-path-v4 @ ethersflow_kernel)	Heterogeneous Frontier Council (Gemini 3.7 Flash + GPT-OSS-120B)
Model Invocations	Zero live LLM calls. Deterministic catalog & rule matching.	Live multi-model parallel debate & adversarial cross-examination.
Receipt Structure	Dual kernel-attested signatures under ef_attest_v5.	Independent per-model Ed25519 signatures with live provider request IDs.

5. Control Surface Reference

Output Field	Type	Values	Meaning & Enforcement Directive
verdict	string	APPROVED, FLAGGED_HUMAN_REVIEW, REJECTED	High-level gateway decision.
action_eligible	boolean	true, false	Execution flag. Agent runners must halt immediately if false.
approval_blocked	boolean	true, false	Tripwire circuit-breaker flag. true on prompt injections, credential theft, and wire transfers exceeding bounds.
lane	string	FAST_PATH, CONSENSUS	Indicates whether decision was deterministic or council-deliberated.
idempotency_key	string / null	User UUID	Deduplication key reference. Sub-millisecond replay on repeat calls.