What can you do with this server?

This server lets you resolve and retrieve authoritative biological entity information (genes and proteins) through MCP tools. * resolve_gene: Resolve gene symbols, aliases (e.g. HER2 → ERBB2), or accession IDs to canonical gene entities with cross-references and confidence-scored match reasons. * Batch resolution: Resolve multiple gene queries at once via batch_resolve_genes. * Contextual disambiguation: Provide optional chromosome or locus-type hints to improve gene resolution. * Cross-species support: Specify taxon_id for non-human gene lookups (e.g. mouse). * Protein metadata: Fetch UniProt protein details such as name, gene, length, mass, and organism via get_protein_info. * Structured JSON output: All tools return JSON strings suitable for LLM/agent consumption.

How do I use biocontext?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@biocontext resolve HER2 to its official HGNC gene symbol" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

biocontext

by CORE-Lab-Research

Overview Schema Source Related Servers Discussions Admin

Python

Local

BioContext

Authoritative Biological Entity Resolution & Contextual Intelligence Framework.

BioContext standardizes, resolves, and cross-references biological entities (genes, proteins, transcripts, genomic loci) across fragmented reference authorities (HGNC, NCBI Entrez, UniProt, Ensembl) with deterministic accuracy and explainable audit trails.

Designed natively for AI coding agents and biological research workflows via the Model Context Protocol (MCP).

Key Capabilities (Phase 0 - MVP v0.1.0)

Authoritative Resolution Hierarchy:
- Human Genes (HGNC Primary): Direct symbol resolution and historical alias/previous symbol traversal (e.g. HER2 $\rightarrow$ ERBB2, p53 $\rightarrow$ TP53).
- NCBI Entrez Integration: Entrez Gene ID lookup (7157 $\rightarrow$ TP53) and cross-species identifier support.
- UniProtKB Cross-Mapping: Direct accession resolution (P04637 $\rightarrow$ TP53) and protein structural metadata enrichment.
Explainable Audit Trail: Every resolution result includes exact matching rules, confidence scores ($0.0 - 1.0$), and authoritative source citations.
Strongly Typed Schemas: Comprehensive Pydantic models for GeneEntity, ProteinEntity, GenomicLocation, and ResolutionResult.
Embedded Persistence: Zero-configuration SQLite key-value cache with configurable TTL to reduce latency and comply with NCBI rate limits.
Model Context Protocol (MCP): Native stdio server compliant with MCP 2.x for integration with Claude Desktop, Antigravity IDE, Cursor, and custom LLM tool-calling clients.

Related MCP server: BioBTree

Architecture Overview

[ LLM / AI Client / Agent ]
           |
       (MCP stdio)
           v
   [ FastMCP Server ]
           |
   [ Entity Resolver ]
      /    |     \
     v     v      v
  [HGNC] [NCBI] [UniProt]
     \     |     /
    [ SQLite Cache ]

Installation (Single Source of Truth)

BioContext is distributed as a standalone CLI tool and MCP server via uv.

Global Installation (Recommended)

Install biocontext globally into your system path using uv tool:

# Install directly from GitHub
uv tool install git+https://github.com/CORE-Lab-Research/biocontext.git

Once installed, the biocontext command is available everywhere across your terminal.

To update to the latest release:

uv tool upgrade biocontext

Local Development Setup

If you are developing or contributing to the codebase:

git clone https://github.com/CORE-Lab-Research/biocontext.git
cd biocontext

# Install editable tool locally
uv tool install --editable .

# Or synchronize local virtualenv with dev dependencies
uv sync --extra dev

Configuration & Rate Limits

BioContext operates out-of-the-box with zero required configuration using public biological REST APIs.

NCBI Entrez API Key (Optional)

NCBI enforces a rate limit of 3 requests/second without an API key, and 10 requests/second with an API key. BioContext features an internal client-side token bucket rate limiter to automatically prevent HTTP 429 throttling.

To increase your throughput when working with extensive batches:

# Set your NCBI API key in your shell environment
export NCBI_API_KEY="your_ncbi_api_key_here"

BioContext automatically detects NCBI_API_KEY from the environment and dynamically unlocks 10 req/s concurrency.

Running Tests

Execute the complete asynchronous test suite:

uv run --extra dev pytest -v

All 8 integration tests verify HGNC exact matching, alias traversal, UniProt accession lookup, NCBI Entrez ID lookup, and MCP tool endpoints.

Using BioContext as an MCP Server

BioContext exposes its tools via standard input/output (stdio), making it compatible with any MCP-compliant client.

