# AI agents (MCP)

> Connect AI assistants to NeuroChain with the neurochain-mcp Model Context Protocol server — setup for Claude Code and Claude Desktop, every read and write tool, session-key signing, spend limits and Sentinel holds.

Source: https://docs.nro.world/build/mcp

`neurochain-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) 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](/ai/account-abstraction#session-keys).
- A session key cannot manage the Sentinel trust list or confirm a held transfer. If [Sentinel](/ai/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

```bash
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:

```json
{
  "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:**

```bash
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`:

```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.