Asentum MCP in Claude Code

Prerequisites

• Node.js 18.17 or newer. Check with node --version. The current LTS release from nodejs.org is a good choice.
• Claude Code installed and signed in. Check with claude --version.
• No account and no key for reads, contract validation, simulation and docs. A key is only needed if you want the agent to send testnet transactions.

Check the package runs before you wire it into a client:

npx -y @asentum/mcp --version

It should print a version such as 0.1.0. The first run downloads the package, which takes a few seconds.

Install

Run this in a terminal, in the folder of the project you want to use it in:

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

Everything after -- is the command Claude Code starts. This is a read-only setup: chain reads, contract validation and simulation, and the docs. Start a new Claude Code session (or restart the current one) to load it.

Useful commands to manage it later:

claude mcp list            # every server and whether it connected
claude mcp get asentum     # the command, scope and env for this one
claude mcp remove asentum  # remove it (add -s user or -s project if needed)

Scopes

The -s (or --scope) flag decides where the server is saved and who gets it:

# just this project, just you (the default)
claude mcp add asentum -- npx -y @asentum/mcp

# every project on your machine
claude mcp add -s user asentum -- npx -y @asentum/mcp

# shared with the team through .mcp.json
claude mcp add -s project asentum -- npx -y @asentum/mcp

If the same name exists in more than one scope, local wins over project, and project over user.

Share it with .mcp.json

A project-scoped server lives in .mcp.json at the root of the repo. You can write it by hand. The read-only version is safe to commit:

{
  "mcpServers": {
    "asentum": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@asentum/mcp"]
    }
  }
}

Claude Code asks each person to approve a project server the first time it sees it. To review that choice later, run claude mcp reset-project-choices.

Never commit a key. If teammates should be able to sign, let each person supply their own key file through an environment variable. Claude Code expands ${VAR} in .mcp.json, and ${VAR:-default} falls back to a default:

{
  "mcpServers": {
    "asentum": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@asentum/mcp"],
      "env": {
        "ASENTUM_KEY_FILE": "${ASENTUM_KEY_FILE:-}"
      }
    }
  }
}

Each person then sets ASENTUM_KEY_FILE in their own shell (for example in ~/.zshrc) before starting claude. Without it, the value is empty and the server stays read-only.

Enable writes with a testnet key

Writes (deploy_contract, call_contract, send_ase) need a signing key. Give the agent its own testnet wallet, not the one you use day to day. The safest way is a key file: the key never appears in the client's config, in your shell history or in a screenshot of your settings.

1. Create a fresh testnet key. This writes a random 32-byte seed to .asentum-mcp/testnet.key in your home folder, readable only by you, and prints the full path. It refuses to overwrite a key that is already there. Works in macOS and Linux terminals, PowerShell and Command Prompt:

node -e "const fs=require('fs'),path=require('path'),dir=path.join(require('os').homedir(),'.asentum-mcp'),f=path.join(dir,'testnet.key');fs.mkdirSync(dir,{recursive:true});fs.writeFileSync(f,require('crypto').randomBytes(32).toString('hex'),{mode:0o600,flag:'wx'});console.log(f)"

You can also use the 64 hex character seed of a new account you made in the Asentum browser extension: save it as the only content of that file instead.

2. Point the server at it with ASENTUM_KEY_FILE, using the full path the command printed (snippets below). An absolute path is safest; a leading ~/ also works.

3. Fund it with a little test ASE. Ask the agent "Show my Asentum wallet". get_wallet prints the ase1 address. Send it a few test ASE from your usual testnet wallet, or use the faucet (see Get Test ASE). A few ASE is plenty for deploys and calls.

Prefer not to use a file? ASENTUM_PRIVATE_KEY takes the 64 hex character seed directly. It works the same way, but the key then sits in plain text in the client's config file, so the key file is the better choice. If both are set, ASENTUM_PRIVATE_KEY wins.

Env vars go in with -e KEY=value, after the server name and before --. If you already added the read-only server under the same name, remove it first:

claude mcp remove asentum