Option A: Run directly from GitHub via `uvx` (No local clone needed)

If uv is installed on your system, you or any user can run BioContext directly without cloning the repository:

{
  "mcpServers": {
    "biocontext": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/CORE-Lab-Research/biocontext.git",
        "biocontext"
      ]
    }
  }
}

Option B: Local Repository Setup

When working with a locally cloned repository:

uv run biocontext

Add the server to your client's MCP configuration (claude_desktop_config.json, Cursor, Antigravity IDE, etc.):

{
  "mcpServers": {
    "biocontext": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/biocontext",
        "run",
        "biocontext"
      ]
    }
  }
}

Note: Replace /path/to/biocontext with the absolute path to your cloned directory (e.g. /home/user/projects/biocontext on Linux/macOS or C:/Users/Username/projects/biocontext on Windows).

Command-Line Interface (CLI)

BioContext includes a built-in CLI for direct terminal testing without needing an active LLM client:

# Resolve a gene symbol or alias
biocontext resolve TP53
biocontext resolve HER2

# Resolve with contextual hint for disambiguation (e.g. chromosome, locus type)
biocontext resolve TP53 --chrom 17
biocontext resolve TP53 --locus-type protein-coding

# Query cross-species (e.g. Mus musculus - taxon 10090)
biocontext resolve Trp53 --taxon 10090

# Batch resolve multiple entities
biocontext batch TP53 HER2 EGFR MYC

# Fetch protein metadata from UniProt
biocontext protein P04637

# Manage local cache
biocontext cache stats
biocontext cache clear

# Run built-in accuracy benchmark & test suite
biocontext bench
biocontext test

Available MCP Tools

Tool	Parameters	Description
`resolve_gene`	`query: str`, `taxon_id: int = 9606`, `chromosome: str = None`, `locus_type: str = None`	Resolves official symbols (`TP53`), aliases (`HER2`), or Entrez IDs (`7157`) to a canonical `GeneEntity` with contextual scoring adjustments.
`batch_resolve_genes`	`queries: list[str]`, `taxon_id: int = 9606`	Concurrently resolves multiple gene identifiers or aliases.
`get_protein_info`	`accession: str`	Retrieves structured protein metadata from UniProtKB by primary accession (e.g. `P04637`).

Benchmark & Empirical Validation

To validate Phase 0 accuracy KPIs, a 25-case benchmark suite evaluates standard symbols, historical aliases (MLL, OCT4, INT1, HER2), Entrez IDs (7157, 672, 2064), UniProt accessions, and cross-species lookups:

uv run --extra dev pytest tests/test_benchmark.py -v

Accuracy: $100%$ ($25/25$ benchmark cases passing).
Target KPI: $\ge 95%$ accuracy achieved.

Example Resolution Output

{
  "query": "HER2",
  "match_status": "alias",
  "confidence_score": 0.85,
  "resolved_entity": {
    "symbol": "ERBB2",
    "name": "erb-b2 receptor tyrosine kinase 2",
    "taxon_id": 9606,
    "species": "Homo sapiens",
    "hgnc_id": "HGNC:3430",
    "ncbi_gene_id": "2064",
    "ensembl_gene_id": "ENSG00000141736",
    "uniprot_ids": ["P04626"],
    "synonyms": ["HER2", "NEU", "NGL", "TKR1", "CD340", "HER-2", "MLN 19", "HER-2/neu"],
    "locus_type": "gene with protein product",
    "location": {
      "chromosome": "17q12",
      "start": null,
      "end": null,
      "strand": null,
      "assembly": "GRCh38"
    }
  },
  "match_reasons": [
    {
      "source": "HGNC",
      "rule": "alias_match",
      "confidence": 0.85,
      "details": "Matched alias_match via HGNC REST API for symbol 'ERBB2'"
    }
  ]
}

Roadmap

Phase 0 (MVP v0.1.0) [CURRENT]: Core schemas, HGNC, NCBI Entrez, UniProt adapters, SQLite cache, FastMCP server.
Phase 1 (v0.5.0): Ensembl & MGI adapters, batch processing engine, PyPI package publication, REST API bridge.
Phase 2 (v1.0.0): Knowledge Graph integration, Biological Evidence & Provenance layer, AI Reasoning (Bio-RAG).
Phase 3 (v2.0.0): Variant interpretation, Drug discovery cross-referencing, multi-omics integration.

Citation

If you use BioContext in your scientific research or software workflows, please cite:

