Tool reference

Tools fall into four groups. Core and application tools are always registered; blobs and governance are toolsets that can be trimmed with CALIMERO_MCP_TOOLSETS.

Note

These are the server-side names. An MCP client may expose them under a prefix of its own — commonly mcp__<server>__<tool>, so node_status becomes mcp__mero-mcp__node_status.

Read-only tools are annotated readOnlyHint; destructive ones destructiveHint.

Core

Always registered, regardless of CALIMERO_MCP_TOOLSETS.

node_status

Health and identity of the connected node. No arguments. Read-only.

Returns node health, the url and nodeName in use, the discoverySource, and the authMode. nodeName is null when nothing on this machine names the node.

A node that was unreachable at connect is not an error until a tool needs it, so this is usually the first call to report it, which makes it the right first call of a session.

list_nodes

Nodes known on this machine, merged with a live local probe. No arguments. Read-only.

Each entry is { url, name, active }. name is null for a node found only by probe. active: true marks the one this session is using.

list_applications

Applications installed on this node, one compact row each. Read-only.

Argument	Type	Notes
verbose	boolean, optional	Return the full records instead: decoded metadata (icon included), blob hashes, signer and appVersion

Each row is { id, package, name, version, description, hasGuide, procedures }. description is cut at 200 characters. procedures holds the ### titles under ## Procedures in the app’s guide, or [] when it ships none. The guide itself is left out; describe_app returns it.

list_namespaces

Namespaces on this node. No arguments. Read-only.

list_contexts

Contexts on this node. Read-only.

Argument	Type	Notes
application	string, optional	Filter to one application: id, package name, trailing segment, or display name
verbose	boolean, optional	Also return contextStateHash and dagHeads (rendered as hex)

create_context

Create a context for an application in a group: a namespace, or a subgroup inside one.

Argument	Type	Notes
application	string	Id, package name, unambiguous trailing segment, or display name
group	string, required unless namespace is given	Namespace or subgroup id to create the context in
namespace	string, optional	Older name for group, still accepted; passing both with different values is an error
name	string, optional
service	string, optional	Required for a multi-service application
args	object, optional	Arguments for the app’s init, keyed by parameter name; checked against the ABI like a method call

args is checked against the app’s init before anything is created, and may be left out only when init takes no required parameters. A missing, invalid or undeclared argument returns isError: true naming each one, followed by the init signature and its parameter docs. When args is left out and the app’s ABI cannot be read, the context is created with no init input and the node reports any init failure; args that cannot be checked are refused.

join_context

Join a context this node is not yet a member of. Takes context. Returns { contextId, memberPublicKey }.

delete_context

Delete a context and its data. Destructive.

Argument	Type	Notes
context	string	Context id or alias

Also the fix for a context stranded by deleting its namespace first — those contexts outlive the namespace and stay uncallable until removed.

create_alias

Create a human-friendly alias for a context id.

Argument	Type
alias	string
contextId	string

lookup_alias

Resolve a context alias to its id. Read-only.

Argument	Type
name	string

A miss returns No alias named "…" on this node. as a result, not an error.

Blobs

In CALIMERO_MCP_TOOLSETS by default. Application bytecode is a blob, which is why install/uninstall live here.

install_application

Install a published application from the node’s own configured registry, by package@version coordinates.

Argument	Type	Notes
coords	string	package@version, e.g. com.example.myapp@1.0.0

uninstall_application

Destructive. Takes application (id, package name, trailing segment, or display name), resolved to one installed application before anything is removed.

upload_blob

Argument	Type	Notes
data	string	Base64-encoded blob bytes
hash	string, optional
context	string, optional	Scope the blob to a context

list_blobs

Blobs stored on this node. No arguments. Read-only.

delete_blob

Destructive. Takes blob (blob id).

Governance

In CALIMERO_MCP_TOOLSETS by default.

create_namespace

Argument	Type	Notes
application	string	Id, package name, trailing segment, or display name
name	string, optional

delete_namespace

Destructive. Takes namespace.

Its contexts outlive it and stay uncallable until delete_context removes them — delete contexts first. See contexts and namespaces.

invite_to_namespace

Mint an invitation. Takes namespace. Returns the invitation object.

join_namespace

Argument	Type	Notes
namespace	string
invitation	object	The object invite_to_namespace returned, unchanged
groupName	string, optional

Caution

The invitation is signed over its own bytes. Reshaping it — renaming keys, dropping fields — invalidates the signature. The server declares it as an opaque object so validation cannot strip fields it does not know about; pass it straight through.

leave_namespace

Destructive. Takes namespace.

list_group_members

Members of a group. Read-only. Takes group. Returns a flat { members, selfIdentity? }.

add_group_members

Argument	Type
group	string
members	array of { identity, role }

create_group

Create a group (a subgroup) inside a namespace, or nested under another group. Returns { groupId }.

Argument	Type	Notes
namespace	string
name	string, optional
visibility	open or restricted, optional	Without parent defaults to open; with parent defaults to restricted
parent	string, optional	Group id to nest under

