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 andexclude_flagsfilters.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:NamedThinganchor label. Categories are labels, not acategoryproperty; node CURIEs are inid. - Relationship IDs are stored in
r.id; provenance lists, includingkgbcia_source_records, return as native Neo4j string arrays. kgbcia_node_fulltextis online overname,synonym, and the StringArrayequivalent_identifiersproperty. The generatedkgbcia_relationship_id_*range indexes are online for relationshipidproperties.- The chart's
server.databases.default_to_read_only=truerejects a graphCREATEthrough a raw driver session as well as throughquery_cypher. - Neo4j Community permits the separate
kgbciaaccount to create and drop users insystemdespite the graph database being read-only. AWS setsNEO4J_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 thebuildsection fromdescription.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), andrare_category_combination(1,325). - Flag formatting and
exclude_flagswere verified onWIKIPATHWAYS:WP4580->CHEBI:10034(biolink:has_participant, edge62c07ced-910e-5540-b2b6-3c4cdd94491f):get_edges_between(include_lineage=true)returnsunresolved_nodeandrare_category_combinationas{flag, reason}pairs, andget_node_edges(..., exclude_flags=["unresolved_node"])filters those edges out. - The issue #63 olodaterol (
CHEBI:82700) -> ADRB2 (UniProtKB:P07550)wrong_mechanismexample is pending a future graph cleaned with #62 and #49. In the current non-final graph, that DrugCentral edge cites PMID:20371707 but carries nokgbcia_flags/kgbcia_flag_reasonsproperties in the cleaned input, so the server correctly has no flag to report.
Known limits:
uvx kgbcia-mcpruns 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. Preferget_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
systemdatabase. Who can reach Bolt is set by the maintainer's AWS security group; open it widely only for as long as needed. query_cypheris 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. AddLIMITto large queries: rows beyond the cap are discarded.
Design decisions
- Separate package:
kgbcia-mcpis a uv workspace member with no imports fromsharedoragents, 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.shcomputes graph summary, schema, property examples and flag counts on a temporary build-time Neo4j and writes them tograph_metadata.json. Runtime tools and validation use those artifacts and never scan the full graph forget_graph_info()orget_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.dumpis 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 administersystem; the AWS deployment therefore usesNEO4J_AUTH=noneplus maintainer-controlled network exposure, graph read-only mode and resource limits rather than a reusable plaintext Bolt password. - Build description is an artifact:
description.jsonis 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.