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:

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.

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

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

Scripts

License

MIT