MCP Tools Reference¶

BioMCP provides 35 specialized tools for biomedical research through the Model Context Protocol (MCP). This reference covers all available tools, their parameters, and usage patterns.

Conceptual Overview: Sequential Thinking with the Think Tool
Practical Examples: See the How-to Guides for real-world usage patterns
Integration Setup: Claude Desktop Integration

Tool Categories¶

Category	Count	Tools
Core Tools	3	`search`, `fetch`, `think`
Article Tools	2	`article_searcher`, `article_getter`
Trial Tools	6	`trial_searcher`, `trial_getter`, + 4 detail getters
Variant Tools	3	`variant_searcher`, `variant_getter`, `alphagenome_predictor`
BioThings Tools	3	`gene_getter`, `disease_getter`, `drug_getter`
NCI Tools	6	Organization, intervention, biomarker, and disease tools
OpenFDA Tools	12	Adverse events, labels, devices, approvals, recalls, shortages

Core Unified Tools¶

1. search¶

Universal search across all biomedical domains with unified query language.

search(
    query: str = None,              # Unified query syntax
    domain: str = None,             # Target domain
    genes: list[str] = None,        # Gene symbols
    diseases: list[str] = None,     # Disease/condition terms
    variants: list[str] = None,     # Variant notations
    chemicals: list[str] = None,    # Drug/chemical names
    keywords: list[str] = None,     # Additional keywords
    conditions: list[str] = None,   # Trial conditions
    interventions: list[str] = None,# Trial interventions
    lat: float = None,              # Latitude for trials
    long: float = None,             # Longitude for trials
    page: int = 1,                  # Page number
    page_size: int = 10,            # Results per page
    api_key: str = None             # For NCI domains
) -> dict

Domains: article, trial, variant, gene, drug, disease, nci_organization, nci_intervention, nci_biomarker, nci_disease, fda_adverse, fda_label, fda_device, fda_approval, fda_recall, fda_shortage

Query Language Examples:

"gene:BRAF AND disease:melanoma"
"drugs.tradename:gleevec"
"gene:TP53 AND (mutation OR variant)"

Usage Examples:

# Domain-specific search
search(domain="article", genes=["BRAF"], diseases=["melanoma"])

# Unified query language
search(query="gene:EGFR AND mutation:T790M")

# Clinical trials by location
search(domain="trial", conditions=["lung cancer"], lat=40.7128, long=-74.0060)

# FDA adverse events
search(domain="fda_adverse", chemicals=["aspirin"])

# FDA drug approvals
search(domain="fda_approval", chemicals=["keytruda"])

2. fetch¶

Retrieve detailed information for any biomedical record.

fetch(
    id: str,                    # Record identifier
    domain: str = None,         # Domain (auto-detected if not provided)
    detail: str = None,         # Specific section for trials
    api_key: str = None         # For NCI records
) -> dict

Supported IDs:

Articles: PMID (e.g., "38768446"), DOI (e.g., "10.1101/2024.01.20")
Trials: NCT ID (e.g., "NCT03006926")
Variants: HGVS, rsID, genomic coordinates
Genes/Drugs/Diseases: Names or database IDs
FDA Records: Report IDs, Application Numbers (e.g., "BLA125514"), Recall Numbers, etc.

Detail Options for Trials: protocol, locations, outcomes, references, all

Usage Examples:

# Fetch article by PMID
fetch(id="38768446", domain="article")

# Fetch trial with specific details
fetch(id="NCT03006926", domain="trial", detail="locations")

# Auto-detect domain
fetch(id="rs121913529")  # Variant
fetch(id="BRAF")         # Gene

# Fetch FDA records
fetch(id="BLA125514", domain="fda_approval")  # Drug approval
fetch(id="D-0001-2023", domain="fda_recall")   # Drug recall

3. think¶

Sequential thinking tool for structured problem-solving.

