PhenotypeLibrary MCP Server

A Model Context Protocol (MCP) server for the Phenotype Library / Concept Library API.

This server provides access to clinical code lists, phenotypes, ontology terms, and other research metadata from the SAIL Databank Concept Library.

Features

• Phenotypes: Search and retrieve phenotype definitions, codelists, and version history

• Concepts: Search and retrieve clinical code lists (concepts), codelists, and version history

• Ontology: Search ontology terms (MONDO, MeSH, SNOMED CT, ICD-10, etc.)

• Collections: Browse collections of phenotypes/concepts

• Tags: Browse tags for categorization

• Data Sources: Access data source metadata

• Templates: Browse phenotype templates

Related MCP server: SNOMED CT MCP Server

Installation

# Install from source
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Configuration

Create a .env file with your configuration:

# API Configuration
PHENOTYPELIBRARY_BASE_URL=https://conceptlibrary.saildatabank.com/api/v1/
PHENOTYPELIBRARY_TIMEOUT=30.0

# Optional: Authentication (for private data)
PHENOTYPELIBRARY_USERNAME=your_username
PHENOTYPELIBRARY_PASSWORD=your_password

Available Domains

• SAIL (default): https://conceptlibrary.saildatabank.com/api/v1/

• HDRUK: https://phenotypes.healthdatagateway.org/api/v1/

• Demo: https://conceptlibrary.demo-dev.saildatabank.com/api/v1/

• ADP: https://conceptlibrary.saildatabank.com/ADP/api/v1/

• Gateway: https://conceptlibrary.serp.ac.uk/api/v1/

Deployment

Render (Web Service)

1. Connect your GitHub repository to Render

2. Create a new Web Service

3. Use the render.yaml configuration file (or manually configure):

   • Build Command: pip install -e .

   • Start Command: uvicorn phenotypelibrary_mcp.server:app --host 0.0.0.0 --port $PORT

   • Health Check Path: /health

4. Add environment variables:

   • PHENOTYPELIBRARY_BASE_URL (optional, defaults to SAIL)

   • PHENOTYPELIBRARY_TIMEOUT (optional, defaults to 30.0)

   • PHENOTYPELIBRARY_USERNAME (optional, for private data)

   • PHENOTYPELIBRARY_PASSWORD (optional, for private data)

MCP Endpoint

Once deployed, the MCP server will be available at:

• SSE Endpoint: https://your-app.onrender.com/mcp/sse

• Health Check: https://your-app.onrender.com/health

Docker

# Build the image
docker build -t phenotypelibrary-mcp .

# Run the container
docker run -p 8000:8000 \
  -e PHENOTYPELIBRARY_BASE_URL=https://conceptlibrary.saildatabank.com/api/v1/ \
  phenotypelibrary-mcp

Docker Compose

docker-compose up -d

Usage

Running the Server

# Run with stdio transport (for MCP clients like Cursor, Claude Desktop)
python -m phenotypelibrary_mcp.server

# Or use the entry point
phenotypelibrary-mcp

# Run with SSE transport (for HTTP-based MCP clients)
python -m phenotypelibrary_mcp.server --transport sse --host 0.0.0.0 --port 8000

Using with MCP Inspector

# Test with MCP Inspector (SSE transport)
npx @modelcontextprotocol/inspector https://phenotypelibrarymcp.onrender.com/mcp/sse

Using with MCP Clients

Add to your MCP client config (Cursor, Claude Desktop, etc.):

{
  "mcpServers": {
    "phenotypelibrary": {
      "url": "https://phenotypelibrarymcp.onrender.com/mcp/sse"
    }
  }
}

For stdio transport (local development):

{
  "mcpServers": {
    "phenotypelibrary": {
      "command": "python",
      "args": ["-m", "phenotypelibrary_mcp.server"]
    }
  }
}

Available Tools

Phenotypes

• search_phenotypes - Search phenotypes with filters

• get_phenotype_detail - Get detailed phenotype information

• get_phenotype_codelist - Get clinical codes for a phenotype

• get_phenotype_versions - Get version history

Concepts

• search_concepts - Search concepts (clinical code lists)

• get_concept_detail - Get detailed concept information

• get_concept_codelist - Get clinical codes for a concept

• get_concept_versions - Get version history

Ontology

• search_ontology - Search ontology terms

• get_ontology_node - Get specific ontology node by term

• get_ontology_groups - Get all ontology groups

• get_ontology_type - Get ontology type details

Collections & Tags

• get_collections - List all collections

• get_collection_detail - Get collection details

• get_tags - List all tags

• get_tag_detail - Get tag details

Data Sources & Templates

• get_data_sources - List data sources

• get_data_source_detail - Get data source details

• get_templates - List templates

• get_template_detail - Get template details

• get_template_versions - Get template version history

Example Usage

# Search for asthma phenotypes
result = await search_phenotypes(search="asthma")

# Get phenotype detail
detail = await get_phenotype_detail("PH1")

# Get codelist for a phenotype
codelist = await get_phenotype_codelist("PH1")

# Search ontology for diabetes terms
ontology = await search_ontology(search="diabetes")

# Get specific ontology node
node = await get_ontology_node("MONDO:0005148")

Resources

The server also exposes resources:

• phenotype://{phenotype_id} - Phenotype details

• concept://{concept_id} - Concept details

• ontology://{term} - Ontology node details

Prompts

Pre-built prompts for common tasks:

• phenotype_search_prompt(condition) - Search phenotypes for a condition

• concept_search_prompt(condition) - Search concepts for a condition

• ontology_search_prompt(term) - Search ontology for a term

API Response Handling

The Concept Library API returns lists for many detail endpoints. This server automatically handles these responses:

• Detail endpoints (get_phenotype_detail, get_concept_detail, etc.): Returns the first item from the list

• Codelist endpoints (get_phenotype_codelist, get_concept_codelist): Wraps the list in {"codes": [...]}

• Version endpoints (get_phenotype_versions, get_concept_versions, get_template_versions): Wraps the list in {"versions": [...]}

• Ontology groups (get_ontology_groups): Wraps the list in {"groups": [...]}

All ID parameters are automatically stripped of whitespace to prevent URL encoding issues.

Development

# Run tests
pytest

# Lint
ruff check .

# Format
ruff format .

License

GPL-3.0 - See LICENSE file for details.

References

• Concept Library Website

• API Documentation

• Python Client

• R Client

• GitHub Repository