MCP Proto-OKN Server

A Model Context Protocol (MCP) server providing seamless access to SPARQL endpoints with specialized support for the NSF-funded Proto-OKN Project (Prototype Open Knowledge Network). This server enables querying the scientific knowledge graphs hosted on the FRINK platform. In addition, third-party SPARQL endpoints can be queried.

Natural Language Querying Across Knowledge Graphs with MCP

Video

Presentation

Related MCP server: GraphQL MCP Toolkit

Features

• 🔗 FRINK Integration: Automatic detection and documentation linking for FRINK-hosted knowledge graphs

• 🕸️ Proto-OKN Knowledge Graphs: Optimized support for biomedical and scientific knowledge graphs, including:

  • 🧬 Biology & Health

  • 🌱 Environment

  • ⚖️ Justice

  • 🛠️ Technology & Manufacturing

• ⚙️ Flexible Configuration: Support for both FRINK and custom SPARQL endpoints

• 📚 Automatic Documentation: Registry links and metadata for Proto-OKN knowledge graphs

• 🌳 Ontology-driven Search Expansion: Queries are automatically expanded using ontology hierarchies

• 🔗 Federated Query: Prompts can query multiple endpoints

Architecture

The MCP Server Proto-OKN acts as a bridge between AI assistants (like Claude) and SPARQL knowledge graphs, enabling natural language queries to be converted into structured SPARQL queries and executed against scientific databases.

Prerequisites

• Client Application

  • Claude Desktop with subscription

  • ChatGPT with subscription

  • VS Code Insiders with GitHub Copilot subscription

  • Other MCP-compliant applications

Installation and Configuration

Beta Notice: The proto-okn MCP server is currently in beta testing.
We welcome feedback and bug reports. Please submit any issues.

Claude Desktop Setup

ChatGPT Setup

If you previously used a local installation of mcp-proto-okn in Claude Desktop, disable those services or remove them from claude_desktop_config.json.

Example Queries

• By default, the server will query all Proto-OKN KGs, e.g.,

Generate a table of all Proto-OKN Knowledge Graphs with two columns: “KG Name” and “Description.”

• To query a specific KG refer to it by @kg-name, e.g.

@spoke-genelab: How many studies are in this KG?

• To create a transcript of a chat session, use the following prompt

Create a chat transcript

The transcript can then be downloaded in .md or .pdf format. The transcript includes prompts and results from the chat session. It also includes the LLM model name and version number that was used.

Knowledge Graph Overviews & Class Diagrams

Each link below points to a chat transcript that demonstrates how to generate a knowledge-graph overview and class diagram for a given Proto-OKN Theme 1 KG. The examples are grouped by domain area.

Use Cases

1. Spaceflight Missions (spoke-genelab)

2. Spaceflight Gene Expression Analysis (spoke-genelab, spoke-okn)

3. Spaceflight Gene Expression with Literature Analysis (spoke-genelab, spoke-okn, PubMed)

4. Spaceflight Gene Expression with Open Targets MCP integration (spoke-genelab, Open Targets, PubMed)

5. Disease Prevalence in the US (spoke-okn)

6. Disease Prevalence - Socio-Economic Factors Correlation (spoke-okn)

7. NIAID Data Exploration - COVID-19 Vaccine Research (nde)

8. Diabetic Nephropathy Meta-Analysis (gene-expression-atlas-okn)

9. Contamination at Superfund Sites (spoke-okn)

10. PFOA in Drinking Water (spoke-okn)

11. Data about PFOA (spoke-okn, biobricks-toxcast)

12. Biological Targets for PFOA (biobricks-toxcastbiobricks-ice, biobricks-apowiki, spoke-okn)

13. PFOA Safety Profile (biobricks-ice, biobricks-apowiki, sawgraph, spoke-okn)

14. Bisphenol A Safety Profile (biobricks-ice, biobricks-apowiki, spoke-okn)

15. Criminal Justice Patterns (scales)