think(
    thought: str,               # Current reasoning step
    thoughtNumber: int,         # Sequential number (1, 2, 3...)
    totalThoughts: int = None,  # Estimated total thoughts
    nextThoughtNeeded: bool = True  # Continue thinking?
) -> str

CRITICAL: Always use think BEFORE any other BioMCP operation!

Usage Pattern:

# Step 1: Problem decomposition
think(
    thought="Breaking down query: need to find BRAF inhibitor trials...",
    thoughtNumber=1,
    nextThoughtNeeded=True
)

# Step 2: Search strategy
think(
    thought="Will search trials for BRAF V600E melanoma, then articles...",
    thoughtNumber=2,
    nextThoughtNeeded=True
)

# Final step: Synthesis
think(
    thought="Ready to synthesize findings from 5 trials and 12 articles...",
    thoughtNumber=3,
    nextThoughtNeeded=False  # Analysis complete
)

Article Tools¶

4. article_searcher¶

Search PubMed/PubTator3 for biomedical literature.

article_searcher(
    chemicals: list[str] = None,
    diseases: list[str] = None,
    genes: list[str] = None,
    keywords: list[str] = None,    # Supports OR with "|"
    variants: list[str] = None,
    include_preprints: bool = True,
    include_cbioportal: bool = True,
    page: int = 1,
    page_size: int = 10
) -> str

Features:

Automatic cBioPortal integration for gene searches
Preprint inclusion from bioRxiv/medRxiv
OR logic in keywords: "V600E|p.V600E|c.1799T>A"

Example:

# Search with multiple filters
article_searcher(
    genes=["BRAF"],
    diseases=["melanoma"],
    keywords=["resistance|resistant"],
    include_cbioportal=True
)

5. article_getter¶

Fetch detailed article information.

article_getter(
    pmid: str  # PubMed ID, PMC ID, or DOI
) -> str

Supports:

PubMed IDs: "38768446"
PMC IDs: "PMC7498215"
DOIs: "10.1101/2024.01.20.23288905"

Trial Tools¶

6. trial_searcher¶

Search ClinicalTrials.gov with comprehensive filters.

trial_searcher(
    conditions: list[str] = None,
    interventions: list[str] = None,
    other_terms: list[str] = None,
    recruiting_status: str = "ANY",  # "OPEN", "CLOSED", "ANY"
    phase: str = None,               # "PHASE1", "PHASE2", etc.
    lat: float = None,               # Location-based search
    long: float = None,
    distance: int = None,            # Miles from coordinates
    age_group: str = None,           # "CHILD", "ADULT", "OLDER_ADULT"
    sex: str = None,                 # "MALE", "FEMALE", "ALL"
    study_type: str = None,          # "INTERVENTIONAL", "OBSERVATIONAL"
    funder_type: str = None,         # "NIH", "INDUSTRY", etc.
    page: int = 1,
    page_size: int = 10
) -> str

Location Search Example:

# Trials near Boston
trial_searcher(
    conditions=["breast cancer"],
    lat=42.3601,
    long=-71.0589,
    distance=50,
    recruiting_status="OPEN"
)

7-11. Trial Detail Getters¶

# Get complete trial information
trial_getter(nct_id: str) -> str

# Get specific sections
trial_protocol_getter(nct_id: str) -> str     # Core protocol info
trial_locations_getter(nct_id: str) -> str    # Sites and contacts
trial_outcomes_getter(nct_id: str) -> str     # Outcome measures
trial_references_getter(nct_id: str) -> str   # Publications

Variant Tools¶

12. variant_searcher¶

Search MyVariant.info for genetic variants.

variant_searcher(
    gene: str = None,
    hgvs: str = None,
    hgvsp: str = None,              # Protein HGVS
    hgvsc: str = None,              # Coding DNA HGVS
    rsid: str = None,
    region: str = None,             # "chr7:140753336-140753337"
    significance: str = None,        # Clinical significance
    frequency_min: float = None,
    frequency_max: float = None,
    cadd_score_min: float = None,
    sift_prediction: str = None,
    polyphen_prediction: str = None,
    sources: list[str] = None,
    include_cbioportal: bool = True,
    page: int = 1,
    page_size: int = 10
) -> str