# recommended: a key file
claude mcp add asentum \
  -e ASENTUM_KEY_FILE=/Users/you/.asentum-mcp/testnet.key \
  -- npx -y @asentum/mcp

# the same, but sign without submitting while you try it out
claude mcp add asentum \
  -e ASENTUM_KEY_FILE=/Users/you/.asentum-mcp/testnet.key \
  -e ASENTUM_DRY_RUN=1 \
  -- npx -y @asentum/mcp

Keep a server with a key in the local or user scope, which live in your own ~/.claude.json. Do not put it in the project scope with a literal path or key, because .mcp.json gets committed.

Claude Code asks before each tool call unless you allow it. Leave deploy_contract, call_contract and send_ase on ask, so you see every transaction before it is signed.

Check it is connected

In a Claude Code session, type /mcp. You should see asentum listed as connected, and you can open it to see its tools. From a terminal, claude mcp list shows the same.

Then ask, in plain words:

What's the Asentum chain status?

The agent should call get_chain_status and answer with chain id 1423, the finalized and tip heights, how many blocks finality is behind, and the recent block time. If it answers from memory instead, it has not loaded the tools: see Troubleshooting below.

With a key configured, also ask "Show my Asentum wallet". get_wallet should report writesEnabled: true, the ase1 address and its balance (and dryRun: true if you set it). It never shows the key.

Example prompts

Some things to try once it is connected. Replace the ase1 address and the hash with your own.

Deploy an ARC-20 token

Create an ARC-20 token called Demo (DMO) with 1,000,000 supply and
18 decimals. Validate it, simulate a transfer, then deploy it to the
Asentum testnet and show me the token's ase1 address and receipts.

Uses the create_arc20_token prompt, validate_contract, simulate_call and, with a key, deploy_contract.

Validate my contract

Validate the Asentum contract in contracts/counter.js and fix anything
it flags. Then simulate increment() from two different senders and
show me what ends up in storage.

Runs on a local copy of the VM the nodes use. Nothing touches the chain and no key is needed.

Build a dapp frontend

Build a Next.js frontend for my contract at
ase1v0myp2de3dhj3crvkhxqlnjaw2mvp64a9efkpl with @asentum/connect:
a connect button, free reads of its view methods, and signed writes
that show "in block" and then "final".

Uses the build_dapp_frontend prompt, get_contract for the real method names and the wallet connect docs.

Check a transaction's finality

Is Asentum transaction 0x<transaction hash> final yet? Wait until
it is, then tell me what it did and which events it emitted.

Uses get_receipt with waitFor: "final" and get_transaction to decode it.

You can also run the server's prompts directly. They show up as slash commands, for example /mcp__asentum__create_arc20_token.

Troubleshooting

• /mcp shows asentum as failed. Run the command by hand to see the error: npx -y @asentum/mcp. It should print asentum-mcp 0.1.0 ready on stdio and then wait (press Ctrl+C to stop). claude --debug also logs MCP startup errors.
• It connects slowly the first time. npx is downloading the package. If it times out, start Claude Code with a longer limit, for example MCP_TIMEOUT=30000 claude, or install it once with npm install -g @asentum/mcp and use asentum-mcp as the command.
• The server is not there in another folder. The default scope is local, which is per project. Add it with -s user to have it everywhere.
• "error: unknown option" or the name gets swallowed. Put the name right after add, the -e flags after the name, and the command after --, exactly as shown above.
• Project server never loads. You may have declined it at the prompt. Run claude mcp reset-project-choices and start Claude Code again.
• "npx: command not found" or an old Node. Install Node.js 18.17 or newer and open a new terminal. If you use nvm, fnm or Volta, a GUI app may not see that Node: use the full path to npx (from which npx on macOS and Linux, where npx on Windows) as the command.
• Writes refuse. No key is configured, the key file path is wrong, ASENTUM_DISABLE_WRITES is set, or the RPC is not testnet 1423. Ask the agent to run get_wallet: it says which.
• "insufficient balance for value plus gas". The agent's wallet needs test ASE. See Get Test ASE.
• HTTP 429 from the chain. 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).

More on the tools, safety and environment variables in the MCP overview.