API reference

MCP request and response

{
  "name": "get_block_height",
  "arguments": { "chain": "n3", "network": "testnet" }
}

Tool results are returned in MCP content. Most successful tools place formatted JSON in content[0].text.

{
  "blockCount": 12346,
  "height": 12345,
  "network": "testnet"
}

blockCount is the RPC count. The latest block index is max(0, blockCount - 1).

Chain and network parameters

One tool covers both chains. Every tool that both chains implement takes a required chain discriminator; single-chain tools reject the chain they do not serve.

Node tools read live RPC on either network. Explorer analytics are backed by n3index for Neo N3 and Blockscout for Neo X; every network-capable tool pins network, while an endpoint that lacks testnet coverage rejects the request explicitly. Blockscout list endpoints are cursor-paginated, so limit and skip apply to Neo N3 explorer tools only.

Registered tools

Optional local signing tools

A locally launched stdio server with NEO_ENABLE_WRITES=true and a NEO_SIGNER_WIF_FILE registers four additional tools that sign with that owner-supplied key. They are annotated destructive and idempotent, require an idempotencyKey and an explicit network, and require the caller to accept the exact returned intent fingerprint. They never accept WIFs, private keys, or passwords as arguments.

The remote MCP HTTP transport rejects this configuration and stays read-only regardless of the setting, so a hosted server never signs on a user's behalf.

Fee estimate fields

{
  "networkFeeDatos": "10000000",
  "systemFeeDatos": "5000000",
  "networkFeeGas": "0.1",
  "systemFeeGas": "0.05"
}

The datos fields are exact integer decimal strings; the GAS fields are formatted decimal strings. Estimates are advisory: the signing wallet decides the fees it actually attaches.

Resources

Generic contract flow

On Neo N3 a contract reference can be a known name, script hash, or Neo address. Resolve and verify the reference on the selected network before calling it. Local names and descriptions are not deployment or protocol guarantees.

{
  "name": "get_contract_status",
  "arguments": {
    "chain": "n3",
    "network": "testnet",
    "contract": "0x0123456789abcdef0123456789abcdef01234567"
  }
}

Read a contract

On Neo N3 this is an invokefunction test invoke with typed args. On Neo X it is an eth_call against a checksummed 0x address.

{
  "name": "call_contract",
  "arguments": {
    "chain": "n3",
    "network": "testnet",
    "scriptHash": "0x0123456789abcdef0123456789abcdef01234567",
    "operation": "symbol",
    "args": []
  }
}

Propose a write

Writes are never executed server-side. build_contract_call returns an unsigned proposal plus the read-only simulation behind it, so a wallet can review the effect before signing.

{
  "name": "build_contract_call",
  "arguments": {
    "chain": "n3",
    "network": "testnet",
    "from": "NXV7ZhHiyM1aHXwpVsRZC6BwNFP2jghXAq",
    "scriptHash": "0x0123456789abcdef0123456789abcdef01234567",
    "operation": "transfer",
    "args": []
  }
}

HTTP transport

HTTP binds to 127.0.0.1:3000 by default and requires one Neo network. A non-loopback host requires HTTP_API_KEY; every configured key must contain at least 32 bytes.

When a key is configured, every route except GET /live and GET /health requires:

Authorization: Bearer <HTTP_API_KEY>

POST and PUT bodies must be JSON objects. HTTP_MAX_BODY_BYTES defaults to 1 MiB. HTTP_CORS_ORIGINS is an exact comma-separated origin allowlist; wildcard CORS is not supported.

Selected routes

Write intents

State-changing routes never accept a key. They require NEO_ENABLE_WRITES=true and NEO_SIGNER_WIF_FILE on the server, an Idempotency-Key header, and a network matching the one the HTTP server was started with. Any wif, privateKey, password, key, or legacy confirm field in the body is rejected with 400.

A successful reservation returns 202 with the intent, not a transaction:

{
  "intentId": "<64 hex>",
  "fingerprint": "<64 hex>",
  "state": "awaiting_approval",
  "operation": "transfer_assets",
  "network": "testnet",
  "signerAddress": "NXV7ZhHiyM1aHXwpVsRZC6BwNFP2jghXAq",
  "payload": { "toAddress": "...", "asset": "GAS", "amount": "1.5" }
}

Execution is a second, separately authorized call. The approval route uses HTTP_WRITE_APPROVAL_API_KEY instead of HTTP_API_KEY, and the body must echo the exact fingerprint returned above, so holding the read key alone can never move funds.

POST /api/write-intents/<intentId>/approve
Authorization: Bearer <HTTP_WRITE_APPROVAL_API_KEY>

{ "fingerprint": "<64 hex>" }

Replaying the same Idempotency-Key with a different payload is refused rather than silently reserving a second intent.

Errors

MCP validation errors are returned as error content with descriptive messages. HTTP responses use JSON and commonly return 400, 401, 404, 413, 415, 429, 500, 503, or 504 according to the failure.