@software{nandatama2026biocontext,
  author = {Nandatama, Engki},
  title = {BioContext: Authoritative Biological Entity Resolution & Contextual Intelligence Framework},
  year = {2026},
  url = {https://github.com/CORE-Lab-Research/biocontext},
  version = {0.1.0}
}

Or reference CITATION.cff.

License

Distributed under the Apache License, Version 2.0. See LICENSE for more information.

Available Tools

3 tools

batch_resolve_genesA

Resolve a list of gene identifiers/aliases in batch.

Args: queries: List of gene symbols or aliases (e.g. ["TP53", "HER2", "EGFR"]). taxon_id: NCBI Taxonomy ID (default: 9606 for human).

Returns: JSON string containing list of resolved entity results.

ParametersJSON Schema

Name	Required	Description	Default
`queries`	Yes
`taxon_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description carries the burden of behavioral disclosure. It does state the return format ('JSON string containing list of resolved entity results'), which is useful, and the verb 'resolve' suggests a non-mutating lookup. However, it does not disclose behavior for unmatched or ambiguous identifiers, error cases, or any access requirements, leaving meaningful gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, with the core purpose stated in the first sentence. The Args and Returns sections are minimal, each line serving a clear purpose with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool, the description provides the essential call information: required input, optional parameter with default, and return format. The main missing piece is guidance on how this tool relates to resolve_gene, and edge-case behavior is not addressed, but overall it is sufficiently complete for basic invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate for documenting the parameters. It does: queries is explained as 'gene symbols or aliases' with concrete examples, and taxon_id is described as 'NCBI Taxonomy ID' with its human default of 9606. This adds meaning well beyond the bare schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb, resource, and scope: 'Resolve a list of gene identifiers/aliases in batch.' This clearly differentiates it from the sibling resolve_gene by emphasizing batch handling, while also distinguishing it from get_protein_info by focusing on identifier resolution rather than protein details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'in batch' implies the tool is intended for multiple gene queries, and the plural 'queries' parameter reinforces this. However, there is no explicit guidance about when to prefer batch_resolve_genes over resolve_gene, nor any stated exclusion such as 'for a single gene, use resolve_gene.' The usage context is clear but mostly implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_protein_infoA

Fetch structured protein details from UniProt by primary accession.

Args: accession: UniProt accession ID (e.g. P04637).

Returns: JSON string containing protein name, gene, length, mass, and organism.

ParametersJSON Schema

Name	Required	Description	Default
`accession`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It states the operation, the data source, and the exact JSON return shape including protein name, gene, length, mass, and organism. It does not mention error handling for invalid accessions, but for a simple read-only retriever this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured with Args and Returns sections. No sentence is wasted, and the most important information—what the tool fetches and what it returns—is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-required-parameter read-only tool with an output schema available, this description is complete. It specifies the input format, gives a realistic example, and describes the returned payload, so an agent has everything needed to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description fully compensates by defining the parameter as a 'UniProt accession ID' and giving a concrete example (P04637). This gives an agent enough information to construct a valid call despite the schema providing no parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Fetch') and resource ('structured protein details from UniProt by primary accession'), which clearly distinguishes it from the sibling gene-resolution tools. It also previews the returned fields, making the scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the intended use clear: provide a UniProt primary accession and receive protein details. It does not explicitly contrast with resolve_gene or batch_resolve_genes, but the 'by primary accession' phrasing and the sibling names make the appropriate context inferable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_geneA

Resolve an ambiguous gene symbol, alias, or accession to an authoritative entity.

Args: query: Gene symbol (e.g. TP53), alias (e.g. HER2, p53), or accession. taxon_id: NCBI Taxonomy ID (default: 9606 for human). chromosome: Optional chromosome hint for disambiguation (e.g. '17' or 'chr17'). locus_type: Optional biotype hint (e.g. 'protein-coding', 'pseudogene').

Returns: JSON string containing the resolved canonical gene entity, cross-references, and match audit trail.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`taxon_id`	No
`chromosome`	No
`locus_type`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of disclosing behavior. It does explain the return format (JSON string with canonical entity, cross-references, and match audit trail), but it does not describe what happens on no match, multiple ambiguous hits, or whether the operation is read-only. This is a moderate gap for an otherwise straightforward lookup tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the purpose sentence, followed by a compact Args list and Returns line. Every sentence adds useful information and there is no filler, though the structure is slightly verbose with the docstring-style sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, all four parameters are documented and an output schema is present, so return structure is already covered. The description lacks explicit error/edge-case behavior and sibling differentiation, but it is otherwise complete enough for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description fully compensates by adding meaning to every parameter: query examples (TP53, HER2, p53), default taxon_id with human-specific context, chromosome format examples, and locus_type biotype examples. Each parameter is more actionable than the bare schema types provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence uses a specific verb ('Resolve') and states the exact resource and ambiguity condition: gene symbols, aliases, or accessions are mapped to an authoritative entity. This clearly differentiates the tool from batch_resolve_genes (single vs batch) and get_protein_info (resolution vs protein information).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a query is ambiguous and needs authoritative resolution, and it hints at optional disambiguation arguments. However, it does not explicitly state when to prefer batch_resolve_genes for multiple queries or when get_protein_info would be more appropriate, so the guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.0Sep 27, 2026
- First observedbatch_resolve_genes
- First observedget_protein_info
- First observedresolve_gene

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-09-27 00:40 across 3 tools

Disambiguation4/5

Tools are largely distinct: get_protein_info fetches protein details by accession, while resolve_gene and batch_resolve_genes both handle gene resolution. The overlap between single and batch resolution is clear from descriptions, so an agent can choose appropriately without much confusion.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: get_protein_info, batch_resolve_genes, resolve_gene. Even the batch_ prefix maintains a clear convention, making the naming uniform and predictable.

Tool Count4/5

With only 3 tools, the server is minimal but well-scoped for the domain of gene and protein resolution. While it's on the lower end of typical counts, the tools cover core operations for this focused purpose, so the count feels appropriate rather than thin.

Completeness3/5

The server covers single and batch gene resolution plus protein lookup by accession, but lacks operations like batch protein retrieval or direct gene-to-protein mapping. Agents may need to chain resolve_gene and get_protein_info manually, representing a notable gap in seamless workflow completion.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

ACEL Observatory A
za.co.pccswart.radar
Machine-readable entity discovery with provenance, trust and verified source evidence.
E-commerce & Retail Product Management
51
UniBio IntelligenceOAuth
io.github.unibio-intelligence
Connect AI clients to biomedical data and tools.
Biology & Medicine Research & Data AI & Machine Learning
2
ExMachina AI — agent research rooms A
io.github.SecondStageTurbine
AI agents collaborate on open biomedical problems, citing sources that are machine-checked.
Biology & Medicine Research & Data Autonomous Agents
231
DeepDNA A
ai.deepdna
Cited gene, variant (rsID) and CPIC drug–gene lookups for AI agents. Read-only, no key.
41

Related MCP Servers

UniProt MCP Server
Bioinformatics Research & Data Databases
TakumiY235
A
license
B
quality
D
maintenance
Enables AI assistants to access protein information directly from UniProt, allowing retrieval of protein names, functions, sequences, and organism data by accession number.
Updated 4 months ago (2026-05-29 16:23 UTC)
2
14
MIT
BioBTree
Bioinformatics Databases Research & Data
tamerh
A
license
Not graded
quality
A
maintenance
A unified biomedical graph database that integrates 50+ primary data sources — genes, proteins, compounds, diseases, pathways, and clinical data — into a single queryable graph with billions of cross-reference edges. Its native MCP server gives LLMs direct access to structured, authoritative biomedical data, complementing their reasoning with reliable identifiers and up-to-date database content.
Updated 25 days ago (2026-09-02 06:59 UTC)
20
AGPL 3.0
gwas-mcp
Bioinformatics Biology & Medicine
muslus
A
license
C
quality
F
maintenance
Provides AI-powered access to major biological databases for GWAS and bioinformatics research. Enables natural language queries for protein, gene, variant, pathway, and drug discovery analysis.
Updated 8 months ago (2026-02-09 22:51 UTC)
44
1
MIT
MyGene MCP Server
Bioinformatics Biology & Medicine
nickzren
A
license
C
quality
D
maintenance
Enables AI assistants to query gene annotations, expression, pathways, variants, and more via the MyGene.info API, supporting batch operations and multiple biological data sources.
Updated 5 months ago (2026-05-04 20:53 UTC)
26
MIT

BioContext

Key Capabilities (Phase 0 - MVP v0.1.0)

Architecture Overview

Installation (Single Source of Truth)

Global Installation (Recommended)

Local Development Setup

Configuration & Rate Limits

NCBI Entrez API Key (Optional)

Running Tests

Using BioContext as an MCP Server

Option A: Run directly from GitHub via uvx (No local clone needed)

Option B: Local Repository Setup

Command-Line Interface (CLI)

Available MCP Tools

Benchmark & Empirical Validation

Example Resolution Output

Roadmap

Citation

License

Available Tools

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Option A: Run directly from GitHub via `uvx` (No local clone needed)