Skip to content

@ic-reactor/mcp

@ic-reactor/mcp is an MCP server that gives an AI agent any Internet Computer canister’s methods as tools. Name a canister, and Claude Code, Cursor or any other MCP client gets one tool per method, with an input schema built from the canister’s Candid. Queries run at once. An update is sent only after you approve that exact call in the client.

The canister’s interface is read from its certified candid:service metadata and compiled with @meantjs/cli, the arguments and replies are checked and encoded by @meantjs/schema, and calls go through an @ic-reactor/core client, which verifies every certificate and says whether a failed write may have run.

Terminal window
npm install --global @ic-reactor/mcp

It installs one command, ic-reactor-mcp, and has nothing to import. A global install keeps the version you installed until you update it.

Node >=22.12.0, as core and react.

Claude Code, for the ICP ledger:

Terminal window
claude mcp add icp -- ic-reactor-mcp --canister ledger=ryjl3-tyaaa-aaaaa-aaaba-cai

Cursor (.cursor/mcp.json) and other clients that take a JSON entry:

{
"mcpServers": {
"icp": {
"command": "ic-reactor-mcp",
"args": ["--canister", "ledger=ryjl3-tyaaa-aaaaa-aaaba-cai"]
}
}
}

Without --identity the server calls as the anonymous principal: every query works and no update is sent. To send updates, give it a key (see A key).

Tool What it does
whoami The principal calls are signed as, the network, whether the client can show the approval form, the listed canisters
list_methods A canister’s methods and their Candid signatures, where the interface came from, and whether updates can be sent
describe_method One method’s Candid (the method and every type it uses), its doc comment, and the JSON Schema of its arguments
query Runs a query method of any canister; certified: true makes it a replicated call, as the anonymous principal, with a certified reply
call Sends an update to a listed canister once you approve it; a query method is run as a query
<name>_<method> One per method of each --canister, such as ledger_icrc1_transfer, with the method’s own input schema

call and the update tools are listed only when an update can be sent: the server has a key, the client can show a form, and a canister is listed.

Tool arguments and replies are JSON. A nat, int, nat64 or int64 is a decimal string such as "150000000", a blob is lower-case hex, an opt is null or the value, and a variant is { "tag": "Name", "value": payload }. The package’s README has every Candid type’s JSON form.

An update (or a oneway call) is sent only when all of these hold, and a refusal says which one did not:

  1. The server has a key: --identity <pem file>.
  2. The canister is listed with --canister. Queries reach any canister, updates only the ones you named.
  3. Its interface is certified metadata, or a .did you gave with --did. An interface read through the uncertified __get_candid_interface_tmp_hack query is used for reads only: it is one replica’s unproven answer.
  4. The client can show a form (MCP form elicitation), and you tick “Send this call” and accept.

The form shows the canister, the method, the principal that signs, the network, the arguments as Candid text (with invisible and bidirectional characters escaped), the size and sha256 of the encoded arguments, and where the interface came from. Arguments over 20,000 characters of Candid, or a method name over 200 characters, are refused, never cut. The server confirms the canister’s module hash before it asks you and again after you approve, and sends nothing if the canister was upgraded in between. Declining, closing the form, ten minutes without an answer, or a client error all mean nothing is sent. One approval is asked at a time.

A certified read (query with certified: true) is a replicated call, which the IC runs as whatever the canister’s module exports under that name. So it is made as the anonymous principal, never with your key, and its reply is read with the interface of the module installed now.

Claude Code shows the form in a dialog. claude -p cancels every form unless an Elicitation hook answers it, so a headless run sends no update unless you wrote a hook that approves.

--identity <file> takes an Ed25519 or secp256k1 private key in PEM form, such as icp identity export <name> or dfx identity export <name> prints. The file must be readable by its owner only (chmod 600); the server refuses one that other users can read. The server never makes a key. Give the agent a key of its own, holding only what you would let it spend.

--canister <name>=<id> A canister that gets typed tools and takes updates,
such as ledger=ryjl3-tyaaa-aaaaa-aaaba-cai. A bare
<id> is named after its first five characters.
--did <name or id>=<path> Read that canister's interface from this .did file
instead of the network.
--identity <pem file> Sign calls with this key (chmod 600).
--network <ic|local|url> ic (mainnet, the default), local
(http://127.0.0.1:8000), or a replica's URL.
--root-key <hex> The root key (DER, hex) of a --network <url> that
is not on this machine.

A root key is fetched only from a replica on this machine. Mainnet’s key is built into the agent, and a remote replica’s must be given with --root-key.

  • A .did over 256 KiB, a service with more than 1,000 methods, or a compile over 2 seconds is refused; the compiler runs in a worker thread.
  • A tool’s input schema is cut at about 64,000 characters, names and descriptions included, and says it was cut. The typed tools of one tools/list stop at 1,000,000 characters; query and call still reach a method past that.
  • A tool result is cut at 60,000 characters, with a note that it was cut.
  • A read waits 60 seconds for its answer, and an approved update 6 minutes; an update that gets no answer in time may still have run, and its result says so.

Names in a canister’s interface (methods, fields, types) are the canister’s own text and reach the model in tool names, descriptions and schemas. A method’s doc comment, which is free text, appears only in describe_method’s result, labelled as written by the canister’s authors, and never in a tool description. The form is the safeguard for writes: an agent misled by such text can still only propose a call, and you read the call itself before it is sent.