🧠 FHESTATE: Model Context Protocol (MCP) Server

AUTONOMOUS AI AGENTS POWERED BY FULLY HOMOMORPHIC ENCRYPTION (FHE)

"Granting AI the power to execute FHE on-chain, without ever seeing the plaintext."

📑 Table of Contents

• 1. Overview
• 2. The Coprocessor Architecture & IPC
• 3. The Security & Redaction Engine
• 4. The Confidential Execution Flow (Memo Anchoring)
• 5. Use Case: Autonomous Agent Workflows
• 6. The Comprehensive Tool Matrix
• 7. Quick Start & IDE Integration
• 8. LLM Execution Example (JSON-RPC Lifecycle)
• 9. Troubleshooting & IPC Error Codes
• 10. Contact & Support

🌟 1. Overview

The FHESTATE MCP Server is a production-grade execution bridge that connects non-deterministic Large Language Models (LLMs) like Claude 3.5 Sonnet to deterministic Fully Homomorphic Encryption (FHE) on the Solana blockchain.

In the current landscape of Artificial Intelligence, LLMs act as "brains in vats." They can reason and write code, but they are fundamentally isolated from secure, cryptographic hardware. The FHESTATE Model Context Protocol (MCP) solves this by providing a standardized, zero-trust stdio pipeline directly into a local Rust cryptographic coprocessor.

By utilizing this MCP Server, you transform a passive AI chatbot into an active, confidential FHE operator. The AI can autonomously encrypt local memory, perform off-chain homomorphic math, and anchor the resulting SHA-256 hash commitments to the Solana blockchain—all without ever possessing the decryption keys.

1.1 The Institutional Paradigm Shift

• 🤖 Zero-Trust AI Autonomy: The LLM can direct FHE operations without ever seeing the plaintext data or the client_key.bin.
• 🛡️ Subprocess Isolation: Heavy TFHE mathematics are routed safely through local Rust subprocesses to prevent AI memory exhaustion and Denial of Service (DoS).
• 🔗 Solana Devnet Anchoring: Agents can autonomously construct, sign, and broadcast transactions to the Solana Devnet, spending local wallet funds to post immutable cryptographic proofs.
• 🔒 Aggressive Redaction: Absolute system paths are scrubbed from LLM context windows to prevent local host topology leaks to cloud providers (OpenAI/Anthropic).
• ✅ Strict Zod Boundaries: Cryptographic Uint32 constraints are strictly enforced via Zod schemas, instantly rejecting AI hallucinations before they crash the Rust binary.

🏗️ 2. The Coprocessor Architecture & IPC

The fundamental challenge of implementing FHE on Solana is the strict 1.4 million Compute Unit (CU) transaction limit. Evaluating a single TFHE-rs boolean gate requires thousands of CPU cycles; evaluating a full homomorphic addition or multiplication requires billions.

To solve this, the FHESTATE MCP Server implements a Coprocessor Architecture. The Node.js server does not perform the cryptography itself. Instead, it securely spawns the fhe-cli Rust binary, acts as a sanitization layer, and manages the blockchain network calls.

2.1 Component Interaction Flow

graph TD
    subgraph "Cloud / AI Layer"
        LLM[Claude 3.5 / Cursor LLM]
        MCP_CLIENT[MCP Client Interface]
    end

    subgraph "Host Machine (Node.js MCP Server)"
        ZOD[Zod Validation Layer]
        REDACT[Path Redaction Engine]
        RPC_SERVER[JSON-RPC 2.0 Server]
        WEB3[Solana Web3.js]
    end

    subgraph "Host Machine (Rust / Cryptography)"
        FHE_CLI[fhe-cli Binary]
        TFHE[TFHE-rs Library]
        KEYS[.fhe_keys Directory]
    end

    subgraph "Solana Network"
        DEVNET[Solana Devnet RPC]
    end

    LLM <-->|JSON-RPC via stdio| MCP_CLIENT
    MCP_CLIENT <--> RPC_SERVER
    
    RPC_SERVER -->|Validate Params| ZOD
    ZOD -->|fhe_encrypt / blind_step| FHE_CLI
    FHE_CLI -->|Reads| KEYS
    FHE_CLI -->|Computes| TFHE
    FHE_CLI -->|stdout Hash| REDACT
    REDACT --> RPC_SERVER
    
    ZOD -->|devnet_submit_memo| WEB3
    WEB3 -->|Sign Tx| DEVNET

