Configuration Reference

This page classifies supported operator runtime configuration separately from internal fixture overrides and release/install variables.

Operator API Keys

Variable	Purpose
ALPHAGENOME_API_KEY	Enables get variant <id> predict
DISGENET_API_KEY	Enables gene/disease disgenet sections
NCBI_API_KEY	Improves NCBI E-utilities quota for ClinVar, PubMed, PMC OA, and ID Converter paths; PubTator3 stays at its published three requests a second with or without the key
NCI_API_KEY	Enables trial operations with --source nci
ONCOKB_TOKEN	Enables the explicit variant oncokb <id> helper
OPENFDA_API_KEY	Improves OpenFDA quota headroom
ORCID_ACCESS_TOKEN	Enables get author orcid:<id> and author papers orcid:<id>
S2_API_KEY	Enables authenticated Semantic Scholar quota
UMLS_API_KEY	Enables optional discover cross-vocabulary enrichment

Operator Data and Cache Knobs

Variable or file	Purpose
BIOMCP_CACHE_DIR	Overrides the BioMCP cache root
BIOMCP_CACHE_MODE	Cache behavior; infinite serves cached replies without expiration or revalidation, including GWAS and openFDA day-cache entries
BIOMCP_CACHE_MAX_AGE	Optional cache age limit, as a positive integer number of seconds
BIOMCP_CACHE_MAX_SIZE	Optional cache size limit
BIOMCP_CACHE_MIN_DISK_FREE	Minimum free disk budget before cache eviction
BIOMCP_DEFAULT_ASSEMBLY	Preferred genome assembly when a source returns equally supported GRCh37 and GRCh38 identities; accepts GRCh37 or GRCh38 and defaults to GRCh38
BIOMCP_STUDY_DIR	Local cBioPortal-style study dataset root
BIOMCP_DDINTER_DIR	Local DDInter download bundle root
BIOMCP_EMA_DIR	Local EMA human-medicines download root
BIOMCP_WHO_DIR	Local WHO Prequalification download root
BIOMCP_CVX_DIR	Local CDC CVX/MVX download root
BIOMCP_GTR_DIR	Local GTR download root
BIOMCP_GENCC_DIR	Private durable GenCC normalized-dataset root; defaults to the platform data directory under biomcp/gencc
BIOMCP_WHO_IVD_DIR	Local WHO IVD download root
BIOMCP_CA_BUNDLE	PEM bundle of extra trusted TLS roots for ordinary provider HTTPS; SSL_CERT_FILE is the fallback
BIOMCP_VARIANT_QUERY_GENE_ROUTING	Source that recognizes a gene-symbol first token in a free-text search variant phrase; mygene (default) or off
cache.toml	Persistent cache defaults under the resolved config root
RUST_LOG	stderr tracing filter; default CLI behavior is quiet, and tools/biomcp-ci sets error

Cache runtime precedence is environment, then cache.toml, then built-in default. The resolved root contains the managed HTTP response cache in http/, the ten-minute article-search loop-breaker records in sessions/, and the thirty-day directed citation-evidence sidecar in citation-evidence/. Cache reads, writes, statistics, and maintenance physically remove entries older than max_age_secs; opening the session store removes expired sessions. The automatic start-up clean runs at most once a day, and biomcp cache clean runs it now; BIOMCP_CACHE_MODE=off skips the start-up clean entirely. BioMCP creates managed directories and files with access limited to the current OS user. On Unix this means 0700 directories and 0600 files. HTTP cache startup repairs the root directory every time and secures the existing tree once, when its .tree-secured-v1 marker is missing or invalid. After that marker exists, startup does not walk the tree or repair permissions broadened later on its children. BioMCP repairs managed paths when it opens them for writing; reads do not repair broadened child permissions. It refuses linked regular files rather than risking access through another pathname. The global --no-cache flag bypasses these HTTP and session stores completely for one invocation. It does not override explicit output paths or provider retention. In particular, it neither deletes nor force-refreshes the GenCC durable dataset; use biomcp gencc sync for explicit revalidation. BIOMCP_CACHE_MAX_AGE overrides [cache].max_age_secs; both values are positive integer seconds. GWAS Catalog queries, openFDA label searches, and openFDA adverse-event counts are held for a day: a repeat inside that window is answered from the cache and the next request goes back to the provider.

