MINERVA v21.0
Manual

Back to the admin manual

An MCP endpoint of the MINERVA Platform#

MINERVA can expose its content over the Model Context Protocol (MCP), allowing AI assistants and other MCP clients to query projects programmatically.

The endpoint of the MCP is <your instance root url>/mcp. For instance, the following endpoint configuration allows to connect to the MCP of MINERVA hosting the PD map:

{
  "mcpServers": {
    "minerva": {
      "type": "http",
      "url": "https://pdmap.uni.lu/minerva/mcp"
    }
  }
}

Scope#

Each separate instance of the MINERVA Platform has a separate MCP endpoint. This endpoint allows access to publicly visible projects, i.e. those where user anonymous has view rights. No authentication is required to access the endpoint.

The endpoint can be configured to be on or off, and it is set to off by default. You can change this setting in the MINERVA configuration.

Tools#

All tools are read-only - the MCP endpoint does not allow to modify the content of an instance. Every tool except projects_list, about_minerva and server_status takes a project identifier as its first argument; this is the Project ID visible in the Projects panel.

Identifiers of diagrams, species, compartments, pathways and reactions are integers, and they are the same in all the tools below.

Utility tools#

about_minerva
returns the documentation of the endpoint: the tools it offers, the data model of projects, diagrams, elements, compartments, pathways and reactions, and the description of the graph model.
server_status
returns whether the endpoint is enabled, and the version of the MINERVA instance serving it.

Listing and search tools#

projects_list
lists all projects available via this endpoint, with their basic metadata: project identifier, name, version, disease, organism, creation date, and the identifier of the top-level diagram.
diagrams_list
lists all diagrams of a project, with their identifiers, names and notes.
species_list
lists elements (species) of a project. Supports filtering (see below) and pagination.
species_search
searches elements of a project by a text query, matching against name, synonyms, symbol and full name. Can be restricted to selected diagrams. Paginated.
compartment_list
lists compartments of a project, optionally restricted to selected diagrams.
pathway_list
lists pathways of a project, optionally restricted to selected diagrams.
reaction_list
lists reactions of a project, with their reactants, products and modifiers. Supports filtering by diagram, reaction type, participating elements, or reaction identifiers. Paginated.
species_list
accepts the following optional filters, which can be combined:

Elements inside complexes Each element returned by species_list and species_search carries a complexAncestry field: an ordered list of complex identifiers, from the immediate parent complex up to the outermost one. It is empty for elements that are not part of any complex. This allows to establish the full nesting of an element without additional queries.

Graph tools#

Graph tools treat the contents of a project as a network, which is useful for exploring connectivity rather than listing contents.

graph_stats
aggregate counts for a project - elements, compartments, reactions and diagrams - together with a per-diagram breakdown, and the number of reactions of each type. A good starting point before exploring a project in detail.
graph_boundary
three separate lists of element identifiers: elements that are never produced by any reaction (upstream sources of the network), elements of type phenotype, and elements not connected to any reaction. The last list is useful for spotting curation gaps.
graph_degrees
the elements taking part in the most reactions (hubs), ranked highest first. By default 10 elements are returned, and the computation can be restricted to selected diagrams.
graph_neighbors
for a single element, the reactions it takes part in, together with all other participants of those reactions and their roles.
graph_reactions
for a list of elements, all reactions involving at least one of them, with all their participants. Useful for expanding a set of elements to their full reaction context.
graph_paths
all simple paths between two sets of elements, given by their identifiers. Both sets accept multiple identifiers, so several copies of the same protein can be handled in a single call.
graph_paths_by_name
as above, with source and target given by their exact names instead of identifiers.
graph_paths_by_annotation
as above, with source and target given by annotations in identifiers.org compact identifier format, e.g. uniprot:P37840.

The graph model#

The network is bipartite: element nodes (species, compartments and pathways) and reaction nodes, connected whenever an element takes part in a reaction. Each connection carries a role describing how the element relates to the reaction: reactant (consumed), product (produced), or one of the modifier roles - catalysis, inhibition, trigger, unknown modifier, or a generic modifier.

Consequently, a path returned by the three graph_paths tools alternates between elements and reactions, starting and ending with an element: for a path of N reactions there are N+1 elements.

Limits of path searching Path length is capped at 6 reactions to prevent combinatorial explosion; the default is 4.

Pagination#

species_list, species_search and reaction_list return results in pages. Both the page size (50 by default) and the page number (counted from 0) can be provided. Besides the requested contents, each response reports the total number of matching entries, the total number of pages, and whether the returned page is the first or the last one.

Page outline