2.2 Deep Dive: Inter-Process Communication (IPC)

The MCP server uses asynchronous stdio to communicate with the IDE/Claude Desktop, but it uses child_process.spawn to communicate with the Rust Coprocessor. This is managed by the cli-bridge.ts module.

When the AI Agent calls fhe_encrypt(42):

1. Payload Interception: The Node MCP Server receives the JSON-RPC request.
2. Argument Construction: Node constructs an argument array: ['encrypt', '--value', '42']. It strictly avoids using shell interpolation.
3. Subprocess Spawning: Node spawns the Rust process with shell: false and a cwd restricted to the workspace.
4. Lattice Computation: The Rust Coprocessor spins up the TFHE-rs lattice mathematics. This consumes ~500MB of RAM and heavily utilizes the CPU for roughly 2-3 seconds to generate a massive 15MB ciphertext file.
5. Buffer Management: The Rust binary writes the resulting SHA-256 hash of that file to its stdout pipe. Node's cli-bridge.ts reads the stream.
6. Graceful Exit: The Node server closes the process, parses the output through the Redaction Engine, and returns the formatted hash to the AI.

🔒 3. The Security & Redaction Engine

Because the AI Agent is fundamentally untrusted and operates in a non-deterministic manner, the MCP Server implements extreme isolation and data scrubbing mechanisms. It assumes the LLM is actively hostile or prone to severe hallucinations.

3.1 The Redaction Engine (redact.ts)

LLMs are cloud-hosted. If the local Rust binary outputs a success message like Saved to C:\Users\Admin\Documents\Crypto\.fhe_keys\client_key.bin, passing this raw string back to the LLM exposes your local folder structure, username, and topology to Anthropic/OpenAI servers.

The MCP Server utilizes a specialized Redaction Engine that intercepts all stdout arrays before they are formatted into the JSON-RPC response.

flowchart LR
    Rust[Rust Coprocessor] -->|Raw stdout| Buffer[Node.js Buffer]
    Buffer --> Regex1[Regex: Match Absolute Paths]
    Regex1 --> Regex2[Regex: Match Base58/Seeds]
    Regex2 --> Mask[Overwrite with REDACTED]
    Mask --> LLM[Return to AI Context]

• Path Scrubbing: It uses heuristic regex to locate Windows (C:\...) and POSIX (/...) absolute paths and overwrites them with [REDACTED_PATH].
• Key Scrubbing: It scans for 12-word seed phrases or 88-character Base58 strings that resemble private keys and masks them, ensuring the AI never accidentally reads the developer's wallet secret into its context window.

3.2 Zod Strictness & Cryptographic Bounds

LLMs frequently hallucinate string parameters where integers are required. Because TFHE-rs operates on strict byte widths, it will panic and abort the process if fed a non-standard byte width (e.g., a float or a negative number).

The MCP Server uses strict zod schemas to enforce Uint32 boundaries. If Claude attempts to call fhe_encrypt(1.5) or injects a path traversal payload like fhe_encrypt("../../"), the Zod layer intercepts the call before it hits the Rust binary. It immediately returns a JSON-RPC -32602 Invalid Params error, forcing the AI to self-correct its logic.

3.3 Buffer Capping & DoS Prevention

The stdout buffer from the FHE binary is capped at exactly 512KB. If an AI hallucinates an infinite loop or triggers a command that dumps massive amounts of data, the subprocess is forcefully terminated via SIGKILL after 60 seconds to prevent host memory exhaustion.

3.4 Read-Only Sandbox Override