Ordinary provider HTTPS trusts the bundled webpki roots plus any operator PEM bundle. BIOMCP_CA_BUNDLE is read first, and a blank or whitespace-only value counts as unset. SSL_CERT_FILE is read only when BIOMCP_CA_BUNDLE is unset; a blank, unreadable, or unparseable SSL_CERT_FILE warns and continues. An unparseable fallback is dropped whole, good certificates included, and the command runs with the bundled roots. A missing, unreadable, malformed, or certificate-less BIOMCP_CA_BUNDLE fails the command before any request and names the path in both text and --json errors. The bundle only adds roots: certificate verification and the bundled roots stay in place. Client certificates, mTLS, and SSL_CERT_DIR are out of scope for ordinary providers. AlphaGenome's separate gRPC client does not use BIOMCP_CA_BUNDLE; when set, SSL_CERT_FILE and SSL_CERT_DIR replace its native OS trust source. Wiring BIOMCP_CA_BUNDLE into that client requires retained PEM bytes and remains future work. BioMCP resolves and parses the ordinary-provider bundle once per process, so set it before startup and restart BioMCP after rotating it.

Free-text search variant "GENE condition" routes the first token to the gene filter only after the BIOMCP_VARIANT_QUERY_GENE_ROUTING source confirms it is the gene's official symbol. The supported default is mygene: MyGene confirms a first token only when a unique entrez-backed row carries it as the official symbol, and refuses aliases, so phrases such as 'HCC liver cancer' (HYCC1), 'MODY diabetes' (HNF4A), and 'HHT telangiectasias' (ACVRL1) keep the whole-phrase condition search; no offline gene list ships with BioMCP. The discover path keeps its separate symbol/alias lookup. A refused, ambiguous, timed-out, or unavailable lookup keeps the whole phrase as the condition search and prints the condition search without the leading word when that search returns zero rows, because the gene filter needs the official symbol the lookup did not confirm. off restores the whole-phrase condition search without the routing lookup.

Internal and Measurement Controls

Variable	Purpose
BIOMCP_GENE_GET_STRATEGY	Internal gene retrieval strategy control used for measurement and rollout comparisons
BIOMCP_GENE_OPTIONAL_TIMEOUT_MS	Internal timeout, in milliseconds, for optional gene enrichment branches
BIOMCP_GENE_TIMING_PATH	Internal measurement output path; when set, gene retrieval may write a local JSON timing report to that caller-provided path

Test and Fixture Override Seams

BIOMCP_*_BASE, BIOMCP_*_URL, and fixture process variables are internal fixture overrides unless this page lists them in an operator section. They let BioMCP's own verification harness redirect a source to a local server or fixture file. Do not treat those base-URL overrides as stable operator API.

Known examples include BIOMCP_CSPEC_FIXTURE_ORIGIN (an exact loopback origin for the runner-owned CSpec fixture), BIOMCP_ALPHAGENOME_BASE, BIOMCP_CANCERHOTSPOTS_BASE, BIOMCP_CBIOPORTAL_BASE, BIOMCP_CBIOPORTAL_DATAHUB_BASE, BIOMCP_CELLOSAURUS_BASE, BIOMCP_CHEMBL_BASE, BIOMCP_CIVIC_BASE, BIOMCP_CLINVAR_BASE, BIOMCP_CLINGEN_BASE, BIOMCP_CLINGEN_CAR_BASE, BIOMCP_CLINGEN_EREPO_BASE, BIOMCP_COMPLEXPORTAL_BASE, BIOMCP_CPIC_BASE, BIOMCP_CTGOV_BASE, BIOMCP_CTGOV_CDN_BASE, BIOMCP_DBSNP_BASE, BIOMCP_DGIDB_BASE, BIOMCP_DISGENET_BASE, BIOMCP_EMA_REPORT_BASE, BIOMCP_ENRICHR_BASE, BIOMCP_EUROPEPMC_BASE, BIOMCP_FDA_ORPHAN_BASE, BIOMCP_FIGSHARE_BASE, BIOMCP_GNOMAD_BASE, BIOMCP_GPROFILER_BASE, BIOMCP_GTEX_BASE, BIOMCP_GWAS_BASE, BIOMCP_HPA_BASE, BIOMCP_HPO_BASE, BIOMCP_INTERPRO_BASE, BIOMCP_KEGG_BASE, BIOMCP_LITSENSE2_BASE, BIOMCP_LITVAR_BASE, BIOMCP_MEDLINEPLUS_BASE, BIOMCP_MONARCH_BASE, BIOMCP_MUTALYZER_BASE_URL, BIOMCP_MYCHEM_BASE, BIOMCP_MYDISEASE_BASE, BIOMCP_MYGENE_BASE, BIOMCP_MYVARIANT_BASE, BIOMCP_NCBI_IDCONV_BASE, BIOMCP_NCI_CTS_BASE, BIOMCP_NIH_REPORTER_BASE, BIOMCP_OLS4_BASE, BIOMCP_ONCOKB_BASE, BIOMCP_OPENCITATIONS_BASE, BIOMCP_OPENFDA_BASE, BIOMCP_OPENTARGETS_BASE, BIOMCP_ORCID_BASE, BIOMCP_PHARMACODB_BASE, BIOMCP_PHARMGKB_BASE, BIOMCP_PMC_HTML_BASE, BIOMCP_PMC_OA_BASE, BIOMCP_PUBMED_BASE, BIOMCP_PUBTATOR_BASE, BIOMCP_QUICKGO_BASE, BIOMCP_REACTOME_BASE, BIOMCP_S2_BASE, BIOMCP_SEER_BASE, BIOMCP_STRING_BASE, BIOMCP_UMLS_BASE, BIOMCP_UNIPROT_BASE, BIOMCP_VAERS_BASE, BIOMCP_VARIANTVALIDATOR_BASE_URL, BIOMCP_WIKIPATHWAYS_BASE, BIOMCP_WHO_PQ_URL, BIOMCP_WHO_PQ_API_URL, BIOMCP_WHO_VACCINES_URL, BIOMCP_WHO_IVD_URL, BIOMCP_GTR_TEST_VERSION_URL, BIOMCP_GTR_CONDITION_GENE_URL, BIOMCP_CVX_URL, BIOMCP_CVX_TRADENAME_URL, and BIOMCP_MVX_URL. Internal cBioPortal fixture/source-selection seams include BIOMCP_CBIOPORTAL_STUDY, BIOMCP_CBIOPORTAL_SAMPLE_LIST, and BIOMCP_CBIOPORTAL_MUTATION_PROFILE.