Significance Options: pathogenic, likely_pathogenic, uncertain_significance, likely_benign, benign

Example:

# Find rare pathogenic BRCA1 variants
variant_searcher(
    gene="BRCA1",
    significance="pathogenic",
    frequency_max=0.001,
    cadd_score_min=20
)

13. variant_getter¶

Fetch comprehensive variant details.

variant_getter(
    variant_id: str,              # HGVS, rsID, or MyVariant ID
    include_external: bool = True  # Include TCGA, 1000 Genomes
) -> str

14. alphagenome_predictor¶

Predict variant effects using Google DeepMind's AlphaGenome.

alphagenome_predictor(
    chromosome: str,              # e.g., "chr7"
    position: int,                # 1-based position
    reference: str,               # Reference allele
    alternate: str,               # Alternate allele
    interval_size: int = 131072,  # Analysis window
    tissue_types: list[str] = None,  # UBERON terms
    significance_threshold: float = 0.5,
    api_key: str = None          # AlphaGenome API key
) -> str

Requires: AlphaGenome API key (environment variable or per-request)

Tissue Examples:

UBERON:0002367 - prostate gland
UBERON:0001155 - colon
UBERON:0002048 - lung

Example:

# Predict BRAF V600E effects
alphagenome_predictor(
    chromosome="chr7",
    position=140753336,
    reference="A",
    alternate="T",
    tissue_types=["UBERON:0002367"],  # prostate
    api_key="your-key"
)

BioThings Tools¶

15. gene_getter¶

Get gene information from MyGene.info.

gene_getter(
    gene_id_or_symbol: str  # Gene symbol or Entrez ID
) -> str

Returns: Official name, aliases, summary, genomic location, database links

16. disease_getter¶

Get disease information from MyDisease.info.

disease_getter(
    disease_id_or_name: str  # Disease name or ontology ID
) -> str

Returns: Definition, synonyms, MONDO/DOID IDs, associated phenotypes

17. drug_getter¶

Get drug/chemical information from MyChem.info.

drug_getter(
    drug_id_or_name: str  # Drug name or database ID
) -> str

Returns: Chemical structure, mechanism, indications, trade names, identifiers

NCI-Specific Tools¶

All NCI tools require an API key from api.cancer.gov.

18-19. Organization Tools¶

# Search organizations
nci_organization_searcher(
    name: str = None,
    organization_type: str = None,
    city: str = None,              # Must use with state
    state: str = None,             # Must use with city
    api_key: str = None
) -> str

# Get organization details
nci_organization_getter(
    organization_id: str,
    api_key: str = None
) -> str

20-21. Intervention Tools¶

# Search interventions
nci_intervention_searcher(
    name: str = None,
    intervention_type: str = None,  # "Drug", "Device", etc.
    synonyms: bool = True,
    api_key: str = None
) -> str

# Get intervention details
nci_intervention_getter(
    intervention_id: str,
    api_key: str = None
) -> str

22. Biomarker Search¶

nci_biomarker_searcher(
    name: str = None,
    biomarker_type: str = None,
    api_key: str = None
) -> str

23. Disease Search (NCI)¶

nci_disease_searcher(
    name: str = None,
    include_synonyms: bool = True,
    category: str = None,
    api_key: str = None
) -> str

OpenFDA Tools¶

All OpenFDA tools support optional API keys for higher rate limits (240/min vs 40/min). Get a free key at open.fda.gov/apis/authentication.

24. openfda_adverse_searcher¶

Search FDA Adverse Event Reporting System (FAERS).

openfda_adverse_searcher(
    drug: str = None,
    reaction: str = None,
    serious: bool = None,        # Filter serious events only
    limit: int = 25,
    skip: int = 0,
    api_key: str = None          # Optional OpenFDA API key
) -> str