If you are running a public hackathon or do not want the AI to spend Devnet SOL, you can hard-lock the network layer. Set FHESTATE_MCP_READ_ONLY=1 in the env block of your MCP configuration. The AI will still be able to execute heavy FHE math locally, but the devnet_submit_memo tool will immediately throw an Unauthorized error.

🌊 4. The Confidential Execution Flow (Memo Anchoring)

The core functional purpose of the MCP Server is to allow AI agents to securely execute FHE commitments and anchor them to the Solana blockchain.

sequenceDiagram
    participant User
    participant AI Agent
    participant Node Coprocessor
    participant Solana Devnet

    note over User, Solana Devnet: Phase 1: Local FHE Encryption
    User->>AI Agent: "Encrypt the value 150"
    AI Agent->>Node Coprocessor: fhe_encrypt(150)
    Node Coprocessor->>Node Coprocessor: Load client_key.bin
    Node Coprocessor->>Node Coprocessor: Generate 15MB Ciphertext
    Node Coprocessor-->>AI Agent: Return SHA-256 Hash
    
    note over User, Solana Devnet: Phase 2: On-Chain Anchoring
    AI Agent->>Solana Devnet: devnet_submit_memo(Hash)
    Solana Devnet-->>AI Agent: Return Signature & Solscan Link
    AI Agent-->>User: "Success. Your data is encrypted and anchored."

4.1 Local Encryption Phase

The AI Agent utilizes the fhe_encrypt tool to encrypt the data locally. The plaintext value never leaves the host machine. Because the generated ciphertext is massive, the Rust node stores it securely in the .fhe_keys/ directory and returns only the 32-byte cryptographic hash to the AI.

4.2 On-Chain Anchoring Phase

