IntentGuard MCP Server

Includes a full end-to-end agent simulation test runnable locally in dry-run mode (no chain required).

A Model Context Protocol server that gives AI agents the ability to submit Ethereum transactions with on-chain outcome protection.

IntentGuard wraps any DeFi transaction with two enforcement transactions. If the declared balance constraints are violated at execution time, the transaction is dropped before inclusion — and no gas is consumed.

---

Architecture

The MCP server has a single, well-defined role: it builds the two protective transactions and validates the signed bundle before submission. It does not build or inspect the underlying DeFi transaction.

Protocol skill / wallet  →  builds the action transaction
IntentGuard agent skill  →  extracts and confirms protection constraints
IntentGuard MCP          →  compiles protection package, validates and submits
On-chain enforcer        →  allows or rejects execution

The MCP exposes exactly two tools:

Tool	Role
prepare_protected_transaction	Compiler — produces two unsigned enforcement transactions and a nonce layout
submit_protected_bundle	Submitter — validates the signed bundle (pre + action + post) and submits to the relay

---

Prerequisites

• Node.js >= 22
• Access to the IntentGuard relay (default: https://sepolia.rpc.intentguard.xyz)

---

Install & Build

npm install
npm run build

The compiled entrypoint is dist/index.js. It includes a #!/usr/bin/env node shebang and is executable.

---

Configuration

The server is configured entirely via environment variables.

Variable	Required	Default	Description
INTENTGUARD_CHAIN_ID	yes	—	EVM chain ID (e.g. 11155111 for Sepolia, 1 for mainnet)
INTENTGUARD_RPC_URL	no	https://sepolia.rpc.intentguard.xyz	IntentGuard relay endpoint
INTENTGUARD_ENFORCER_TYPE	no	balance	Enforcer contract type

The enforcer contract address is resolved automatically from the relay — no contract address configuration is required.

---

Connecting to an Agent

Add the server to your agent's MCP configuration. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "intentguard": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "INTENTGUARD_CHAIN_ID": "11155111"
      }
    }
  }
}

The agent spawns the server as a subprocess over stdio. No port or hosting is required.

---

Tools

prepare_protected_transaction

Produces two unsigned enforcement transactions that wrap a given action transaction.

Does not receive or build the action transaction. The action transaction is constructed upstream by the wallet or protocol skill.

Input:

• userAddress — wallet address that will sign all three transactions
• protectionIntent — structured protections:
  • max_spend — cap outflow of a token
  • min_receive — guarantee minimum inflow of a token
  • no_balance_decrease — ensure balance does not decrease
• validUntilBlock (optional) — protection expiry block; defaults to current block + 10

Output:

• preTx — unsigned pre-enforcement transaction (nonce N)
• postTx — unsigned post-enforcement transaction (nonce N+2)
• nonceLayout — { pre: N, action: N+1, post: N+2 }
• summary — human-readable protection list and signing instructions

The caller assigns nonceLayout.action to the action transaction and signs all three.

---

submit_protected_bundle

Validates and submits a fully signed bundle of three transactions.

Input:

• signedPreTx — signed pre-enforcement transaction (nonce N)
• signedUserTx — signed action transaction (nonce N+1, built externally)
• signedPostTx — signed post-enforcement transaction (nonce N+2)
• retryUntilBlock (optional) — retry deadline; defaults to current block + 25

Pre-submission validation (failures returned immediately, no submission attempt):

1. All three transactions are EIP-1559 (type 2)
2. All three are signed by the same address
3. Nonces are strictly sequential: N, N+1, N+2
4. All three target the same chain ID

Return:

• Constraints satisfied → transaction hash, signer, confirmed nonce layout
• Constraints violated → bundle dropped, no gas paid

Returns the final bundle outcome directly. No separate receipt polling is required.

---

Testing

npm test

The test suite covers:

• Nonce layout assignment and boundary cases
• Output shape — action transaction is never returned by the MCP
• Default block window behaviour
• All protection types (max_spend, min_receive, no_balance_decrease)
• Input schema validation
• Bundle validation (nonce ordering, signer consistency, chain ID consistency)
• Error paths (network failures, SDK errors, malformed inputs)
• Full end-to-end flow: prepare → sign → submit

---

End-to-end test (agent simulation)

This repository includes a full end-to-end test that simulates an AI agent using IntentGuard over the MCP protocol.

The script:

• launches the MCP server as a subprocess (stdio transport, exactly as Claude / Cursor do)
• connects as an MCP client
• calls prepare_protected_transaction
• assigns nonce N+1 to the action transaction (built externally, never passed to MCP)
• signs all three transactions (preTx, actionTx, postTx)
• optionally submits the bundle

Run locally — no chain required

INTENTGUARD_CHAIN_ID=11155111 npm run agent-e2e:dry

Verifies: MCP connectivity over stdio, nonce assignment (N, N+1, N+2), bundle construction, and transaction signing. The relay is contacted for nonce and block number but no transaction is submitted.

Full execution (Sepolia)

INTENTGUARD_CHAIN_ID=11155111 TEST_PRIVATE_KEY=0x... npm run agent-e2e

Requires a funded Sepolia wallet. Submits the signed bundle to the relay.

What this test simulates

Role	Responsibility
Upstream builder	constructs the action transaction and assigns nonce N+1
IntentGuard agent	calls prepare_protected_transaction
Signing agent	signs all three transactions
Orchestrator	assembles and submits the bundle
MCP server	validates and submits

This is a full protocol-level test of the IntentGuard execution flow.

---

Scripts

Script	Description
npm run build	Compile to dist/
npm run dev	Run directly from source with tsx
npm test	Run the test suite
npm run typecheck	TypeScript type check without emit
npm run agent-e2e:dry	Full agent simulation, dry-run (no submission)
npm run agent-e2e	Full agent simulation with bundle submission (Sepolia)

---

License

MIT