Example:

# Find serious bleeding events for warfarin
openfda_adverse_searcher(
    drug="warfarin",
    reaction="bleeding",
    serious=True,
    api_key="your-key"  # Optional
)

25. openfda_adverse_getter¶

Get detailed adverse event report.

openfda_adverse_getter(
    report_id: str,              # Safety report ID
    api_key: str = None
) -> str

26. openfda_label_searcher¶

Search FDA drug product labels.

openfda_label_searcher(
    name: str = None,
    indication: str = None,      # Search by indication
    boxed_warning: bool = False, # Filter for boxed warnings
    section: str = None,         # Specific label section
    limit: int = 25,
    skip: int = 0,
    api_key: str = None
) -> str

27. openfda_label_getter¶

Get complete drug label information.

openfda_label_getter(
    set_id: str,                 # Label set ID
    sections: list[str] = None,  # Specific sections to retrieve
    api_key: str = None
) -> str

Label Sections: indications_and_usage, contraindications, warnings_and_precautions, dosage_and_administration, adverse_reactions, drug_interactions, pregnancy, pediatric_use, geriatric_use

28. openfda_device_searcher¶

Search FDA device adverse event reports (MAUDE).

openfda_device_searcher(
    device: str = None,
    manufacturer: str = None,
    problem: str = None,
    product_code: str = None,    # FDA product code
    genomics_only: bool = True,  # Filter genomic/diagnostic devices
    limit: int = 25,
    skip: int = 0,
    api_key: str = None
) -> str

Note: FDA uses abbreviated device names (e.g., "F1CDX" for "FoundationOne CDx").

29. openfda_device_getter¶

Get detailed device event report.

openfda_device_getter(
    mdr_report_key: str,         # MDR report key
    api_key: str = None
) -> str

30. openfda_approval_searcher¶

Search FDA drug approval records (Drugs@FDA).

openfda_approval_searcher(
    drug: str = None,
    application_number: str = None,  # NDA/BLA number
    approval_year: str = None,       # YYYY format
    limit: int = 25,
    skip: int = 0,
    api_key: str = None
) -> str

31. openfda_approval_getter¶

Get drug approval details.

openfda_approval_getter(
    application_number: str,     # NDA/BLA number
    api_key: str = None
) -> str

32. openfda_recall_searcher¶

Search FDA drug recall records.

openfda_recall_searcher(
    drug: str = None,
    recall_class: str = None,    # "1", "2", or "3"
    status: str = None,          # "ongoing" or "completed"
    reason: str = None,
    since_date: str = None,      # YYYYMMDD format
    limit: int = 25,
    skip: int = 0,
    api_key: str = None
) -> str

Recall Classes:

Class 1: Dangerous or defective products that could cause serious health problems or death
Class 2: Products that might cause temporary health problems or pose slight threat
Class 3: Products unlikely to cause adverse health consequences

33. openfda_recall_getter¶

Get drug recall details.

openfda_recall_getter(
    recall_number: str,          # FDA recall number
    api_key: str = None
) -> str

34. openfda_shortage_searcher¶

Search FDA drug shortage database.

openfda_shortage_searcher(
    drug: str = None,
    status: str = None,          # "current" or "resolved"
    therapeutic_category: str = None,
    limit: int = 25,
    skip: int = 0,
    api_key: str = None
) -> str

35. openfda_shortage_getter¶

Get drug shortage details.

openfda_shortage_getter(
    drug_name: str,
    api_key: str = None
) -> str

Best Practices¶

1. Always Think First¶

# ✅ CORRECT - Think before searching
think(thought="Planning BRAF melanoma research...", thoughtNumber=1)
results = article_searcher(genes=["BRAF"], diseases=["melanoma"])

# ❌ INCORRECT - Skipping think tool
results = article_searcher(genes=["BRAF"])  # Poor results!

2. Use Unified Tools for Flexibility¶

# Unified search supports complex queries
results = search(query="gene:EGFR AND (mutation:T790M OR mutation:C797S)")

