Build with AI Agents (MCP)

TL;DR

@asentum/mcp is a Model Context Protocol server for Asentum. Add it to your AI coding agent and the agent can read the chain, check a contract on the same VM the nodes run before anything is deployed, read these docs, and, if you give it a testnet key, deploy and call contracts. One line in Claude Code:

claude mcp add asentum -- npx -y @asentum/mcp

Reads, validation, simulation and docs need no key and no account. Writes are opt-in, testnet only by default, and the key never leaves your machine.

What MCP is

The Model Context Protocol is an open standard for plugging tools into AI apps. An MCP server is a small program that offers tools (things the agent can do), resources (documents it can read) and prompts (ready-made tasks). The AI app, called the client, starts the server or connects to it, and the model decides when to use the tools. You approve each action in the client.

@asentum/mcp runs on your machine. It talks to the public Asentum testnet RPC and explorer, runs a local copy of the contract VM, and ships a copy of these docs. It needs Node.js 18.17 or newer and nothing else.

Set it up in your client

Pick your client for step-by-step setup: where the config file lives on each OS, a read-only config, how to add a testnet key safely, how to check it is connected, and fixes for common problems.

Any other client that can start a stdio server works with command npx and arguments -y @asentum/mcp.

Safety

Without a key the server can only read and simulate, so there is nothing to lose. Once you give it a key, the agent can spend from that wallet. Five rules:

• Testnet only. Before signing, the server checks the node is testnet chain 1423 and refuses anything else. Leave ASENTUM_ALLOW_MAINNET unset.
• Use a dedicated, low-balance key. Make a fresh key just for the agent and keep only a few test ASE on it. Use a key file (ASENTUM_KEY_FILE) rather than pasting the key into a config file. Each client guide shows how.
• Start with a dry run. ASENTUM_DRY_RUN=1 signs but never submits, so you see exactly what the agent would send before anything goes out.
• Review its transactions. The agent can deploy, call contracts and send ASE from that key. Keep the client's approval prompt on for deploy_contract, call_contract and send_ase, read what it is about to send, and never put them on auto-approve. An agent that other people can message should not have a key at all.
• Never paste your main wallet key. Not into the config, not into the chat. No Asentum tool will ever ask you for it. If you need to sign with your own wallet, use build_unsigned_tx and sign elsewhere.

The key is read only when a write tool runs, signing happens in the server process on your machine, and the key is never logged, returned or put in an error. A shared HTTP server leaves the signing tools out by default: see Running it as a shared HTTP server.

What the agent can do

Every tool takes addresses as ase1... or 0x... and answers with ase1, the form people should see. Contracts store lowercase 0x hex internally; the tools convert ase1 arguments for you.

Read the chain

Build and test locally

Write (opt-in)

Docs and test ASE

Validate before you deploy

AI agents tend to write contracts for other chains. validate_contract catches that before it costs a deploy. It runs static checks, then deploys the source on a local copy of the Asentum VM, calls init and every method, and looks at what ended up in storage. It flags:

• Solidity syntax (contract X { }, pragma solidity), export / import, TypeScript types.
• A script that does not end in an object literal, or an object without its parentheses.
• this inside methods, async methods and await.
• Globals that do not exist: cron, console, Date, Math.random, fetch, setTimeout.
• Fields that read undefined: msg.block, msg.timestamp, chain.timestamp, chain.baseFee.
• An object or array stored without JSON.stringify (it reads back as '[object Object]').
• storage.get(k) + 1n, which concatenates strings, and BigInt values mixed with Numbers.
• Durations in seconds next to chain.blockTimestamp, which is in milliseconds.
• ase1 strings inside contract code, where msg.sender and E() use hex, and an unguarded init.

Each finding comes with a fix. The rules are the ones in Writing Contracts. Use simulate_call to try specific paths: a different sender, ASE attached, storage you set up, or another contract mocked behind E().

Signing transactions

The write tools are off until you set ASENTUM_KEY_FILE (recommended) or ASENTUM_PRIVATE_KEY in the server's environment. Without a key they refuse and say how to enable them.

• Testnet only. Before signing, the server checks the node is chain 1423 and refuses anything else unless ASENTUM_ALLOW_MAINNET=1.
• The key stays local. It is read only when a write tool runs, signing happens in the server process, and the key is never logged, returned or put in an error message.
• Dry run. ASENTUM_DRY_RUN=1 (or dryRun: true on a call) signs without submitting, so you can see what the agent would send.
• Use a dedicated key. Give the agent a fresh testnet wallet funded from the faucet, not the wallet you use day to day.
• Sign elsewhere. build_unsigned_tx returns the exact digest to sign with ML-DSA-65, for a hardware wallet or another process, and submit_signed_tx sends the result.

Test ASE comes from the faucet on the airdrop dashboard (see Get Test ASE). get_wallet shows the signing address to link there.

Receipts and finality

Every write returns the transaction hash and waits for the receipt, following Fast Confirmations:

• waitFor: "included" (the default) returns once the transaction is in a block, about 2.5 seconds. The receipt has finalized: false.
• waitFor: "final" keeps waiting until its block is final, a few blocks later. Only finalized: true is permanent.
• waitFor: "none" returns as soon as the node accepts it.

The result names the state (in-block, final, failed-in-block, failed-final or pending) and how long each step took. A wait that runs out is reported as still pending, not as a failure: the transaction may still land.

Docs, resources and prompts

The server ships a copy of these docs, so the agent can read them without a browser. The key guides are MCP resources:

And prompts that produce working code that follows these docs:

An example session

Ask your agent something like:

Write a tip jar contract for Asentum. Validate it, simulate a 1 ASE tip
from another address and a withdraw by the owner, then deploy it to
testnet and show me the receipt.

A typical run:

1. The agent reads asentum://guide/contract-cheatsheet and writes the contract.
2. validate_contract reports, say, storage.get('total') + msg.value as string concatenation, with the fix. The agent fixes it and validates again.
3. simulate_call runs tip with valueAse: "1" from a second address, then withdraw as the owner, and shows the storage writes and the outbound transfer.
4. deploy_contract deploys it and sends init, then returns the ase1 contract address and both receipts.
5. view_call reads getTotal for free.

Other things to ask:

• "Is the Asentum testnet healthy? How far behind the tip is finality?"
• "What methods does ase1v0myp2de3dhj3crvkhxqlnjaw2mvp64a9efkpl have? Read pool 3."
• "Build a Next.js frontend for my counter contract at ase1..."
• "Schedule my contract's tick method every hour."

Environment variables

Troubleshooting

• Client-specific problems. Each client guide above has its own troubleshooting list: config file locations, logs, restarts and Windows quirks.
• The tools do not show up. Check node --version is 18.17 or newer and that npx -y @asentum/mcp --version prints a version. In Claude Code, claude mcp list shows whether the server started.
• Writes refuse. The key is missing, ASENTUM_DISABLE_WRITES is set, or the RPC is not testnet 1423. get_wallet says which.
• "insufficient balance for value plus gas". The signing wallet needs test ASE: get_testnet_ase.
• An old transaction is not found. Public nodes keep recent history only. list_address_txs reads the explorer index, which has everything.
• HTTP 429. The public gateway allows about 25 requests a second per IP. For heavy use, point ASENTUM_RPC_URL at your own node (see Run Your Own RPC).