16. Drug Possession Charges (scales)

17. Environmental Justice (sawgraph, scales, spatialkg, spoke-okn)

18. Rural Health Access (ruralkg, dreamkg, spoke-okn)

19. Michigan Flooding Event (ufokn)

20. Flooding and Socio-Economic Factors (ufokn, spatialkg, spoke-okn)

21. Philadelphia Area Incidents (nikg)

22. Mining Suppliers in North Dakota (sudokn)

Ontology-Driven Search Expansion

Queries are automatically expanded using ontology hierarchies (MONDO, HP, GO, UBERON, etc.) from the Ubergraph KG to include all descendant concepts, ensuring comprehensive retrieval without manual enumeration. For example, searching for "arthritic joint disease" automatically includes rheumatoid arthritis, osteoarthritis, ankylosing spondylitis, and all other subtypes.

1. Arthritic Joint Disease Datasets (nde)

2. Space Flight Studies Investigating Muscles (spoke-genelab)

Proto-OKN Integration Opportunities

1. Cross-KG Geolocation Data Exploration

2. Cross-KG Chemical Compound Data Exploration

Cross-Platform LLM Benchmarks

This section compares the results of two queries using Claude Desktop and VS Code Insiders with commons LLMs.

Benchmarks (in progress)

mcp-proto-okn vs. SPARQL Ground-Truth Evaluation

Benchmarks

Building and Publishing (maintainers only)

Instructions for building, testing, and publishing the mcp-proto-okn package on PyPI

API Reference and Query Analysis System

mcp-proto-okn server API

Remote Deployment

The server supports two transport modes:

• stdio (default) -- local subprocess mode, used by uvx mcp-proto-okn

• streamable-http -- remote HTTP mode, for hosting a server that multiple clients connect to over the network

Environment Variables

CLI arguments --transport, --host, and --port take precedence over environment variables.

Testing Locally with Claude Code

Start the server in HTTP mode:

# Terminal 1: Start the server
MCP_PROTO_OKN_TRANSPORT=streamable-http mcp-proto-okn \
  --endpoint https://frink.apps.renci.org/spoke/sparql

# The server listens on http://localhost:8000/mcp

Then configure Claude Code to connect via the remote MCP URL (add to .mcp.json or Claude Code settings):

{
  "mcpServers": {
    "proto-okn": {
      "type": "url",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Desktop Requirements (HTTPS + Domain)

Claude Desktop requires HTTPS with a valid domain name for remote MCP servers (it does not support http://localhost). Steps:

1. Deploy the server to a host with a domain name

2. Set up HTTPS via a reverse proxy (e.g., nginx, Caddy) or cloud service

3. Optionally set MCP_PROTO_OKN_API_KEY for authentication

4. Configure Claude Desktop:

{
  "mcpServers": {
    "proto-okn": {
      "type": "url",
      "url": "https://your-domain.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Troubleshooting

MCP server not appearing in Claude Desktop:

• Ensure you've completely quit and restarted Claude Desktop (not just closed the window)

• Check that your JSON configuration is valid (attach your config file to a chat and ask it to fix any errors)

• Verify that uvx is installed and accessible in your PATH (which uvx)

Connection errors:

• Verify the SPARQL endpoint URL is correct and accessible

• Some endpoints may have rate limits or temporary downtime

Performance issues:

• Complex SPARQL queries may take time to execute

• Consider breaking down complex queries into smaller parts

License

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

Citation

If you use MCP Server Proto-OKN in your research, please cite the following works:

@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}
}

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

This work is in part supported by:

• 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

• Proto-OKN Project - Prototype Open Knowledge Network initiative

• FRINK Platform - Knowledge graph hosting infrastructure

• Knowledge Graph Registry - Catalog of available knowledge graphs

• Model Context Protocol - AI assistant integration standard

• Original MCP Server SPARQL - Base implementation reference

For questions, issues, or contributions, please visit our