Asentum MCP in Claude Desktop

Prerequisites

• Node.js 18.17 or newer. Check with node --version. The current LTS release from nodejs.org is a good choice.
• Claude Desktop, the latest version (Claude menu, Check for Updates).
• 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.

Find the config file

Claude Desktop reads local MCP servers from claude_desktop_config.json. The easy way to open it: in the Claude menu (the menu bar on macOS, not the settings inside a chat), choose Settings, go to the Developer tab and click Edit Config. That creates the file if it does not exist yet.

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

Add the server

1. Open the config file as above.
2. Add asentum under mcpServers. If the file already has other servers, add it next to them, inside the same mcpServers object.
3. Save the file.
4. Quit Claude Desktop completely (on macOS, Claude menu then Quit, or Cmd+Q; on Windows, quit it from the tray icon too) and open it again. Closing the window is not enough.

Read-only setup: chain reads, contract validation and simulation, and the docs.

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

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.

Recommended: a key file

{
  "mcpServers": {
    "asentum": {
      "command": "npx",
      "args": ["-y", "@asentum/mcp"],
      "env": {
        "ASENTUM_KEY_FILE": "/Users/you/.asentum-mcp/testnet.key",
        "ASENTUM_DRY_RUN": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "asentum": {
      "command": "npx",
      "args": ["-y", "@asentum/mcp"],
      "env": {
        "ASENTUM_KEY_FILE": "C:\\Users\\you\\.asentum-mcp\\testnet.key",
        "ASENTUM_DRY_RUN": "1"
      }
    }
  }
}

Delete the ASENTUM_DRY_RUN line when you want transactions to really go out, then restart Claude Desktop again. Every change to this file needs a full restart.

Alternative: an inline key

Works, but the key then sits in plain text in the config file. Only ever a dedicated testnet key:

{
  "mcpServers": {
    "asentum": {
      "command": "npx",
      "args": ["-y", "@asentum/mcp"],
      "env": {
        "ASENTUM_PRIVATE_KEY": "<64 hex character testnet seed>"
      }
    }
  }
}

Claude Desktop asks before it runs a tool. Read the request for deploy_contract, call_contract and send_ase before you allow it, and do not choose always allow for those three.

Check it is connected

After the restart, click the + button ("Add files, connectors, and more") at the bottom left of the message box, hover Connectors and click Manage connectors. asentum should be in the list, and clicking it shows its tools.

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.

Claude Desktop cannot read your project folder by itself. For "validate my contract", paste the contract into the chat, or use Claude Code or Cursor for work inside a repo.

Troubleshooting

• asentum is not in the connector list. Quit Claude Desktop fully and reopen it. Then check the JSON is valid: a missing comma between two servers is the most common cause. Paste the file into any JSON validator if unsure.
• Read the logs. mcp.log has general connection errors and mcp-server-asentum.log has the server's own output, including the ready on stdio line.

  macOS

  tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

  Windows

  type "%APPDATA%\Claude\logs\mcp*.log"

• "spawn npx ENOENT". Claude Desktop cannot find npx. Use its full path as the command (see the note above).
• ENOENT with ${APPDATA} in the path (Windows). Add your expanded APPDATA folder to env, for example "APPDATA": "C:\\Users\\you\\AppData\\Roaming\\", and make sure npm is installed globally (npm install -g npm).
• Key file errors. On Windows, every backslash in the path must be doubled in JSON, or use forward slashes: "C:/Users/you/.asentum-mcp/testnet.key".
• "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.