Skip to main content

MCP interface

Team: @UNC-RENCI-KGAI/mcp-interface

A read-only MCP server over a Neo4j copy of the final graph. Any MCP client, Pi included, can use it to search nodes, explore neighbors and paths, and explain any edge down to the source file, columns and record it came from ("why does A connect to B?").

The implementation spec is AGENTS.md in the KGB-CIA repository.

Quick start

Requires uv and Python 3.12 or newer. Add this to your MCP client's configuration (for Pi, .pi/mcp.json). The Bolt host, artifacts URL and checksum change with each release; get the current ones from the KGB-CIA team by opening an issue in the repository.

{
  "mcpServers": {
    "kgbcia-mcp": {
      "command": "uvx",
      "args": ["kgbcia-mcp", "serve", "--enable-cypher"],
      "env": {
        "NEO4J_URI": "bolt://<bolt-host>:7687",
        "NEO4J_DATABASE": "neo4j",
        "KGB_MCP_ARTIFACTS": "https://<public-artifact-host>/artifacts.tar.gz",
        "KGB_MCP_ARTIFACTS_SHA256": "<64-hex-artifact-checksum>"
      }
    }
  }
}

The shared Neo4j runs without authentication, so no user or password is needed. The server downloads and verifies the artifacts tarball on first start.

Tools

  • get_graph_info, get_schema: counts, sources, build status, quality-flag counts and the category–predicate–category meta-graph, all precomputed.
  • search_nodes, get_node: find nodes by CURIE, equivalent identifier, name or synonym.
  • summarize_node_edges, get_node_edges: what a node connects to, with optional predicate, category, property and exclude_flags filters.
  • get_edges_between(include_lineage=true): every direct edge between two nodes with full lineage: the one-call answer to "why does A connect to B?".
  • find_paths, find_connected_nodes: bounded multi-hop connections, skipping hub nodes.
  • explain_edge: Biolink provenance, quality flags with reasons, and each source record resolved to its file, record set and columns.
  • query_cypher (with --enable-cypher): read-only, row-capped Cypher for counts and patterns the fixed tools can't express. Column aliases are optional.

Every edge in a response carries its ID, predicate, primary knowledge source, publication count and quality flags. To work on part of the graph (a gene family, a disease, a drug class), just ask: the server's instructions tell the agent to resolve and confirm the seed nodes, then scope its answers to them.

How it fits together

final graph (nodes.jsonl, edges.jsonl) + transform_report.json files
  -> orion-neo4j-dump + deploy/prepare_dump.sh -> kgb dump + artifacts tarball
  -> Helm chart (deploy/helm/kgb-mcp): Neo4j 5 Community, read-only
  <- kgbcia-mcp (this server), run locally over stdio by each MCP client

The server ships as its own package, kgbcia-mcp on PyPI, so it runs without the rest of the pipeline. Lineage beyond Biolink fields comes from each edge's kgbcia_source_records, resolved against the TransformReports (see agents/AGENTS.md).

Run it alone

Pipeline stage: an offline check that the final graph is ready to be dumped into Neo4j.

uv run kgb-mcp check --input <dir with nodes.jsonl and edges.jsonl>
# For a graph whose reports live outside data/transformation/:
uv run kgb-mcp check --input <graph-dir> --report <transform_report.json>

Prepare or refresh release artifacts:

# Full graph-to-dump release: runs ORION, then computes MCP statistics on a temporary Neo4j.
bash agents/mcp_interface/deploy/prepare_dump.sh \
  --graph-dir <dir with nodes.jsonl and edges.jsonl> \
  --reports-dir <dir containing transform_report.json files> \
  --graph-metadata <merge-metadata.json or graph metadata JSON> \
  --description data/describe/description.json \
  --output-dir <prepared-output-dir> \
  --graph-version <version>

# Artifacts-only refresh for an already deployed kgb.dump: skips ORION and copies the dump unchanged.
bash agents/mcp_interface/deploy/prepare_dump.sh \
  --artifacts-only \
  --existing-dump <existing kgb.dump> \
  --reports-dir <dir containing transform_report.json files> \
  --graph-metadata <merge-metadata.json or graph metadata JSON> \
  --description data/describe/description.json \
  --output-dir <prepared-output-dir> \
  --graph-version <version>

MCP server, against a running Neo4j:

export NEO4J_URI=bolt://<host>:7687
# Only for an authenticated Neo4j (the local-k8s default); the AWS deployment has no auth:
export NEO4J_USER=<user> NEO4J_PASSWORD=<password>
export KGB_MCP_ARTIFACTS=<dir or URL of the artifacts tarball>
export KGB_MCP_ARTIFACTS_SHA256=<required when artifacts is a URL>
uvx kgbcia-mcp serve --enable-cypher               # stdio, the published package from PyPI
uv run kgbcia-mcp serve --enable-cypher            # stdio, this checkout's code (for development)