# Unified fetch auto-detects domain
details = fetch(id="NCT03006926")  # Knows it's a trial

3. Leverage Domain-Specific Features¶

# Article search with cBioPortal
articles = article_searcher(
    genes=["KRAS"],
    include_cbioportal=True  # Adds cancer genomics context
)

# Variant search with multiple filters
variants = variant_searcher(
    gene="TP53",
    significance="pathogenic",
    frequency_max=0.01,
    cadd_score_min=25
)

4. Handle API Keys Properly¶

# For personal use - environment variable
# export NCI_API_KEY="your-key"
nci_results = search(domain="nci_organization", name="Mayo Clinic")

# For shared environments - per-request
nci_results = search(
    domain="nci_organization",
    name="Mayo Clinic",
    api_key="user-provided-key"
)

5. Use Appropriate Page Sizes¶

# Large result sets - increase page_size
results = article_searcher(
    genes=["TP53"],
    page_size=50  # Get more results at once
)

# Iterative exploration - use pagination
page1 = trial_searcher(conditions=["cancer"], page=1, page_size=10)
page2 = trial_searcher(conditions=["cancer"], page=2, page_size=10)

Error Handling¶

All tools include comprehensive error handling:

Invalid parameters: Clear error messages with valid options
API failures: Graceful degradation with informative messages
Rate limits: Automatic retry with exponential backoff
Missing API keys: Helpful instructions for obtaining keys

Tool Selection Guide¶

If you need to...	Use this tool
Search across multiple domains	`search` with query language
Get any record by ID	`fetch` with auto-detection
Plan your research approach	`think` (always first!)
Find recent papers	`article_searcher`
Locate clinical trials	`trial_searcher`
Analyze genetic variants	`variant_searcher` + `variant_getter`
Predict variant effects	`alphagenome_predictor`
Get gene/drug/disease info	`gene_getter`, `drug_getter`, `disease_getter`
Access NCI databases	`nci_*` tools with API key
Check drug adverse events	`openfda_adverse_searcher`
Review FDA drug labels	`openfda_label_searcher` + `openfda_label_getter`
Investigate device issues	`openfda_device_searcher`
Find drug approvals	`openfda_approval_searcher`
Check drug recalls	`openfda_recall_searcher`
Monitor drug shortages	`openfda_shortage_searcher`

Next Steps¶

Review Sequential Thinking methodology
Explore How-to Guides for complex workflows
Set up API Keys for enhanced features

MCP Tools Reference¶

Related Guides¶

Tool Categories¶

Core Unified Tools¶

1. search¶

2. fetch¶

3. think¶

Article Tools¶

4. article_searcher¶

5. article_getter¶

Trial Tools¶

6. trial_searcher¶

7-11. Trial Detail Getters¶

Variant Tools¶

12. variant_searcher¶

13. variant_getter¶

14. alphagenome_predictor¶

BioThings Tools¶

15. gene_getter¶

16. disease_getter¶

17. drug_getter¶

NCI-Specific Tools¶

18-19. Organization Tools¶

20-21. Intervention Tools¶

22. Biomarker Search¶

23. Disease Search (NCI)¶

OpenFDA Tools¶

24. openfda_adverse_searcher¶

25. openfda_adverse_getter¶

26. openfda_label_searcher¶

27. openfda_label_getter¶

28. openfda_device_searcher¶

29. openfda_device_getter¶

30. openfda_approval_searcher¶

31. openfda_approval_getter¶

32. openfda_recall_searcher¶

33. openfda_recall_getter¶

34. openfda_shortage_searcher¶

35. openfda_shortage_getter¶

Best Practices¶

1. Always Think First¶

2. Use Unified Tools for Flexibility¶

3. Leverage Domain-Specific Features¶

4. Handle API Keys Properly¶

5. Use Appropriate Page Sizes¶

Error Handling¶

Tool Selection Guide¶

Next Steps¶