The AI Agent automatically calls the devnet_submit_memo tool with the resulting hash. The MCP server utilizes @solana/web3.js to construct an SPL Memo transaction (formatted exactly as local://<hash>). The server signs the transaction using the developer's keypair specified in FHESTATE_WALLET_PATH, and broadcasts it to the Solana Devnet, returning the finalized signature to the AI.

🤖 5. Use Case: Autonomous Agent Workflows

How does an AI actually use this MCP server in a real-world scenario?

To ensure that the LLM cannot hallucinate steps or skip cryptographic verifications, the MCP server enforces an internal blind-step hash chain. The server's registry defines 3 distinct AI agents (Sentinel, Auditor, Coordinator) that can be combined into different confidential workflows (missions).

The MCP Server is pre-configured with 3 execution workflows (demo scripts) that show how these agents interact:

Workflow 1: The Fast Path (Sentinel Only)

"Sentinel Secret Vote" This is the fastest workflow. A single Sentinel agent takes a user's binary vote (1 or 0), encrypts it locally via fhe_encrypt, and advances the hash chain. No other agents are required.

Workflow 2: The Compliance Path (Sentinel → Auditor)

"Sentinel → Auditor Compliance Scan → Auditor Seal Record"

1. Sentinel: Encrypts the user's intent and establishes the stepHash.
2. Auditor: Receives the stepHash from the Sentinel, runs a zero-knowledge compliance scan against the encrypted data, and permanently seals the record if the policy passes.

Workflow 3: The Routing Path (Sentinel → Coordinator)

"Sentinel Market Signal → Coordinator Route Intent"

1. Sentinel: Encrypts a quantitative market signal (e.g., a blind trade intent) and passes the hash forward.
2. Coordinator: Takes the verified signal hash and routes the intent to a specific execution channel on-chain using devnet_submit_memo.

🛠️ 6. The Comprehensive Tool Matrix

The MCP Server exposes exactly 13 highly restricted JSON-RPC tools. If a tool is not on this list, the AI cannot execute it. Every tool is strictly typed using Zod.

6.1 FHE Cryptography Tools (Compute-Heavy)

1. fhe_encrypt

• Description: The core cryptographic engine. Takes a plaintext Uint32 integer from the LLM, pipes it to the local Rust fhe-cli, and generates a massive (15MB+) TFHE-rs ciphertext. To protect the LLM context window, it only returns the SHA-256 commitment hash.
• Risk Profile: Moderate (High CPU Usage).
• Zod Schema:

  z.object({
    value: z.number().int().min(0).max(4294967295)
  }).strict()

2. agent_run_blind_step

• Description: Advances the agent memory chain. Takes an agentId (Sentinel/Auditor) and a missionId, and computes the next link in the local stepHash chain.
• Risk Profile: Low.
• Zod Schema:

  z.object({
    agentId: z.string(),
    missionId: z.string(),
    value: z.number().int().min(0).max(4294967295)
  }).strict()

3. fhe_cli_run

• Description: A highly restricted sandbox allowing the AI to execute specific diagnostic commands on the fhe-cli binary.
• Risk Profile: Moderate.
• Zod Schema:

  z.object({
    subcommand: z.string(),
    args: z.array(z.string()).max(10)
  }).strict()

  (Note: Only subcommands ['doctor', 'history', 'balance'] are allowlisted. Path traversal ../ is explicitly blocked).

4. simulate_homomorphic_eval

• Description: Simulates the Auditor homomorphic logic over an encrypted payload, returning a deterministic boolean pseudo-hash. Bridges the gap between the theoretical Auditor functionality and the current CLI capabilities.
• Risk Profile: Low.
• Zod Schema:

  z.object({
    logicGate: z.string(),
    inputHash: z.string().min(64)
  }).strict()

6.2 Solana Network Tools (State Modifying)

5. devnet_wallet_status

• Description: Pings the FHESTATE_RPC and checks the exact SOL lamport balance of the keypair specified in FHESTATE_WALLET_PATH.
• Risk Profile: Low (Read-Only RPC call).
• Zod Schema: z.object({}).strict()

6. devnet_history

• Description: Fetches the 5 most recent transaction signatures associated with the local developer wallet, allowing the AI to verify if its previous transactions successfully landed on-chain.
• Risk Profile: Low (Read-Only RPC call).
• Zod Schema: z.object({}).strict()

7. devnet_submit_memo

• Description: [CRITICAL] This tool modifies blockchain state and spends funds. It constructs, signs, and broadcasts a live transaction to the Solana Devnet. It wraps the SHA-256 ciphertext hash generated by fhe_encrypt in an SPL Memo (local://<hash>), anchoring the FHE commitment on-chain.
• Risk Profile: Extreme. Spends Devnet SOL. Automatically disabled if FHESTATE_MCP_READ_ONLY=1 is set.
• Zod Schema:

  z.object({
    value: z.number().int().min(0).max(4294967295)
  }).strict()

8. solscan_link

• Description: A static formatting tool. Takes a raw Solana Base58 signature and constructs a valid https://solscan.io URL bound strictly to the Devnet cluster.
• Risk Profile: None (Static String Generation).
• Zod Schema:

  z.object({
    signature: z.string().min(80).max(90)
  }).strict()

6.3 Knowledge & Verification Tools (Zero Risk)

9. list_agents_and_missions

• Description: Returns the full JSON registry of all available confidential AI agents (Sentinel, Auditor, Coordinator) and their specific allowed mission IDs. Used to ground the AI before it executes a workflow.
• Zod Schema: z.object({}).strict()

10. execution_protocol_script

• Description: Returns the exact step-by-step presentation script used for walking a developer through the Sentinel Secret Vote workflow. Ensures the AI uses canonical phrasing during live integrations.
• Zod Schema: z.object({}).strict()

11. architectural_proof_checklist

• Description: Returns the pre-flight checklist required to successfully deploy the FHESTATE system in a live environment, ensuring all devnet wallets, rust binaries, and environment variables are positioned correctly.
• Zod Schema: z.object({}).strict()

12. get_mcp_config_state

• Description: Safely reads the server's local environment configuration. Returns redacted visibility into the operational state.
• Zod Schema: z.object({}).strict()

13. verify_ciphertext_hash

• Description: Zero-Trust format verification of an intent hash before anchoring to Devnet. Mathematically validates the SHA-256 entropy.
• Zod Schema:

  z.object({
    hash: z.string().min(64)
  }).strict()

🚀 7. Quick Start & IDE Integration

Because this MCP server interfaces with a local Rust binary, setup requires compiling the Coprocessor first.

Step 1: Compile the Rust Coprocessor

You must have Rust 1.70+ installed.

git clone https://github.com/fhestate/fhestate-rs.git
cd fhestate-rs
cargo build --release -p fhe-cli

Note the absolute path to the generated binary: .../fhestate-rs/target/release/fhe-cli.

Step 2: Build the MCP Server

cd mcp/fhestate-mcp
npm install
npm run build

Step 3: Configure the Solana Wallet

Generate a new Devnet keypair. DO NOT USE A MAINNET WALLET.

solana-keygen new --outfile devnet-wallet.json --no-bip39-passphrase
solana airdrop 2 -k devnet-wallet.json --url devnet

Note the absolute path to this JSON file.

Step 3: Configure Cursor IDE or Claude Desktop

Open your MCP configuration file:

• Cursor IDE: Settings > Features > MCP > Add New
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

Add the following configuration, replacing the absolute paths with your actual system paths:

{
  "mcpServers": {
    "fhestate-coprocessor": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/fhestate/mcp/fhestate-mcp/dist/index.js"],
      "env": {
        "FHESTATE_CLI_PATH": "/ABSOLUTE/PATH/TO/fhestate-rs/target/release/fhe-cli",
        "FHESTATE_WALLET_PATH": "/ABSOLUTE/PATH/TO/devnet-wallet.json",
        "FHESTATE_RPC": "https://api.devnet.solana.com",
        "FHESTATE_MCP_READ_ONLY": "0"
      }
    }
  }
}

Restart your IDE or Claude Desktop. You should now see the 13 tools available in the agent's context window. Type "Check my devnet wallet balance" to initiate the handshake.

💻 8. LLM Execution Example (JSON-RPC Lifecycle)

This is how an AI Agent (like Claude) actually communicates with the MCP Server under the hood to execute a confidential operation. The AI constructs a JSON-RPC payload:

{
  "jsonrpc": "2.0",
  "id": "req_1a2b3c",
  "method": "tools/call",
  "params": {
    "name": "fhe_encrypt",
    "arguments": {
      "value": 50
    }
  }
}

The MCP Server intercepts this, enforces the Zod Uint32 boundary, pipes the 50 to the Rust Coprocessor, and returns the redacted hash commitment back to the AI's context window:

{
  "jsonrpc": "2.0",
  "id": "req_1a2b3c",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Ciphertext generated. Local Hash: 8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4"
      }
    ]
  }
}

