Architecture

How the Lockstep MCP server integrates with on-chain contracts and with the Uniswap v4 MCP server.

System diagram

┌─────────────────────────────────────────────────────────────────┐
│                        AI Trading Agent                         │
│                                                                 │
│   ┌─────────────┐                         ┌─────────────────┐  │
│   │  Strategy    │──── scan / execute ────►│  MCP Clients    │  │
│   │  Engine      │◄─── opportunities  ─────│                 │  │
│   └─────────────┘                         │  ┌────────────┐ │  │
│                                           │  │ lockstep.ts│ │  │
│   ┌─────────────┐                         │  ├────────────┤ │  │
│   │  Risk       │──── position limits ───►│  │ uniswap.ts │ │  │
│   │  Manager    │                         │  └────────────┘ │  │
│   └─────────────┘                         └────────┬────────┘  │
│                                                    │ stdio     │
└────────────────────────────────────────────────────┼───────────┘
                                                     │
                    ┌────────────────────────────────┼──────────┐
                    │                                ▼          │
                    │  ┌──────────────────┐  ┌──────────────┐  │
                    │  │ Lockstep MCP     │  │ Uniswap v4   │  │
                    │  │ Server           │  │ MCP Server   │  │
                    │  │ (14 tools)       │  │              │  │
                    │  └────────┬─────────┘  └──────┬───────┘  │
                    │           │ ethers.js          │ ethers   │
                    │           ▼                    ▼          │
                    │  ┌──────────────────────────────────────┐│
                    │  │           Base (L2)                   ││
                    │  │                                       ││
                    │  │  Registry ─── Hook ─── InternalHook  ││
                    │  │  Router ──── Evaluator ── Vault      ││
                    │  │  PoolManager (Uniswap v4)            ││
                    │  └──────────────────────────────────────┘│
                    │                On-chain                   │
                    └──────────────────────────────────────────┘

On-chain reads

The Lockstep MCP server reads state from the following contracts using ethers.js:

LockstepRegistry — agent list, tiers, statuses, proposal details
LockstepHook — investor registrations, commitment state, profit-share configuration
LockstepInternalHook — internal pool access control, micro-fee rate, treasury address
LockstepRouter — optimal route computation between internal and external pools
CollateralVault — collateral balances and lock status
PerformanceEvaluator — cycle settlement results

On-chain writes

For write operations (registering agents, funding proposals, executing swaps), the MCP server constructs the transaction but does not sign it. Signing can be handled two ways:

Agent-signed — the agent holds a private key and signs locally. This is the default for the trading agent template.
Relayer — a meta-transaction relayer signs and submits. Useful for agents running in the cloud without direct key access.

Non-custodial

The MCP server never has custody of funds. All write operations require the agent or relayer to sign. The server is a read-heavy gateway with transaction construction capabilities — not a wallet.

Smart router — atomic split swaps

The LockstepRouter is the only component that can execute split swaps — routing part of a trade through an internal pool and the rest through an external pool in a single atomic transaction. This is critical because:

It prevents front-running between the two legs of the trade.
If either leg fails, the entire transaction reverts — no partial fills.
The router computes the optimal split based on current pool depths and fee structures.

Transport

The MCP server supports two transport modes:

stdio — local communication via standard input/output. Used by the trading agent template and Claude Desktop. Lowest latency.
SSE (Server-Sent Events) — remote communication over HTTP. Used for cloud-hosted agents that need to connect to a centralized MCP server.

Mock data store

When no on-chain configuration is available (no RPC URL or contract addresses), the MCP server falls back to a mock data store with realistic sample data. This is useful for:

Local development without deploying contracts
Testing agent logic before going on-chain
Demos and presentations

Error handling

Errors from on-chain calls, invalid parameters, or network issues are propagated to the client in standard MCP error format. The server distinguishes between:

Validation errors — bad parameters, missing fields, invalid addresses
Contract errors — reverts with decoded reason (e.g. NotRegisteredAgent(), InsufficientCollateral())
Network errors — RPC timeouts, chain unavailable