Working with applications

Four tools cover the application side: describe_app to look, select_app to generate tools, deselect_app to take them away, and call as the fixed-name escape hatch.

Naming an application

Anywhere a tool takes an application, three forms work:

Form	Example
Application id	5w8XyQ… (base58)
Full package name	com.calimero.kv-store
Trailing package segment	kv-store

The short form is matched on whole segments only, so mero-chat never resolves to mero-chat-v2. If the segment is ambiguous across installed applications, the error names the candidates and you disambiguate with the full package or the id:

Application "chat" is ambiguous: com.calimero.chat, com.example.chat.
Pass the full package name or the application id.

A name that matches nothing lists what is installed, which is usually faster than going back to list_applications.

Selecting several applications

select_app adds to the selection. Applications already selected keep their tools, so one instruction can span two apps without losing the first:

Select kv-store, then also select mero-chat.

Each selection keeps its own pinned context, and its own tool-name prefix. Tool names come from the resolved application rather than the string you typed, so the same app always produces the same names no matter how you referred to it.

When two packages would sanitise to the same prefix, the second gets a short suffix derived from its application id — never from selection order, so the names are stable across sessions.

Selecting an application that is already selected refreshes it: the old tools are dropped and re-registered from a freshly fetched ABI. That is how you pick up an application you just upgraded.

Trimming the list

deselect_app removes one application’s tools and its pinned context, leaving every other selection untouched:

Deselect mero-chat.

Past 80 generated tools, select_app adds a warning to its result — a long tool list gets hard for a model to work with, and deselect_app is how you cut it back. The server never refuses a selection over it.

Note

The selection lives in the server process and lasts as long as it does. Restart the MCP client and you start from an empty selection again.

Multi-service applications

An application can bundle several services, and each has its own ABI. Pass service to reach one:

Call describe_app with app "my-app" and service "Accounts".

Omitting service on a multi-service app returns an error from the node naming the services available. For a selected multi-service app the tool prefix includes the service, so <app>_<service>_<method> — that is what keeps two services’ same-named methods apart.

Service names are awkward to discover: nothing on the application record or in the ABI lists them. describe_app reports the service names any existing contexts use (contextServices), which is what create_context asks for. When there are no contexts yet, it says so explicitly and you take the name from the app’s bundle or its docs.

Targeting a context per call

Every generated tool accepts an optional _context argument — a context id or alias to run that one call against, overriding the pinned context:

Call kv_store_entries with _context "staging".

The leading underscore is deliberate: no ABI generator emits a parameter starting with _, so an application’s own context parameter keeps its name. In the pathological case where a method really does declare a parameter named _context, the declared parameter wins and targeting is unavailable for that method — dropping its argument would break the call outright.

Context resolution goes: an explicit _context, then the pin for that application, then the application’s only context if it has exactly one. With several and no pin, the error lists the ids.

Aliases are resolved through the node and cached for the session. A value shaped like a base58 context id is passed through untouched; anything else is looked up as an alias.

call vs generated tools

call reaches the same methods through one fixed tool name:

Call the `call` tool with method "set" and args {"key": "greeting", "value": "hello"}.

Use it when:

• The generated tools are not visible. Tools appearing mid-session is the common cause — see troubleshooting.
• You have not selected anything. call takes an optional app (and service), so it can load an ABI and invoke a method in one step.

With several applications selected, call requires app to disambiguate. With exactly one, it defaults to it.

Arguments go under args, keyed by parameter name, and are validated against the same ABI-derived schema the generated tools use. An unknown method name returns the list of methods that do exist.