Mcp Proto Okn

MCP Proto-OKN Server

[](https://opensource.org/licenses/BSD-3-Clause) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io/) [](https://pypi.org/project/mcp-proto-okn/)

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](#for-users)

---

Features

• 🌐 Unified access — one MCP server, 30+ knowledge graphs, one endpoint
• 🔎 Graph discovery — list, filter, and search graphs by domain, entity type, or natural language
• 📐 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

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](docs/claude-setup.md).

> 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](docs/chatgpt-setup.md).

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](docs/examples/proto-okn-overview.md)

• 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](docs/examples/biobricks-aopwikioverview.md) | [climatemodelskg](docs/examples/climatemodelskgoverview.md) | [dreamkg](docs/examples/dreamkgoverview.md) | [securechainkg](docs/examples/securechainkgoverview.md) | [biomarkerkg](docs/examples/biomarkerkg-overview.md) | | [biobricks-ice](docs/examples/biobricks-iceoverview.md) | [fiokg](docs/examples/fiokgoverview.md) | [nikg](docs/examples/nikgoverview.md) | [sudokn](docs/examples/sudoknoverview.md) | [digcfdekg](docs/examples/digcfdekgoverview.md) | | [biobricks-mesh](docs/examples/biobricks-meshoverview.md) | [geoconnex](docs/examples/geoconnexoverview.md) | [ruralkg](docs/examples/ruralkgoverview.md) | | [evoweb](docs/examples/evoweb-overview.md) | | [biobricks-pubchem-annotations](docs/examples/biobricks-pubchem-annotationsoverview.md) | [hydrologykg](docs/examples/hydrologykgoverview.md) | [scales](docs/examples/scalesoverview.md) | | [gene-expression-atlas-okn](docs/examples/gene-expression-atlas-oknoverview.md) | | [biobricks-tox21](docs/examples/biobricks-tox21overview.md) | [sawgraph](docs/examples/sawgraphoverview.md) | | | [maudekg](docs/examples/maudekg-overview.md) | | [biobricks-toxcast](docs/examples/biobricks-toxcastoverview.md) | [sockg](docs/examples/sockgoverview.md) | | | [nasa-gesdisc-kg](docs/examples/nasa-gesdisc-kgoverview.md) | | [biohealth](docs/examples/biohealthoverview.md) | [spatialkg](docs/examples/spatialkgoverview.md) | | | [ncipidkg](docs/examples/ncipidkg-overview.md) | | [spoke-genelab](docs/examples/spoke-genelaboverview.md) | [ufokn](docs/examples/ufoknoverview.md) | | | [nde](docs/examples/ndeoverview.md) | | [spoke-okn](docs/examples/spoke-oknoverview.md) | [wildlifekn](docs/examples/wildlifeknoverview.md) | | | [oard-kg](docs/examples/oard-kg-overview.md) | | | | | | [pankgraph](docs/examples/pankgraph-overview.md) | | | | | | [phaseskg](docs/examples/phaseskg-overview.md) | | | | | | [prokn](docs/examples/proknoverview.md) | | | | | | [rdkg](docs/examples/rdkgoverview.md) |

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

Space Flight Use Cases

• [Spaceflight Missions (spoke-genelab)](docs/examples/spoke-genelab_breakdown.md)
• [Spaceflight Gene Expression Analysis (spoke-genelab, spoke-okn)](docs/examples/spokespaceflightanalysis.md)
• [Spaceflight Gene Expression with Literature Analysis (spoke-genelab, spoke-okn, MCP:PubMed)](docs/examples/spoke-genelab-OSD-244_verbatim.md)
• [Spaceflight Gene Expression — Disease Associations (spoke-genelab, spoke-okn, prokn, MCP:Open Targets, MCP:PubMed)](docs/examples/space-flight-disease-relationships.md)
• [Spaceflight Microbiome and Pathogen Analysis (spoke-genelab, spoke-okn, MCP:PubMed)](docs/examples/spoke-genelabmicrobiomeandpathogenanalysis.md)

Biomedical Use Cases

• [Disease Prevalence in the US (spoke-okn)](docs/examples/uscountydisease_prevalence.md)
• [Disease Prevalence — Socio-Economic Factors Correlation (spoke-okn)](docs/examples/diseasesocioeconomic_correlation.md)
• [NIAID Data Exploration — COVID-19 Vaccine Research (nde)](docs/examples/nde_COVID-19-Vaccine-Research.md)
• [Diabetic Nephropathy Meta-Analysis (gene-expression-atlas-okn)](docs/examples/diabetic-nephropathy-meta-analysis.md) — featured on WOBD as a worked example
• [Diabetic Nephropathy Differential Expression Analysis (gene-expression-atlas-okn, ARCHS4)](docs/examples/dndifferentialexpressionarchs4analysis.md)
• [APOE Gene Info (prokn)](docs/examples/prokn-apoe-gene.md)
• [Protein - Rare Disease Associations (prokn, oard-kg)](docs/examples/prokn-oard-kg-proteins-associated-rare-diseases.md)
• [Prostate Cancer Biomarkers (biomarkerkg)](docs/examples/biomarkerkg-prostate-cancer.md)
• [Marfan Syndrome Phenotypes (oard-kg)](docs/examples/oard-kg-marfan-syndrom-phenotypes.md)
• [Pancreatic Acinar Cell Adhesion Genes (pankgraph)](docs/examples/pankgraph-pancreatic-acinar-cell-adhesion-genes.md)

