MCP Tools

Graphomics exposes its capabilities as Model Context Protocol tools over streamable HTTP. Connect an MCP-capable client to your Graphomics MCP endpoint (see the Quickstart) and call the tools below directly from your agent.

What your token can do. Every token belongs to one organization and carries a role. Most tools work for any organization token. query_graph (raw Cypher) needs a service or admin role. Call whoami first to see exactly what yours allows.

Identity

Tool	Purpose
`whoami`	Your own organization, role and capabilities: whether identity is configured, and whether you can run `query_graph`. Open to every caller; it only ever reports your own identity.

Knowledge-graph lookups

Structured reads over MicroMap. Available to any organization token. Results include the evidence on each association (direction, number of studies, PubMed IDs) where the source provides it.

Tool	Parameters	Purpose
`kg_search`	`q`, `types?`, `limit?`, `offset?`	Search across taxa, diseases and metabolites by name. Use it to find the IDs the other tools take. `types` takes label names exactly as written, e.g. `Disease` or `Taxon`. Disease names follow MeSH order, so a single distinctive word (`colitis`) finds more than a phrase.
`kg_taxon_by_id`	`taxon_id`	Fetch a taxon by NCBI tax ID or graph taxon ID (`NCBITaxon:838`).
`kg_taxon_by_name`	`query`	Search taxa by scientific or common name.
`kg_taxon_diseases`	`taxon_id`, `limit?`	Diseases associated with a taxon.
`kg_taxon_metabolites`	`taxon_id`, `limit?`	Metabolites a taxon produces.
`kg_disease_taxa`	`disease_id`, `direction?`, `limit?`	Taxa associated with a disease; filter `direction` to `depleted` or `enriched`.
`kg_disease_metabolites`	`disease_id`, `limit?`	Metabolites associated with a disease.
`kg_metabolite_producers`	`metabolite_id`, `limit?`	Taxa that produce a metabolite.
`kg_graph_neighborhood`	`entity_id`, `max_depth?`, `limit?`	The neighborhood around an entity. Pass the entity's name (e.g. `Faecalibacterium prausnitzii`).
`kg_graph_path`	`from_id`, `to_id`, `max_depth?`	The shortest path between two entities, by name (e.g. `Faecalibacterium prausnitzii` → `Butyrate`).

Example. Find the disease ID with kg_search, then ask for the taxa depleted in it:

text

kg_search(q="colitis")
  → { "type": "Disease", "id": "colitis, ulcerative", "name": "Colitis, Ulcerative" }, …

kg_disease_taxa(disease_id="colitis, ulcerative", direction="depleted")
  → { "disease": "colitis, ulcerative",
      "taxa": [ { "taxon_name": …, "taxon_id": …, "direction": "depleted",
                  "n_studies": …, "pmids": [ … ] }, … ],
      "count": … }

Graph and schema

Tool	Purpose
`list_databases`	List the databases in the federated graph and their status. Open to every caller.
`get_schema`	Node labels and relationship types for a database, with counts. Open to every caller.
`query_graph`	Run a read-only Cypher query and return up to 1,000 rows. Requires a `service` or `admin` role; other callers get an error pointing them to the lookup tools above.

Provenance

Results are scoped to your organization: you see your own contributions and the shared reference data, never another organization's.

Tool	Purpose
`provenance_record_finding`	Record an Experiment → Analysis → Assertion finding and project the resulting graph edges. The organization is taken from your token, never from the request.
`provenance_lineage`	Trace the experiment → analysis → assertion lineage for an entity, as it stands now or as of a timestamp. Superseded assertions are excluded.
`provenance_artifact_lineage`	For a content-addressed artifact (by `sha256`): the decision that produced it, the decisions that used it downstream, and the chain of artifacts it was derived from.

MapForge tools

Build and extend the knowledge graph. See the MapForge guide for the end-to-end workflow.

Tool	Purpose
`mapforge_create_bundle`	Create an empty bundle/session; returns a `bundle_dir`.
`mapforge_inspect`	Profile a source file: columns, inferred types, row-count estimate, samples.
`mapforge_templates_list`	List built-in discipline templates (`{name, version, description}`).
`mapforge_templates_show`	Return the full YAML of one named template.
`mapforge_map_heuristic`	Draft a `mapping.yaml` from the column profile (optional `schema_config`).
`mapforge_resolve`	Resolve source entities against the graph; write `resolution.json`.
`mapforge_plan`	Plan ingest routing; write `routing.yaml`.
`mapforge_emit`	Generate Cypher from the resolved bundle.
`mapforge_approve`	Human approval gate; record reviewer and timestamp.
`mapforge_submit`	Execute the approved Cypher against the graph (gated on approval).