MCP tools

This is what an AI agent sees when it connects. If you are just wiring up Claude or Cursor, you do not need this page — Connect an agent is enough. This is here for when you are building against the tools directly and want the full list.

Two things worth knowing up front. Every tool here has an exact command-line twin, so anything an agent can do, you can do from the terminal too. And every tool is gated by the agent's permissions — if its token cannot do something, the tool simply is not available to it.

Transport#

terminal

canonicalwalletd mcp --token-file ~/.canonical/mcp.token

Standard MCP over stdio: initialize, tools/list, tools/call, resources/list, resources/read, plus session-local subscriptions.

Read tools (safe by default)#

Tool	Returns
wallet_get_status	Lock state, active chain, wallet presence.
wallet_get_current_principal	The calling token's identity and capabilities.
wallet_list_accounts / wallet_list_chains	Addresses / configured chains.
wallet_list_proposals / wallet_get_proposal	Proposals (with filters) / one proposal.
wallet_get_proposal_review	The frozen semantic review artifact.
wallet_compare_proposal_review	Drift diff: approved vs current.
wallet_resimulate_proposal	A fresh review, no stored state touched.
wallet_get_proposal_workflow / wallet_get_proposal_decision	Workflow record / decision options.
wallet_get_my_work	The computed inbox for this principal.
wallet_why_not_executable	Exactly what blocks execution.
wallet_decode_calldata	Plain-language decode of any calldata.
wallet_list_events / wallet_list_activity / wallet_list_audit_events	Machine stream / timeline / audit log.
wallet_list_clients / wallet_list_permissions / wallet_list_policies	Registry views.
wallet_list_contacts / wallet_list_watched_assets	Address book / watched assets.
wallet_get_manifest / wallet_inspect_policy	The generated surface / one policy.

Propose tools (need create_proposal)#

Each returns a proposal id that then waits for the human quorum.

Tool	Proposes
wallet_create_transaction_proposal	A direct transaction.
wallet_create_transaction_replacement_proposal	Replacing an executed transaction.
wallet_create_safe_proposal	A Safe multisig transaction.
wallet_create_personal_sign_proposal	An EIP-191 message signature.
wallet_create_typed_data_sign_proposal	An EIP-712 signature.
wallet_create_chain_add_proposal / wallet_create_chain_switch_proposal	Chain registry changes.
wallet_create_permission_grant_proposal / wallet_create_permission_revoke_proposal	Origin-permission changes.
wallet_create_client_register_proposal / wallet_create_client_revoke_proposal	Client-registry changes.
wallet_create_policy_change_proposal	A policy-template change.

Decide & execute tools (human / operator tokens)#

Policy decides whether a machine approval can ever count — with human_required it cannot.

Tool	What it does
wallet_approve_proposal / wallet_reject_proposal	Record a decision on the frozen review.
wallet_cancel_proposal	Withdraw a proposal.
wallet_execute_proposal	Drift re-check, sign, broadcast.
wallet_claim_proposal / wallet_release_proposal_claim	Take / drop a workflow item.
wallet_handoff_proposal	Pass to another principal.
wallet_mark_proposal_reviewed / wallet_request_proposal_changes	Record team review outcomes.

Admin tools (operator tokens)#

Wallet lifecycle and immediate mutations: wallet_create_wallet, wallet_import_mnemonic, wallet_import_private_key, wallet_unlock, wallet_lock, wallet_set_password, wallet_derive_account, wallet_reveal_backup_phrase, wallet_verify_backup_phrase, wallet_add_chain, wallet_switch_chain, wallet_register_client, wallet_revoke_client, wallet_rotate_client_token, wallet_grant_origin_permission, wallet_revoke_origin_permission, wallet_upsert_contact, wallet_remove_contact, wallet_watch_asset, wallet_sign_personal_message, wallet_sign_typed_data_v4. Same names and behavior as the CLI table.

Resources & subscriptions#

Read state as resources instead of tool calls, and subscribe for change events:

Resource	Contents
wallet://status	Live status.
wallet://accounts · wallet://chains	Addresses · chain registry.
wallet://proposals · wallet://proposal/{id}	Proposal list · one proposal.
wallet://proposal/{id}/review · .../compare-review	Frozen review · live drift diff.
wallet://proposal/{id}/workflow · .../decision	Workflow · decision options.
wallet://inbox/me	The computed inbox.
wallet://events · wallet://activity · wallet://audit	History streams.
wallet://permissions · wallet://clients · wallet://policies	Registries.
wallet://manifest	The generated surface.

Session-local subscriptions notify on change (for example proposal_review_updated, accounts_updated, status_updated) so an agent reacts to your inbox instead of polling. Subscriptions are capped per session (see docs/release/mcp-subscriptions.md).