Environmental Use Cases

• [Contamination at Superfund Sites (spoke-okn)](docs/examples/superfund-contaminants.md)
• [PFOA in Drinking Water (spoke-okn)](docs/examples/spokeoknpfoadrinkingwater.md)
• [Data about PFOA (spoke-okn, biobricks-toxcast)](docs/examples/pfoadataspokeoknbiobricks_toxcast.md)
• [PFAS Environmental Health Analysis (sawgraph, spoke-okn, biobricks-ice)](docs/examples/pfasenvironmentalhealthkganalysis.md) — featured on WOBD as a worked example
• [Biological Targets for PFOA (biobricks-toxcast, biobricks-ice, biobricks-aopwiki, spoke-okn)](docs/examples/biobrickstoxcastPFOA_targets.md)
• [PFOA Safety Profile (biobricks-ice, biobricks-aopwiki, sawgraph, spoke-okn)](docs/examples/pfoa-safety-profile.md)
• [Bisphenol A Safety Profile (biobricks-ice, biobricks-aopwiki, spoke-okn)](docs/examples/bpa-safety-profile.md)

Criminal and Environmental Justice

• [Criminal Justice Patterns (scales)](docs/examples/scalescriminaljustice_analysis.md)
• [Drug Possession Charges (scales)](docs/examples/scalesdrugpossession.md)
• [Environmental Justice (sawgraph, scales, spatialkg, spoke-okn)](docs/examples/environmental-justice-analysis.md)
• [Rural Health Access (ruralkg, dreamkg, spoke-okn)](docs/examples/rural-health-access-mapping.md)

Misc. Use Cases

• [Michigan Flooding Event (ufokn)](docs/examples/ufoknmichiganflood.md)
• [Flooding and Socio-Economic Factors (ufokn, spatialkg, spoke-okn)](docs/examples/flooding-socioeconomic-correlation.md)
• [Philadelphia Area Incidents (nikg)](docs/examples/nikgphiladelphiaincidents.md)
• [Mining Suppliers in North Dakota (sudokn)](docs/examples/sudoknminingsuppliers.md)

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.

• [Cardiovascular Disease Datasets — full walkthrough (nde)](docs/examples/cardiovascular-disease-ontology-expansion.md) — shows how one URI in the query expands to 1,592 descendant concepts and matches 284 disease subtypes
• [Arthritic Joint Disease Datasets (nde)](docs/examples/nde-arthriticjointdiseaseontologyexpansion.md)
• [Space Flight Studies Investigating Muscles (spoke-genelab)](docs/examples/spoke-genelabmusclestudiesontologyexpansion.md)

Proto-OKN Integration Opportunities

• [Cross-KG Geolocation Data Exploration](docs/examples/cross-kg-geolocation-analysis.md)
• [Cross-KG Chemical Compound Data Exploration](docs/examples/cross-kg-compound-analysis.md)
• [Cross-KG Bio Data Exploration (Opus 4.7)](docs/examples/cross-graph-opportunities-bio-opus4.7.md)
• [Cross-KG Bio Data Exploration (Sonnet 4.6)](docs/examples/cross-graph-opportunities-bio-sonnet4.7.md)

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](docs/examples/spacex-missions-sonnet-4.5-claude.md) | [link](docs/examples/spacex-missions-sonnet-4.5-vs-studio.md) | [link](docs/examples/spacex-missions-Gemini-3-Pro.md) | [link](docs/examples/spacex-missions-Gorc-Code-Fast-1.md) | [link](docs/examples/spacex-missions-GPT-5.2.md) | | Gene Expression Analysis | [link](docs/examples/OSD-161-sonnet-4.5-claude.md) | [link](docs/examples/OSD-161-sonnet-4.5-vs-studio.md) | [link](docs/examples/OSD-161_Gemini-3-ProPreview-vs-studio.md) | [link](docs/examples/OSD-161-Groc-Code-Fact-1-vs-studio.md) | [link](docs/examples/OSD-161-GPT-5.2-vs-studio.md) |

[Benchmarks (in progress)](docs/benchmarks.md) — mcp-proto-okn vs. SPARQL ground-truth evaluation.

---

For Developers

The [developer document](docs/develop.md) describes how to run the server locally, contribute code, or host a copy.

---

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") may take several minutes

---

License

This project is licensed under the BSD 3-Clause License. See [LICENSE](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](#for-users)

• Technical Review

Video · Presentation

• Project Overview of the SPOKE Project

Video

• Cross-Graph Demo: SPOKE, ProKN, BioBricks, SAWGrap

Video · Presentation

• Building and Querying the SPOKE-GeneLab Knowledge Graph

Video · Presentation

• Knowledge Graphs for Space Life Sciences

Video · [Presentation](https://docs.google.com/presentation/d/1qq9C4HgCsyYKpsRcRMWIV-U7WeSCJN9g/edit?usp=sharing&ouid=112820493940716707493&rtpof=true&sd=truehttps://docs.google.com/presentation/d/1qq9C4HgCsyYKpsRcRMWIV-U7WeSCJN9g/edit?slide=i

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sbl-sdsc
• Source: sbl-sdsc/mcp-proto-okn
• License: BSD-3-Clause

Install and usage instructions live in the source repository linked above.