Tools¶
This page catalogues every tool the server exposes to an MCP client. Tools are plain Python functions
decorated with @mcp.tool() in aiida_mcp.server; each one’s docstring (shown here via
the API reference) is sent to the client verbatim as the tool’s description, so it
is worth keeping those docstrings accurate and complete — see Adding support for a new AiiDA plugin for the convention.
Read-only tools¶
Tool |
What it does |
|---|---|
|
Checks the server is running. |
|
Reports the loaded profile, daemon state and broker connection. |
|
Lists process nodes, newest first. Filters: |
|
Details, inputs and outputs for one process by PK. |
|
Log messages for one process, oldest first. |
|
Lists configured computers. |
|
Lists codes, optionally for one |
|
Finds nodes by |
|
Returns the content of a node: file content for |
|
Lists all configured AiiDA profiles, showing the current and default ones. |
|
Reports whether an AiiDAlab server is running locally, and its URL. See Detecting AiiDAlab. |
|
Describes the MLIP single point calcjob. |
|
Describes the MLIP geometry optimisation calcjob. |
|
Describes the MLIP molecular dynamics calcjob. |
|
Describes the MLIP phonon calcjob. |
Notes:
List tools take a
limit. The default is 20 (100 for logs), the maximum is 200 (1000 for logs), and a value below 1 is an error.list_processesstates arecreated,waiting,running,finished,exceptedandkilled.If the daemon is stopped,
get_statusdoes not check the broker, because connecting would block.get_node_contentonly supportsSinglefileData,Int,Float,DictandArrayDatanodes so far; other node types return an error naming the supported ones. File content over 1 MB is truncated, content that cannot be decoded as UTF-8 text is returned base64-encoded, and each array in anArrayDataover 1000 rows along its first axis is truncated.Errors the caller can fix, such as an unknown state or a missing PK, are returned as short messages (see
aiida_mcp.limits.clamp_limit()and theToolErrorraised throughoutaiida_mcp.nodesandaiida_mcp.processesfor the pattern).
Write tools¶
Tool |
What it does |
|---|---|
|
Builds and submits an MLIP single point calculation to the daemon. |
|
Builds and submits an MLIP geometry optimisation to the daemon. |
|
Builds and submits an MLIP molecular dynamics run to the daemon. |
|
Builds and submits an MLIP phonon calculation to the daemon. |
|
Creates a new AiiDA profile and initialises its storage. See Managing profiles. |
|
Switches the server’s active AiiDA profile. See Managing profiles. |
|
Re-checks for installed AiiDA plugins and registers any newly available ones. See Rescanning for plugins. |
DL_POLY tools now ship with aiida-dlpoly¶
describe_dlpoly_calcjob and submit_dlpoly_job are no longer bundled with aiida-mcp. They are
provided by aiida-dlpoly’s own aiida_dlpoly.mcp module,
installed via its optional mcp extra:
pip install "aiida-dlpoly[mcp]"
Once installed alongside aiida-mcp, these tools are discovered through the same aiida_mcp.plugins
entry point mechanism as any other plugin — see Adding support for a new AiiDA plugin — with no further configuration needed.
See aiida-dlpoly’s MCP integration docs for their
arguments and behaviour.
ChemShell tools now ship with aiida-chemshell¶
describe_chemshell_calcjob and submit_chemshell_job are no longer bundled with aiida-mcp. They are
provided by aiida-chemshell’s own aiida_chemshell.mcp
module, installed via its optional mcp extra:
pip install "aiida-chemshell[mcp]"
Once installed alongside aiida-mcp, these tools are discovered through the same aiida_mcp.plugins
entry point mechanism as any other plugin — see Adding support for a new AiiDA plugin — with no further configuration needed.
See aiida-chemshell’s MCP integration docs for their
arguments and behaviour.
Submitting an MLIP job¶
There are four MLIP tools — submit_mlip_sp_job (single point), submit_mlip_opt_job (geometry
optimisation), submit_mlip_md_job (molecular dynamics) and submit_mlip_ph_job (phonons),
implemented by aiida_mcp.plugins.mlip — sharing the same core arguments, plus arguments specific
to each job type.
Shared arguments:
Argument |
Meaning |
|---|---|
|
Label (e.g. |
|
Path to a structure file on the machine running the server, or the PK of an existing
|
|
Path or URL of the MLIP model file, or the PK of an existing |
|
MLIP architecture, e.g. |
|
Device to run on: |
|
Extra keyword arguments to pass to the selected calculator. |
|
Machines to run on. Default 1. |
|
MPI processes per machine. Default 1. |
|
Optional label to set on the calcjob node. |
|
Optional description to set on the calcjob node. |
Unlike configuration/field/control in submit_dlpoly_job, structure and model are
plain strings or PKs, not {"path": ...}/{"pk": ...} objects — MLIP’s own structure/model loading
helpers (aiida_mlip.helpers.help_load.load_structure/load_model) are reused directly, and they
already accept either form as a single value.
Job-specific arguments:
submit_mlip_sp_job:out(xyz output filename),properties(list of properties to calculate, e.g.["energy", "forces"]).submit_mlip_opt_job:opt_cell_fully,opt_cell_lengths(bools),fmax(float),steps(int),minimize_kwargs(dict),pressure(float, GPa).submit_mlip_md_job:ensemble(str, e.g.NVT),md_kwargs(dict).submit_mlip_ph_job:out,supercell,qpoint_file(str),n_qpoints(int),displacement(float),no_hdf5,dos,pdos,bands,symmetrize(bools).
Example arguments for a single point calculation:
{
"code": "janus@localhost",
"structure": "/data/structure.xyz",
"architecture": "mace_mp",
"properties": ["energy", "forces"]
}
Behaviour is the same as submit_dlpoly_job. Follow the job with get_process and
get_process_report, and check exit_status against the codes listed by the matching
describe_mlip_*_calcjob tool.
Rescanning for plugins¶
Plugin tools are discovered from the aiida_mcp.plugins entry point group
(aiida_mcp.plugins.ENTRY_POINT_GROUP), and both AiiDA and Python cache entry point lookups for the
lifetime of the process (aiida.plugins.entry_point.eps/eps_select are wrapped in
functools.cache; Python’s import system caches which distributions exist on sys.path). That means
installing a new plugin package (e.g. pip install aiida-dlpoly into the server’s environment while it
is already running, assuming it declares its own aiida_mcp.plugins entry point) is invisible to the
server until those caches are cleared — restarting the whole server is one way to do that, but
rescan_plugins (aiida_mcp.plugins.clear_entry_point_cache() plus
aiida_mcp.plugins.register_all()) does it without a restart:
Clears AiiDA’s and Python’s cached entry point lookups.
Re-runs the normal plugin registration pass (
aiida_mcp.plugins.register_all()), which enumerates everyaiida_mcp.pluginsentry point again, checksis_available()for each one, and registers tools for any that are now available.
Plugins already registered are left alone — registering the same tool name twice is a safe no-op (the underlying MCP server keeps the existing tool and does not duplicate or error). The response reports both the full set of currently available plugins and which ones (if any) were newly registered by this call, identified by their entry point name:
{
"available": ["dlpoly", "chemshell"],
"newly_registered": ["chemshell"]
}
An empty newly_registered list means nothing changed since the server started (or since the last
successful rescan) — not that the rescan failed.
Managing profiles¶
Note
create_profile and switch_profile are currently disabled (commented out in
aiida_mcp.server). list_profiles is still available.
The server always runs against one loaded profile (see Introduction), but it can also create and
switch between profiles at runtime, through aiida_mcp.profiles.
Argument |
Meaning |
|---|---|
|
Name for the new profile. |
|
Default user’s email. Required unless |
|
Storage entry point. Defaults to |
|
Backend-specific configuration, e.g. |
|
Message broker: |
|
Optional details for the default user. |
|
Makes the new profile the on-disk default, used the next time the server starts. |
Example:
{
"name": "scratch",
"email": "me@example.com",
"storage_config": {"filepath": "/data/aiida-scratch"}
}
create_profile only creates and initialises the profile; it does not change which profile the
running server uses — call switch_profile with the profile’s name for that. list_profiles
shows what is configured, which one is the default, and which one the server currently has loaded.
create_profile fails if a profile with that name already exists, if storage_backend or
broker is not recognised, or if email is missing for a non-read-only backend, and nothing is left
behind on failure. switch_profile fails if name does not match a configured profile; on success
it loads the profile and initialises its storage, so the next call may take a moment. Switching profiles
affects every subsequent tool call on the server, including from other clients connected to the same
server process.
Detecting AiiDAlab¶
get_aiidalab_status (aiida_mcp.aiidalab.get_status()) is meant for the common setup where an
AiiDAlab container’s startup script launches the MCP server alongside the default Jupyter notebook
server, as the same user and in the same Python environment. An MCP client on your local machine can
then ask the container “is AiiDAlab up, and what’s its URL”. See Integrating with AiiDAlab for how to
set that deployment up, including which port to expose for the MCP server itself.
It uses jupyter_server.serverapp.list_running_servers(), the same mechanism behind
jupyter server list, to find Jupyter servers running in that environment. Since it shares the
environment with AiiDAlab, this requires no special handling for differing users, home directories, or
installed packages.
Requires the aiidalab extra (pip install -e ".[aiidalab]"), though in the container deployment
described above jupyter-server is already installed as part of AiiDAlab itself. Without it, the tool
reports running: false with an explanatory error instead of failing.
Possible results:
No running server found at all:
{"running": false}.A server whose working directory mentions
aiidalab, or the sole running server if none do (an AiiDAlab container normally runs only one Jupyter server):{"running": true, "url": "...", "pid": ..., "root_dir": "...", "version": "..."}. The URL includes the access token, so it can be opened directly in a browser.Several running servers and none clearly AiiDAlab:
{"running": true, "ambiguous": true, "servers": [...]}, listing every one so the caller can pick the right one (e.g. byroot_dirorpid).
This only detects a server running in the same Python environment as the MCP server; it will not see an AiiDAlab instance running in a different container or on a remote machine.