Release and Install Variables

Variable	Purpose
BIOMCP_BIN	Selects a built binary for spec wrappers and local demos
BIOMCP_GITHUB_REPO	Installer repository override
BIOMCP_INSTALL_DIR	Installer destination override
BIOMCP_TAG	Release/tag helper override
BIOMCP_VERSION	Installer/version override
BIOMCP_SPEC_CACHE_HIT	Spec wrapper hint that enables replay-style cache mode when unset by the caller

Observability and Degradation

Variable	Purpose
BIOMCP_DISABLE_SOURCES	Comma- or pipe-separated source ids or group names to turn off; --disable-sources passes the same list for one invocation
BIOMCP_DISABLE_KEGG	Legacy alias for BIOMCP_DISABLE_SOURCES=kegg; set to 1 to turn off KEGG

Disabling sources by name or group

--disable-sources and BIOMCP_DISABLE_SOURCES take a comma- or pipe-separated list of source ids and group names, matched case-insensitively with surrounding whitespace trimmed: --disable-sources kegg,enrichr and BIOMCP_DISABLE_SOURCES=kegg|enrichr behave identically, and the CLI and the MCP server read the same setting. biomcp serve and biomcp serve-http accept --disable-sources before the subcommand, so one server run keeps the list for every tool call exactly as a one-shot command does. An unknown id or group name is an error that lists the valid names. Valid ids come from sources.json; the groups are commercial-restricted, license-required, and non-commercial, drawn from each source's recorded commercial terms in that file rather than from a list in code. A disabled source is never called, its fields are dropped when another service carries them (for example, gene records show no KEGG pathway names while kegg is off), biomcp health lists every disabled source with the setting that turned it off, and the MCP server's description names them for its clients. Sources that need a key stay off without one regardless of this setting.

• Human-facing diagnostics and tracing go to stderr, never JSON stdout.
• JSON query responses use _meta.source_status where a command has structured source availability/auth state to expose.
• biomcp health --apis-only reports API/source connectivity and excluded key-gated rows; full biomcp health also reports local runtime data and cache readiness.
• Optional entity lookups expose typed outcomes in JSON/MCP. disabled names an operator setting and offers no retry; inapplicable means a required input was absent and no provider was contacted; empty is a successful zero-result query; unavailable means retrieval produced no usable result; and degraded preserves partial evidence. _meta.section_sources repeats requested section outcomes and credits only providers that returned usable evidence. Outcome-only helpers such as variant structure may expose the same state model on their documented status surface.
• SourceUnavailable means the source is supported but temporarily unavailable. It is distinct from unsupported sections or invalid command grammar. A source disabled through --disable-sources/BIOMCP_DISABLE_SOURCES is reported as disabled, not unavailable, and names the setting to change.