Agent API & MCP Server (Concept)

Strategic sketch — operational docs on mcp-docs.feelyourprotocol.org. The execution engine and gateway tools exist; the public hosted endpoint is not launched yet. See Launch week.

What we're building

Feel Your Protocol MCP server: a headless service wrapping the EthereumJS stack so an AI agent can run exact, deterministic simulations of the future Ethereum protocol — upcoming forks, EIPs, and research — and get back not just a result, but a step-by-step trace it can reason over.

Delivery shape: primarily an MCP server over HTTP at mcp.feelyourprotocol.org — not a bare REST API, not a self-host tutorial. MCP is the agent↔tool standard: discover tools, read schemas, call without custom prompt engineering.

Live tool surface (generic verbs)

We deliberately ship intent-driven tools, not per-EIP endpoints:

MCP tool	Shape	Purpose
describe_capabilities	probe	Registry: forks, runnable EIP modules, opcodes, encoding, shapes
run_bytecode	simulate	Run caller-supplied bytecode under a fork config; optional trace
run_transaction	transaction	Paid tx gas, receipt logs, wallet gasLimit, first-touch transfers
run_block	block	1–8 txs as a lab block; optional header slot / number / timestamp
generate_artifact	generate	Lab artifacts (e.g. block-level access lists)
inspect_artifact	inspect	Structure / hash of a caller-supplied artifact

EIP coverage is advertised through the probe response and human catalogue pages under mcp-docs/use/eips/ — not separate tools like simulate_eip8024_stack. Compare baseline vs preview by calling the same verb twice (e.g. osaka then amsterdam).

Full schemas and limits: mcp-docs/use/tools/.

Design principles (still hold)

• Isolated lab / BYOS. No archive node, no mainnet or L2 sync. The caller supplies bytecode, txs, and any constructed prestate; we run in an isolated context. Default: discard that lab world after the call (so workers stay parallel). Constructing accounts/code/storage in the request is in scope. An MCP transport session is not EVM memory — continuation across prompts is optional later, not implied.
• Raw bytecode, base-layer only. No Solidity compilation in the service. ERC application-layer concerns are out of scope.
• Observability first. Rich JSON traces (stack, memory, gas, opcodes) are a primary deliverable.
• Guardrails for agents. Tool schemas and hard ceilings protect the open service. Gas-based pricing applies on the paid tier (see Pricing).

Use-case scopes (candidates)

Three scopes mapped onto the stack — v1 focuses on run under upcoming fork rules:

1. Future-fork gas & opcode simulator — run bytecode under Fusaka vs Glamsterdam; compare gas, logs, stack. Audience: DeFi engineers, MEV searchers, auditors. (8024, 7708, 7883, 7951 in catalogue today.)
2. Deep-state security tracer — return exact stack/memory at sensitive opcodes via optional trace. Audience: security auditors._
3. Block-level access lists (EIP-7928) — generate shape planned; website exploration is the textbook twin today.

Likely first users (hypothesis — to validate at launch)

Programmatic actors with urgent incentive to understand upcoming forks before mainnet: MEV searchers, DeFi/security auditors, and L2 / infra teams running automated integration tests. The website builds trust; the hosted MCP is what they allowlist.

Illustrative handler (early sketch — superseded by generic tools)

An early design explored per-EIP tool names. We rejected that in favour of generic verbs + a live catalogue. The handler shape is still instructive:

// Today: one run tool, fork config selects Glamsterdam + bundled EIPs
const common = new Common({ chain: 'mainnet', hardfork: 'amsterdam' }) // EthereumJS EL id
const result = await simulateBytecode({ bytecode, fork: { baseHardfork: 'glamsterdam' } })
// → gasUsed, stack, logs, provenance JSON back to the agent

Tech readiness & boundaries

• TypeScript is fine for this. Isolated single simulations; the LLM round-trip dominates timing. Modularity and observability matter more than raw speed.
• Concurrency via worker pool. CPU-bound sims in Node worker_threads so the network layer stays responsive. See AWS & Hosting.
• The hard wall to avoid: sequential multi-block historical backtesting. Archive-node / revm territory — outside scope and margins.

Open questions

• EIP-7928 generate — when it ships relative to launch week.
• x402 integration — after the open launch has usage and has been hardened. Facilitator, proxy, token discount check. First paid EIP expected: 8141. See Pricing.
• Registry listings — machine-readable discovery after the hosted endpoint is live. See Two Audiences.

Resolved: MCP-first delivery (not REST-primary); docs split (roadmap = strategy, mcp-docs = operational).

Changelog

Agent API Concept Changelog

1. v0.82026-10-01x402 is a post-launch question. Launch week is the open Glamsterdam endpoint.
2. v0.72026-09-24Six generic verbs (run_block, generate_artifact, inspect_artifact); registry discovery for agents.
3. v0.62026-09-14BYOS: isolated lab and demand-built prestate; MCP transport session is not EVM memory.
4. v0.52026-09-08run_bytecode + run_transaction; renamed from run_evm_bytecode.
5. v0.42026-09-02Generic MCP tools shipped (describe_capabilities, run_evm_bytecode); per-EIP tool sketch retired; public launch pending.
6. v0.32026-07-15MCP docs site live at mcp-docs.feelyourprotocol.org — this page remains the strategic sketch.
7. v0.22026-06-30Reframed as in-progress concept — no shipped API.
8. v0.12026-06-30Initial outline — MCP-first delivery, stateless/BYOS design, three use-case scopes.

Add a one-line entry here whenever the Agent API concept changes.