With parent, the group is created for the parent’s application, restricted, and an explicit visibility is applied as a second step because core’s nested create takes none; if that step fails, the error names the created group so set_group_visibility can finish the job.

set_group_visibility

Takes group and visibility (open: namespace members can join; restricted: members must be added).

set_group_metadata

Set a group’s name and metadata. data is stored whole: keys left out of it are removed. An omitted name keeps the current one.

Argument	Type	Notes
group	string
name	string, optional	Omitted keeps the current name
data	object of string values, optional	The complete key/value set; omitted means empty

join_open_group

Join an open group through membership of its parent namespace or group. Takes group. Returns { groupId, memberPublicKey, wasInherited }. Follow it with join_context for the contexts inside the group.

Application

Always registered.

describe_app

Show an application’s methods and guide without choosing a context. Read-only.

Argument	Type	Notes
app	string	Id, package name, trailing segment, or display name
service	string, optional	For an app bundling several services

Returns, as JSON: application, package, appVersion, resolved service, contextServices, every method as a signature (with its doc and documented parameters when the ABI carries them; see ABI mapping), and an app_handle with no context. Then the guide as an embedded text/markdown resource after an author label, or the line This app ships no guide. describe_app always carries the guide; select_app carries it only the first time a session shows that app version, then a note naming the resource uri.

Omitting service on a multi-service app returns an error naming the available services. When no context exists to read a service name from, a serviceNote says so: nothing on the application record or in the ABI lists an app’s services.

select_app

Choose an application and the context to act in. Read-only.

Argument	Type	Notes
app	string	Id, package name, trailing segment, or display name
context	string, optional	Context id or alias; defaults to the app’s only context
service	string, optional	Only when no context is chosen; a chosen context decides the service
verbose	boolean, optional	Also return methods and the guide, as describe_app does

Returns what describe_app does without the methods: application, package, appVersion, service, contextServices, guide (the resource uri), the app’s tool names (tools), the chosen context, and an app_handle bound to that context and its service. The guide itself follows only the first time a session meets that app version, after which a text note points at the guide uri. tools lists exactly the tools of the app and service the handle binds. When a package name matches apps from several signers, select_app and describe_app refuse and list each application id with its signer; pass the application id. For a bundle with one named service, a context created without a service name binds that service. With several contexts and none chosen, context is null and a note lists the ids. An app missing from the tool list, for example because the node was down at connect, makes select_app, describe_app and call read the list again first.

call

Call an application method by name.

Argument	Type	Notes
app_handle	string, optional	From select_app; or pass app and context instead
context	string, optional	Context id or alias, resolved as select_app does, with app
method	string	ABI method name
args	object, optional	Arguments keyed by parameter name
app	string, optional	With context, names the app; otherwise shows that app’s guide on a refusal. A handle for another app is refused

An unknown method returns the list of methods that exist. init is refused, after the handle check, with a pointer to create_context’s args: it runs once, when the context is created.

call_many

Run up to 32 calls at once. Each item takes what call takes (method, args, and an app_handle or app with context) and is validated against its ABI the same way.

Returns an array in request order: { ok: true, result } or { ok: false, error } per item, so one failing call does not fail the batch. Calls run concurrently, so the order in which mutating methods execute is not guaranteed.

Generated method tools

One per method of every installed application except init, which create_context runs, sorted by package, then application id, then service, then method, for every client alike. Named <app>_<method>, or <app>_<service>_<method> for a multi-service application, where <app> is the sanitised trailing package segment cut to 20 characters; a name longer than 49 characters keeps its first 42 and ends in _ plus 6 hex of its sha256. A name never repeats a fixed tool’s name or another app’s: a clash adds _ plus 6 alphanumerics of the application id (see tool naming).

Argument	Type	Notes
app_handle	string, optional	From select_app; names the context
context	string, optional	Context id or alias, instead of app_handle; absent when the method has its own context parameter

plus the method’s declared parameters, typed from the ABI (ABI mapping).

Each tool carries a title (Set blocks (Mero Blocks)), a description (the method’s ABI doc, when it has one, above its signature), an outputSchema when the method returns something (described by the ABI’s returns_doc, when present), and explicit readOnlyHint, destructiveHint, idempotentHint and openWorldHint: false annotations. readOnlyHint follows the method’s intent; destructiveHint and idempotentHint follow the ABI’s destructive and idempotent flags, and idempotentHint is also true for every read-only method. A tool’s description is the method’s doc followed by its signature, or the signature alone; see ABI mapping. It also carries _meta with the package, appVersion, signerId and method intent. Results carry structuredContent next to the JSON text, except for methods that return unit, which return the text only. A contract call that fails returns isError: true with the node’s message.

Resources

calimero://apps/{applicationId}/{version}/guide (text/markdown): one resource per installed app that ships a guide. The application id is core’s hash of package and signer, so two signers of one package get separate guides; the embedded copy’s _meta carries package, appVersion and signerId.