Skip to content
BranchesTags

Repository files navigation

MCP Proto-OKN Server

License: BSD-3-Clause Python 3.10+ Model Context Protocol PyPI version

A single Model Context Protocol (MCP) server that exposes 30+ Proto-OKN knowledge graphs through one unified interface. The server enables AI assistants (Claude, ChatGPT, GitHub Copilot, etc.) to discover graphs, inspect their schemas, query them with SPARQL, bridge identifiers across graphs, and combine results from multiple sources — all through natural-language conversation. The graphs are hosted on the Open Knowledge Network (OKN) federation platform and cataloged in the OKN Knowledge Graph Registry.

Beta: the proto-okn MCP server is in beta. We welcome feedback and bug reports via issues.

Cross-Graph Demo: SPOKE, ProKN, BioBricks, SAWGraph

Video · Presentation

Note: MCP URL and installation instructions have changed. Updated instructions

Features

  • 🌐 Unified access — one MCP server, 30+ knowledge graphs, one endpoint
  • 🔎 Graph discovery — list and filter graphs by domain or entity type, or rank them by keyword overlap with a question (a lexical prefilter over registry metadata; the assistant makes the final selection)
  • 📐 Schema inspection — understand each graph's classes, predicates, and properties before writing queries
  • 🧭 Per-graph SPARQL — query any individual graph with automatic FROM-clause injection
  • 🔗 Cross-graph bridging — built-in identifier maps (Ensembl ↔ NCBI Gene ↔ Symbol; CAS, DTXSID, InChIKey; MONDO, FIPS, NAICS, …)
  • 🧬 Multi-graph queries — run different SPARQL across multiple graphs in a single call and merge results
  • 🌳 Ontology-driven search expansion — queries are automatically expanded using ontology hierarchies (MONDO, UBERON, HP, GO, CL, ChEBI, …) via Ubergraph, so a query for "arthritic joint disease" matches all of its subtypes without manual enumeration
  • 🖼️ Schema visualization & transcripts — generate Mermaid class diagrams and chat transcripts directly from the conversation

Architecture

Architecture

Workflow Example

Workflow Example

For Users

This section is for people who want to use the unified server through an MCP-compatible client (Claude Desktop, ChatGPT, Claude Code, VS Code Insiders with GitHub Copilot, etc.). No installation, no local setup — the server is already hosted, you just point your client at it.

Hosted endpoint URL: https://apps.okn.us/okn-mcp/mcp

Connecting Your Client

Claude Desktop

  1. Launch Claude Desktop → Settings → Connectors → Add custom connector
  2. Name: proto-okn, URL: https://apps.okn.us/okn-mcp/mcp
  3. Click Configure and set tool permissions to Always allow
  4. In a new chat, click + and toggle proto-okn on. Toggle Web search off.

Full walkthrough with screenshots: Claude Desktop setup.

A Claude Pro or Max subscription is required for MCP connectors in Claude Desktop.

ChatGPT

