Asentum MCP in Cursor

Prerequisites

• Node.js 18.17 or newer. Check with node --version. The current LTS release from nodejs.org is a good choice.
• Cursor, a recent version. MCP tools are used by the Agent in chat.
• 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.

Global or project config

Cursor reads MCP servers from an mcp.json file in one of two places:

• Global: ~/.cursor/mcp.json in your home folder (on Windows, %USERPROFILE%\.cursor\mcp.json). The server is there in every project.
• Project: .cursor/mcp.json in the project root. Only that project, and you can commit it so your team gets it too.

Create the file if it does not exist. Both use the same format.

Add the server

1. Open (or create) ~/.cursor/mcp.json or .cursor/mcp.json.
2. Add asentum under mcpServers, next to any servers already there.
3. Save. Cursor picks up the change; if the server does not appear, reload the window (Command Palette, Developer: Reload Window).
4. Make sure the server is switched on in the MCP list (see below).

Read-only setup, safe to commit in a project:

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

You can also manage servers in the app: open Customize in the sidebar to see your MCP servers and switch them on or off without editing the file. In older Cursor versions this lives under Cursor Settings, MCP (or Tools & MCP), where Add new MCP server opens the same mcp.json.

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, in the global config

Put a server with a key in ~/.cursor/mcp.json, not in a project file you might commit. Cursor expands ${userHome}, so the same file works on every OS:

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

Remove ASENTUM_DRY_RUN when you want transactions to really go out.

In a shared project file

If the server lives in a committed .cursor/mcp.json, read the path from each person's environment instead of writing it in the file:

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

Alternative: an inline key

Works, but the key sits in plain text in the file. Global config only, testnet key only:

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

Cursor asks before running an MCP tool by default. Keep it that way for deploy_contract, call_contract and send_ase: do not add them to an auto-run allowlist.

Check it is connected

Open Customize (or Cursor Settings, MCP in older versions). asentum should be listed, switched on, with a green status and its tools. Then open a chat in Agent mode.

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.

Troubleshooting

• Read the MCP logs. Open the Output panel (Cmd+Shift+U on macOS, Ctrl+Shift+U on Windows and Linux) and pick MCP Logs from the dropdown. Startup errors, a bad path and crashes show up there.
• The server shows red or no tools. Check the JSON is valid (a missing comma is the usual cause), then switch the server off and on again, or reload the window.
• The agent does not use the tools. Make sure you are in Agent mode and the server is switched on. Asking by name helps: "use the asentum tools to ...".
• Too many tools. Cursor may limit how many tools it sends to the model at once. Switch off servers you are not using.
• ${env:ASENTUM_KEY_FILE} is empty. Cursor only sees variables from the environment it was started in. On macOS, start it from a terminal (cursor .) or use the global config with ${userHome}.
• "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.