Smart Contracts
As Agent Tools.

Start here

A protocol integration in five steps.

1. 01Choose an ENS nameUse a normalized name your protocol controls.
2. 02Describe contractsAdd lowercase aliases and deployed addresses for one EVM chain.
3. 03Declare toolsExpose read calls and write sequences with explicit inputs.
4. 04Publish two recordsWrite the manifest and its keccak256 digest to ENS text records.
5. 05Connect a generic hostCall discover(name); users approve writes in their own wallet.

Agent integrations

Install the tools for your agent.

The repository provides the same Web3MCP plugin for Claude Code and Codex. Add this repository as a marketplace, install web3mcp@evm-web3mcp, then restart the agent so the bundled MCP server, signing page, and skill are loaded.

/plugin marketplace add Team-Managed/EVM-Web3MCP
/plugin install web3mcp@evm-web3mcp

codex plugin marketplace add Team-Managed/EVM-Web3MCP
codex plugin add web3mcp@evm-web3mcp

[plugins."web3mcp@evm-web3mcp".mcp_servers.web3mcp]
default_tools_approval_mode = "writes"

Developer tools

Use the SDK. Build an agent-ready protocol.

The SDK is for hosts that want direct control over discovery and execution. The builder skill is for turning an existing contract into a checked, publishable Web3MCP manifest without handing an agent a private key.

npm install @web3mcp/evm viem

import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
import { discover, executeRead, prepareWrite } from "@web3mcp/evm";

const client = createPublicClient({ chain: sepolia, transport: http() });
const protocol = await discover(client, "agentswap.web3mcp.eth");
const quote = await executeRead(client, protocol, "quote_eth_to_usdc", { amount: "0.01" }); // such as "250.663701 USDC"
const minUsdc = (parseFloat(String(quote)) * 0.99).toFixed(6); // accept about 1% less

const wallet = "0xYourWallet";
const write = await prepareWrite(client, protocol, "eth_to_usdc", {
  amount: "0.01", min_usdc: minUsdc, recipient: wallet
}, wallet);

# Format-only validation
node <skill-folder>/scripts/web3mcp-publish.mjs validate vault.myprotocol.eth.json

# Validate against the chain and print ENS records
node <skill-folder>/scripts/web3mcp-publish.mjs check vault.myprotocol.eth.json

# Discover and verify an already-published name
node <skill-folder>/scripts/web3mcp-publish.mjs check vault.myprotocol.eth

01 / Publication

Publish one manifest to ENS.

Store two text records on the protocol's ENS name. The manifest describes every contract and tool; the digest is the keccak256 hash of the exact manifest record bytes. ENS is the source of truth, while indexes are only caches.

{
  "web3mcp": "0.1-evm",
  "chainId": 11155111,
  "name": "vault.web3mcp-demo.eth",
  "contracts": {
    "vault": "0x1111111111111111111111111111111111111111",
    "usdc": "0x2222222222222222222222222222222222222222"
  },
  "tools": [
    {
      "name": "total_assets",
      "description": "Read the vault asset balance",
      "kind": "read",
      "inputs": {},
      "call": {
        "contract": "vault",
        "function": "function totalAssets() view returns (uint256)",
        "args": []
      }
    }
  ]
}

The digest must be computed from the exact bytes stored in the manifest record. Changing whitespace or ordering changes the digest. A host rejects a mismatch before parsing or exposing tools.

02 / Manifest

Keep tools explicit and small.

A manifest contains 1–32 uniquely named tools. Names are lowercase identifiers. Every contract reference is an alias, and every argument is either a validated literal or a declared binding.

Supported input types are address, amount, ether, uint256, bool, bytes32, and string. Read tools may also declare formatted outputs or a non-view dryRun. Bindings include $input.name, $sender, and $contracts.alias.

Write tool example

Approvals and calls are one declared sequence. The host resolves bindings, validates the ABI argument count and mutability, then simulates the sequence atomically.

{
  "name": "deposit",
  "description": "Deposit tokens into the vault",
  "kind": "write",
  "inputs": {
    "amount": { "type": "amount", "token": "usdc" }
  },
  "steps": [
    { "approve": {
      "token": "usdc",
      "spender": "vault",
      "amount": "$input.amount"
    } },
    { "call": {
      "contract": "vault",
      "function": "function deposit(uint256 amount)",
      "args": ["$input.amount"]
    } }
  ]
}

03 / Discovery

Verify before exposing anything.

The host resolves ENS, checks the digest, validates the schema, confirms contract code and selectors, and records fingerprints. Unknown fields, aliases, bindings, or unsafe read calls fail discovery.

Discovery checklist

• Resolve the ENS name and read both records
• Verify the manifest digest before parsing
• Reject unknown fields and invalid references
• Confirm deployed bytecode and function selectors
• Record code fingerprints, including proxy implementations
• Label contracts Owner-verified or Name-only

04 / Execution

Simulate first. Sign last.

The host builds every write, simulates the complete sequence with eth_simulateV1, and shows decoded calls, gas, and exact balance changes. It re-checks fingerprints immediately before asking the wallet to sign.

05 / MCP

One generic host, every protocol.

The MCP server starts with discover(name) and call(tool, args). Discovered tools use <namespace>_<tool> for reads and tx_<namespace>_<tool> for writes. Descriptions are treated as untrusted publisher text.

What is implemented today?

The current SDK discovers manifests from ENS, verifies their digest and contract code, labels trust, executes reads, prepares and simulates writes, and returns a wallet signing handoff. The MCP server also reports write status. The protocol remains a draft, so use the security and limitations guidance when moving beyond the tested Sepolia flow.

06 / Security invariants

Security invariants by design.

These are the protocol guarantees and intended trust boundaries. They describe the design target; unfinished execution features remain clearly marked in the implementation status above.