An artifacts URL is downloaded and unpacked once, by checksum, into $KGB_CACHE_DIR/mcp-artifacts/ when KGB_CACHE_DIR is set (the pipeline's cache root), else ~/.cache/kgbcia-mcp/artifacts/.

For the local authenticated cluster, port-forward Bolt and source the local ignored deployment environment before starting Pi or the server:

kubectl -n <namespace> port-forward svc/kgb-mcp-neo4j 7687:7687
set -a; . agents/mcp_interface/deploy/.env; set +a
uv run kgbcia-mcp serve --enable-cypher

For the AWS host, use deploy/aws/README.md. It deploys only Neo4j from the same chart with values-aws.yaml and keeps mcp.enabled=false; run kgbcia-mcp locally over stdio against the host's Bolt Service.

Input / output

Input: nodes.jsonl and edges.jsonl in ORION KGX format (shared.schema.Node / Edge), from the cleaning stage (data/cleaning/, the default) or data/transformation/merged/. Every edge must have an id and a kgbcia_source_records list, except an edge the augmentation stage proposed from the literature (primary_knowledge_source: infores:kgbcia-augmentor): it has no transformation record, so it is accepted without one when it cites publications and names the edges it refines in original_edge_ids, and check counts it on a line of its own. Plus the per-source transform_report.json files under data/transformation/.

Output: check writes no graph files. kgbcia-mcp hubs writes hubs.json; the server returns JSON-serializable, read-only query results. deploy/prepare_dump.sh produces the Neo4j dump and artifact tarball (manifest.json, graph metadata, hubs and reports). The graph metadata now includes precomputed counts for get_graph_info, get_schema, and argument validation, so the running server does not scan the whole deployed graph for aggregate answers. In --artifacts-only mode the script recomputes the artifact tarball from an existing dump and copies that dump to the output unchanged.

Neo4j notes

Confirmed on the local-k8s Neo4j 5.26.31 load in November 2026:

  • Every graph node has the biolink:NamedThing anchor label. Categories are labels, not a category property; node CURIEs are in id.
  • Relationship IDs are stored in r.id; provenance lists, including kgbcia_source_records, return as native Neo4j string arrays.
  • kgbcia_node_fulltext is online over name, synonym, and the StringArray equivalent_identifiers property. The generated kgbcia_relationship_id_* range indexes are online for relationship id properties.
  • The chart's server.databases.default_to_read_only=true rejects a graph CREATE through a raw driver session as well as through query_cypher.
  • Neo4j Community permits the separate kgbcia account to create and drop users in system despite the graph database being read-only. AWS sets NEO4J_AUTH=none, so there is no application account or reusable password, but an unauthenticated raw client can still create system users. Network exposure remains the maintainer's responsibility; graph writes remain blocked by the database-level read-only setting and resource limits.

Status

The MCP interface is deployed against the real cleaned graph on the prepared AWS k3s host. The loaded graph has 943,412 nodes and 11,701,010 edges. Neo4j runs read-only with NEO4J_AUTH=none; the MCP HTTP deployment is disabled (mcp.enabled=false), so teammates run kgbcia-mcp locally over stdio and connect to the shared Bolt endpoint. Network exposure is controlled by the maintainer outside this repository.

Build-order steps 1–4 are complete: the standalone uv workspace package, offline graph check, artifact loading, TransformReport lineage, bounded Neo4j service, FastMCP tools, optional Cypher tool, dump preparation, precomputed statistics, indexes, Docker image, Helm chart, local-k8s deployment, and AWS deployment of the cleaned graph. Step 5, publication to PyPI, is complete: kgbcia-mcp is published, so anyone can run uvx kgbcia-mcp serve --enable-cypher without a checkout.

Anyone can connect with the entry under "Quick start". Update KGB_MCP_ARTIFACTS_SHA256 every time a new artifacts.tar.gz is published.

Current verification:

  • get_graph_info() returns 943,412 nodes and 11,701,010 edges and includes the build section from description.json.
  • get_schema() returns a 116-row one-category meta-graph, avoiding the former whole-graph aggregate timeout.
  • Precomputed flag counts are present for unresolved_node (1,914,123), type_violation (178,255), self_loop (2,435), and rare_category_combination (1,325).
  • Flag formatting and exclude_flags were verified on WIKIPATHWAYS:WP4580 -> CHEBI:10034 (biolink:has_participant, edge 62c07ced-910e-5540-b2b6-3c4cdd94491f): get_edges_between(include_lineage=true) returns unresolved_node and rare_category_combination as {flag, reason} pairs, and get_node_edges(..., exclude_flags=["unresolved_node"]) filters those edges out.
  • The issue #63 olodaterol (CHEBI:82700) -> ADRB2 (UniProtKB:P07550) wrong_mechanism example is pending a future graph cleaned with #62 and #49. In the current non-final graph, that DrugCentral edge cites PMID:20371707 but carries no kgbcia_flags / kgbcia_flag_reasons properties in the cleaned input, so the server correctly has no flag to report.

Known limits:

  • uvx kgbcia-mcp runs the published release, not your checkout. To test local changes to the server, use "command": "uv", "args": ["run", "kgbcia-mcp", ...] from the repository root.
  • explain_edge(edge_id) still unions over relationship types and can time out on the full graph for some edge IDs. Prefer get_edges_between(include_lineage=true) when endpoint IDs are known; it returns the same lineage for direct edges with an anchored query.
  • AWS uses unauthenticated Bolt. Read-only graph settings block graph writes and resource limits bound expensive queries, but Neo4j Community does not provide a strong authorization boundary for the system database. Who can reach Bolt is set by the maintainer's AWS security group; open it widely only for as long as needed.
  • query_cypher is read-only, row-capped and useful for ad hoc aggregates, but expensive raw queries can still hit the configured 30-second transaction timeout or 2 GiB transaction memory cap. Add LIMIT to large queries: rows beyond the cap are discarded.

Design decisions

  • Separate package: kgbcia-mcp is a uv workspace member with no imports from shared or agents, so it can be published independently from the pipeline code.
  • Local stdio server, shared Neo4j: each client runs the MCP server locally over stdio while all clients share one read-only Neo4j service. This avoids deploying and authenticating a public MCP HTTP endpoint for the demo.
  • Precomputed artifacts for aggregate answers: prepare_dump.sh computes graph summary, schema, property examples and flag counts on a temporary build-time Neo4j and writes them to graph_metadata.json. Runtime tools and validation use those artifacts and never scan the full graph for get_graph_info() or get_schema().
  • One category per node in the meta-graph: nodes carry ancestor labels, so the meta-graph uses the rarest graph-wide category label per node to avoid cross-products over all ancestors.
  • Indexes baked into the dump: the deployed database starts read-only, so the full-text node index and relationship-id indexes are created before the final kgb.dump is produced.
  • Checksum-keyed loads: Helm init containers key their PVC marker on the dump checksum, not the URL, so changing presigned URLs does not reload an unchanged dump.
  • AWS auth disabled: Neo4j Community allowed the authenticated read-only user (kgbcia) to administer system; the AWS deployment therefore uses NEO4J_AUTH=none plus maintainer-controlled network exposure, graph read-only mode and resource limits rather than a reusable plaintext Bolt password.
  • Build description is an artifact: description.json is generated on the VM that has the Nov 9 transformation output and cleaning report, then sanitized and packed into the artifact tarball so user-facing tools can mention failed or missing sources.

Metadata

Release files for kgbcia-mcp 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kgbcia-mcp 0.1.1
File Size Uploaded Provenance Actions
kgbcia_mcp-0.1.1.tar.gz 30.1 kB Without provenance Details for kgbcia_mcp-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kgbcia-mcp 0.1.1
File Interpreter ABI Platform Actions
kgbcia_mcp-0.1.1-py3-none-any.whl Python 3 none any Details for kgbcia_mcp-0.1.1-py3-none-any.whl

Total release size: 62.0 kB

Release files / kgbcia_mcp-0.1.1.tar.gz

Download URL kgbcia_mcp-0.1.1.tar.gz
Size 30.1 kB
Tags Source
SHA-256 checksum
How to use checksums
958aefda2b0d635f31dccf7adb9d7e5c2ffa82f1471ad7e81835e26d0b09fd7e
BLAKE2b-256 checksum
How to use checksums
d7a4f4611e6ec3f39749385f07f0e67ec5e068e1fe66180050b35b4020a077d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.5

Release files / kgbcia_mcp-0.1.1-py3-none-any.whl

Download URL kgbcia_mcp-0.1.1-py3-none-any.whl
Size 32.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5f5a8d430ae62fe8fffa6916ebceffa720f708fa5872271c2efac1139fe24461
BLAKE2b-256 checksum
How to use checksums
f7b8a254a5e8774b2f2a10bd4baf8472e036cf9ff7e0474d1914b34fa29c6459
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.5

Security for kgbcia-mcp 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page