🛑 9. Troubleshooting & IPC Error Codes

When interacting with the MCP server over standard input/output (stdio), you may encounter specific JSON-RPC error codes resulting from the IPC Bridge.

| JSON-RPC Code | HTTP Equivalent | Trigger Scenario | Resolution | |---------------|-----------------|------------------|------------| | -32602 | 400 Bad Request | Zod Validation Failure. AI hallucinated a string instead of a Uint32 or tried to use path traversal ../. | Inform the AI of the Zod constraints. It will automatically correct its payload. | | -32603 | 500 Internal Error | CLI Binary ENOENT. The Node server cannot find the fhe-cli binary. | Verify FHESTATE_CLI_PATH in your MCP Config is absolute and the binary was compiled. | | -32000 | 504 Gateway Timeout| Coprocessor Timeout. The FHE math took longer than 60s. | You likely ran cargo build instead of cargo build --release. FHE math requires release optimizations. | | -32001 | 401 Unauthorized | Read-Only Sandbox active. AI tried to call devnet_submit_memo. | Set FHESTATE_MCP_READ_ONLY=0 if you intend to spend Devnet SOL. | | -32002 | 502 Bad Gateway | Solana Web3 Connection Error. Devnet RPC dropped the packet. | Switch FHESTATE_RPC to a premium provider like Helius or Alchemy. |

📞 10. Contact & Support

• Documentation: Comprehensive Technical Specs
• GitHub Issues: Report bugs or request features
• Discussions: Join community discussions
• Twitter: @fhe_state