ChatGPT supports MCP services only in the web app (https://chatgpt.com) with Developer mode enabled. Then Settings → Apps → Create app, MCP Server URL https://apps.okn.us/okn-mcp/mcp.

Full walkthrough with screenshots: ChatGPT setup.

Claude Code

Add to .mcp.json in your project root (or ~/.claude/settings.json for all projects):

{
  "mcpServers": {
    "proto-okn": {
      "type": "url",
      "url": "https://apps.okn.us/okn-mcp/mcp"
    }
  }
}

Verify with /mcp — you should see proto-okn connected.

VS Code Insiders + GitHub Copilot

VS Code Insiders supports MCP in Agent mode with the GitHub Copilot extension. Use the same URL: https://apps.okn.us/okn-mcp/mcp.

Example Prompts

Once the server is connected, try these conversational prompts in your client. The assistant will pick the right graphs, write the SPARQL, and combine results for you.

  • Default: query across all Proto-OKN KGs

    Generate a table of all Proto-OKN Knowledge Graphs with two columns: "KG Name" and "Description." → Result

  • Target a specific KG with @kg-name

    @spoke-genelab: Give a high-level overview of this knowledge graph, including its main entities, relationships, and purpose.

  • Save a session

    Create a chat transcript.

    The transcript downloads as .md or .pdf and includes the model name and version.

Use Cases

Knowledge Graph Overviews & Class Diagrams

Each link points to a chat transcript for generating an overview and a class diagram for a Proto-OKN KG.

🧬 Biology & Health 🌱 Environment ⚖️ Justice 🛠️ Technology & Manufacturing NASA/NIH/ARCH(*)
biobricks-aopwiki climatemodelskg dreamkg securechainkg biomarkerkg
biobricks-ice fiokg nikg sudokn digcfdekg
biobricks-mesh geoconnex ruralkg evoweb
biobricks-pubchem-annotations hydrologykg scales gene-expression-atlas-okn
biobricks-tox21 sawgraph medical-device-kg
biobricks-toxcast sockg nasa-gesdisc-kg
biohealth spatialkg ncipidkg
spoke-genelab ufokn nde
spoke-okn wildlifekn oard-kg
pankgraph
phaseskg
prokn
rdkg

(*) ARCH: Advancing Research Capacity in Health, NSF Proto-OKN supplemental awards.

See also: Knowledge Graph Versions & Update Dates — a federation-wide snapshot of each KG's version and last-updated date from the VoID provenance metadata.

Space Flight Use Cases

Biomedical Use Cases

Environmental Use Cases

Criminal and Environmental Justice

Misc. Use Cases

Ontology-Driven Search Expansion

Queries are automatically expanded using ontology hierarchies (MONDO, HP, GO, UBERON, ChEBI, …) via Ubergraph to include all descendant concepts. A search for "cardiovascular disease" automatically matches every subtype the data is tagged at — without you having to enumerate them.

Proto-OKN Integration Opportunities

Cross-Platform LLM Benchmarks

The same prompt run across Claude Desktop and VS Code Insiders with several LLMs.

Query Claude Sonnet 4.5 (Desktop) Claude Sonnet 4.5 (VS Code) Gemini 3 Pro Groq Code Fast 1 GPT-5.2
Spaceflight Missions link link link link link
Gene Expression Analysis link link link link link

Benchmarks (in progress) — mcp-proto-okn vs. SPARQL ground-truth evaluation.

For Developers

The developer document describes how to run the server locally, contribute code, or host a copy.

The pseudocode specification describes how the server works: the query pipeline, ontology expansion, identifier mapping, and join strategies, written as pseudocode with a map back to the implementing source. A one-page summary of the core concepts and control flow is in README-brief.md.

Troubleshooting

MCP server not appearing in Claude Desktop

  • Completely quit and restart Claude Desktop (closing the window is not enough)
  • For local installs, verify uvx is on PATH (which uvx); if not, use the absolute path in command

Connection errors

  • Check that the OKN endpoints are reachable: curl https://apps.okn.us/spoke-okn/sparql. Returns "Unknown path" when connected.
  • Some endpoints may have rate limits or temporary downtime

Slow or hung queries

  • Complex SPARQL can take time; break it into smaller parts
  • Ontology expansion across very broad concepts (e.g. "disease") pulls a large descendant set into the query and may take several minutes against the target graph; narrow the concept or set auto_expand_descendants=False to query the exact URI only

"Query refused: SERVICE may only address the OKN federation"

  • A SERVICE clause pointing outside apps.okn.us is rejected, because its result cannot be reproduced from the graphs this server serves
  • Ontology lookups do not need an external endpoint: the ontology hub is available in-federation as GRAPH <https://purl.org/okn/frink/kg/ubergraph>
  • Peer graphs are reachable as SERVICE <https://apps.okn.us/<graph>/sparql> as before

License

This project is licensed under the BSD 3-Clause License. See LICENSE.

Citation

@software{rose2025mcp-proto-okn,
  title={MCP Server Proto-OKN},
  author={Rose, P.W. and Good, B.M. and Nelson, C.A. and Saravia-Butler, A.M. and Shi, Y. and Su, A.I. and Baranzini, S.E.},
  year={2025},
  url={https://github.com/sbl-sdsc/mcp-proto-okn}
}

@software{rose2025spoke-genelab,
  title={NASA SPOKE-GeneLab Knowledge Graph},
  author={Rose, P.W. and Nelson, C.A. and Gebre, S.G. and Saravia-Butler, A.M. and Soman, K. and Grigorev, K.A. and Sanders, L.M. and Costes, S.V. and Baranzini, S.E.},
  year={2025},
  url={https://github.com/BaranziniLab/spoke_genelab}
}

Videos and Presentations

Note: MCP URL and installation instructions have changed. Updated instructions

Related Publications

  • Nelson, C.A., Rose, P.W., Soman, K., Sanders, L.M., Gebre, S.G., Costes, S.V., Baranzini, S.E. (2025). "Nasa Genelab-Knowledge Graph Fabric Enables Deep Biomedical Analysis of Multi-Omics Datasets." NASA Technical Reports, 20250000723. Link
  • Sanders, L., Costes, S., Soman, K., Rose, P., Nelson, C., Sawyer, A., Gebre, S., Baranzini, S. (2024). "Biomedical Knowledge Graph Capability for Space Biology Knowledge Gain." 45th COSPAR Scientific Assembly, July 13-21, 2024. Link

Acknowledgments

Funding

  • National Science Foundation Award #2333819: "Proto-OKN Theme 1: Connecting Biomedical information on Earth and in Space via the SPOKE knowledge graph"
  • National Science Foundation Award #2535091: "Proto-OKN Theme 2: OKN-Fabric"

Related Projects

For questions, issues, or contributions, please visit our GitHub repository.

About

A Model Context Protocol (MCP) server that provides tools for querying SPARQL endpoints, with specialized support for NSF-funded Proto-OKN (Prototype Open Knowledge Network) knowledge graphs hosted on the FRINK platform.

Topics

knowledge-graphmcpmcp-serverproto-oknsparql-endpoints

Resources

Readme
BSD-3-Clause license
Activity
Custom properties

Stars

8 stars

Watchers

1 watching

Forks

7 forks
Report repository

Releases

Packages

Contributors

Languages