@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.
Install
Section titled “Install”npm install --global @ic-reactor/mcpIt 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.
Add it to a client
Section titled “Add it to a client”Claude Code, for the ICP ledger:
claude mcp add icp -- ic-reactor-mcp --canister ledger=ryjl3-tyaaa-aaaaa-aaaba-caiCursor (.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.
Updates and approval
Section titled “Updates and approval”An update (or a oneway call) is sent only when all of these hold, and a refusal says which one did not:
- The server has a key:
--identity <pem file>. - The canister is listed with
--canister. Queries reach any canister, updates only the ones you named. - Its interface is certified metadata, or a
.didyou gave with--did. An interface read through the uncertified__get_candid_interface_tmp_hackquery is used for reads only: it is one replica’s unproven answer. - 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.
Options
Section titled “Options”--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.
Limits
Section titled “Limits”- A
.didover 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/liststop at 1,000,000 characters;queryandcallstill 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.
What the agent sees
Section titled “What the agent sees”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.
Read next
Section titled “Read next”- Give an agent a canister’s tools: a ledger’s tools
written by hand with
@ic-reactor/core, with amounts as decimal text and a transfer that never pays twice. - Errors and mayHaveExecuted: what a failed write tells you about whether it ran.
- @ic-reactor/core: the client the server calls through.