AI agents (MCP)

neurochain-mcp is a Model Context Protocol server. It lets an AI assistant — Claude Code, Claude Desktop or any MCP client — read the chain and, within limits you set, act on it.

AI assistant ⇄ (MCP over stdio) ⇄ neurochain-mcp ⇄ (HTTP) ⇄ gateway :3000 ⇄ node :9933

The server is plain Node.js in neurochain-mcp/ of the repository (no build step). It only talks to the gateway's REST API.

How it stays safe

• Writes are signed with a session key, never your wallet's master key. The key is granted by your master key with a scope, a spend cap and an expiry, and every validator enforces those in consensus — see Account abstraction → Session keys.
• A session key cannot manage the Sentinel trust list or confirm a held transfer. If Sentinel holds a risky transfer, only you can let it through.
• Staking, delegation and governance voting are not exposed to agents.
• Without a session key the server runs read-only.

Setup

1. Install

cd neurochain-mcp
npm install

2. Create a session key and the config

In the web wallet, open the Agent panel, create a session key — choose the addresses it may send to (or *), a total spend cap and how many blocks it stays valid — and click Export config. You get:

{
  "node_rpc": "http://localhost:3000",
  "account": "neuro:<15 hex>.human",
  "session_pk": "<session public key, hex>",
  "sk_seed_hex": "<session key seed, hex>",
  "scope": "*"
}

Field	Meaning
node_rpc	The gateway URL (not the node's 9933 port). The wallet fills in the page's own address; change it if the gateway runs elsewhere
account	The address the agent acts for
session_pk, sk_seed_hex	The session key. Leave both empty for read-only
scope	For your reference only — the grant on chain is what is enforced

Save it outside the repository and keep it private: sk_seed_hex is a secret.

3. Register the server

Claude Code:

claude mcp add neurochain \
  --env NEUROCHAIN_MCP_CONFIG=/absolute/path/to/neurochain-mcp.config.json \
  -- node /absolute/path/to/neurochain-mcp/src/index.js

Claude Desktop (claude_desktop_config.json) or a project's .mcp.json:

{
  "mcpServers": {
    "neurochain": {
      "command": "node",
      "args": ["/absolute/path/to/neurochain-mcp/src/index.js"],
      "env": { "NEUROCHAIN_MCP_CONFIG": "/absolute/path/to/neurochain-mcp.config.json" }
    }
  }
}

Use absolute paths: the client starts the server from its own working directory.

Tools

Read

Tool	Parameters	Returns
nc_get_account	address (default: the configured account)	Balance, nonce, transaction count
nc_get_txs	address, limit (1–200)	Transaction history
nc_gas_estimate	—	Base fee and fee estimates
nc_list_proposals	status, limit (1–100), offset	Governance proposals with tallies
nc_list_validators	—	Validators with stake and metrics
nc_get_contract	address (a .app)	Owner, code hash, security score
nc_analyze_contract	bytecode_hex	VMGuardian analysis — risk, violations
nc_get_session_grants	address	Session keys of the account, with cap and amount spent
nc_get_held	address	Transfers held by Sentinel

Write (session key required)

Tool	Parameters	Notes
nc_transfer	to, amount_nro (NRO, decimals allowed)	If Sentinel holds it, the tool says whether it releases automatically or needs your confirmation
nc_call_contract	to (a .app), function, args, value (uNRO, default 0)
nc_deploy	bytecode_hex, name, description, template, init_args	Goes through the VMGuardian gate like any deploy

Each write reads the next nonce, signs with the session key and posts to POST /api/v1/transactions. The node checks the grant on every validator; for example, a transfer beyond the cap comes back as:

Error: POST /api/v1/transactions failed: HTTP 401 — session spend cap exceeded

Tested

On a local test network: the read tools return live data; nc_transfer of 1 NRO with a session key capped at 5 NRO was confirmed and recorded as spent: 1000000 on the grant; a following 10 NRO transfer was refused with the error above; with no session key configured, write tools refuse without signing.

Revoking

Revoke the key from the wallet's Agent panel, or with POST /api/v1/session/revoke signed by your master key. From the next block on, everything signed with it is refused.