> For the complete documentation index, see [llms.txt](https://esper.gitbook.io/esperchain-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://esper.gitbook.io/esperchain-docs/architecture/proof-of-ai-consensus/esper-mcp.md).

# Esper MCP

### Why “Model Context Protocol”?

AI agents rarely want a pure vanilla model; they need **domain context**:

* current block height, AMM pool reserves, oracle prices
* user-supplied background (strategy, goals, style guide)
* static corpora (white-papers, docs, laws)

MCP lets you *reference* and *version* that context on-chain **without** bloating blocks, while keeping zkLLM proofs 100 % deterministic.

***

### 2 Design goals

| Goal                        | Mechanism                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------ |
| **Deterministic inference** | Context root (Poseidon-512) is part of the public inputs proven in zkLLM.            |
| **Zero-trust retrieval**    | Clients fetch shards from IPFS/Arweave; proof checks the Merkle root, not the bytes. |
| **Composable**              | A single `LLMCall` can import many context IDs; miners fuse them into one prompt.    |
| **Cheap**                   | Adding or pinning context is <200 bytes on-chain; actual text lives off-chain.       |
| **Epoch-aware**             | Each model-rotation upgrades the *context schema* in lock-step (e.g. new tokenizer). |

***

### 3 Core data structures

```
struct ContextHeader {
  id            Poseidon512   // commitment of full tree
  owner         Address
  schema        uint8         // which tokenizer / format
  size_bytes    uint32
  created_at    BlockHeight
  expires_at    BlockHeight   // optional; 0 = eternal
}

enum MCP tx ⇢
  • ContextAdd      {root, size, schema, optional uri}
  • ContextUpdate   {ctx_id, new_root, diff_patch_uri}
  • ContextPin      {ctx_id}                // extend TTL
  • ContextDelete   {ctx_id}
```

> **Storage model**
>
> * `ContextHeader` lives in Esperchain state.
> * The actual text chunks are **content-addressed** (CAR files, IPLD) and replicated by anyone who benefits (miners, dApps, gateways).
> * Miners are *not* forced to store the bytes—only the 32-byte root.

***

### 4 Calling the LLM with context

```json
LLMCall {
  "prompt": "Summarise my DeFi positions.",
  "ctx": [
    "0xC0FFEE…",        // Wallet & position dump
    "0xBEEF12…"         // Latest AMM state snapshot
  ],
  "max_tokens": 128
}
```

#### Miner / zkLLM workflow

1. **Fetch** referenced context chunks (or from local cache).
2. **Concatenate** in canonical order: `[sys] + Σ(ctx_i) + [userprompt]`.
3. **Tokenise** under current model schema.
4. Run forward-pass → `y`.
5. Build STARK proof **including**:
   * each `ctx_id`
   * Merkle root of concatenated context
   * final Poseidon hash `r` used for difficulty check

Full-nodes verify `π` in the ordinary PoAI block-validation step.\
No extra gas; caller pays in *Compute Credits* (CC) per generated token **plus** tiny CC surcharge per kilobyte of context.

***

### 5 Governance & lifecycle

#### 5.1 Context schemas

*Model DAO* upgrades both the **model weights** and the **tokeniser / schema ID** every six-month epoch.\
A context created under `schema = 3` is **read-only** once the chain activates `schema = 4`; dApps must re-index or migrate.

#### 5.2 Slashing for poisonous context

If a context is proven malicious (e.g. breaks determinism, illegal content) the DAO can mark it `blacklisted`, and any `LLMCall` referencing it is invalid **and** slashes the caller 1 % stake.

***

### 6 Reference client flow (Agents)

{% @mermaid/diagram content="sequenceDiagram
autonumber
participant Agent
participant ContextHub
participant Esper\_RPC
Agent->>ContextHub: POST /add  {ipfsUri}
ContextHub-->>Agent: ctx\_id
Agent->>Esper\_RPC: LLMCall{prompt, ctx:\[ctx\_id], max:128}
Esper\_RPC-->>Agent: tx\_hash
Esper\_RPC-->>Agent: receipt + answer (after block finality)" %}

*ContextHub* is an optional off-chain helper that lets users pin large corpora and returns the on-chain transaction ready to sign.

***

### 7 MCP and zkLLM side-by-side

```
          +------------------+
          |  zkLLM proof π   |
          |------------------|
          | model_id         |
          | batch_B_hash     |
          | context_root     |  <-- **MCP JOIN POINT**
          | logits_root      |
          +------------------+
```

`context_root` glues MCP to zkLLM: change any byte in the context → different root → proof fails.

***

### 8 Implementation status

| Component     | Repo                              | Status                                      |
| ------------- | --------------------------------- | ------------------------------------------- |
| `mcp-sdk-ts`  | github.com/esperchain/mcp-sdk-ts  | **beta** (ContextAdd, Pin)                  |
| `esper-node`  | github.com/esperchain/esper-node  | `context_root` integrated into PoAI circuit |
| `indexer-ctx` | github.com/esperchain/indexer-ctx | off-chain CAR pinning + GraphQL search      |
| `ethers-mcp`  | github.com/esperchain/ethers-mcp  | TypeScript typings & wagmi hooks            |

***

#### TL;DR

* **Model Context Protocol (MCP)** makes Esperchain’s native LLM *context-aware* **and** keeps inference verifiable under zkLLM.
* Users register or reference arbitrary knowledge blobs; miners prove they used *exactly those blobs* when producing answers.
* The result is an on-chain, permissionless **knowledge commons**—fuel for agentic DeFi bots, NFT story-engines, or any future app that speaks natural language.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://esper.gitbook.io/esperchain-docs/architecture/proof-of-ai-consensus/esper-mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.