@cyanheads/brapi-mcp-server
A collaborative BrAPI v2.1 workspace for multi-agent research via MCP. Search studies, germplasm, genotypes, and more across Breedbase, T3, Sweetpotatobase, and any BrAPI v2-compliant server.
26 Tools • 6 Resources • 2 Prompts
Overview
Plant-breeding data from any BrAPI (Breeding API) v2 server — Breedbase instances like Cassavabase and Sweetpotatobase, the Triticeae Toolbox (T3), and more, several at once. Search studies, germplasm, observations, and genotypes, walk pedigrees, and build phenotype and genotype matrices, with large results queryable in SQL.
Tools
Resources
Every resource reads the default connection and mirrors a tool; tool-only clients and multi-server workflows use the tools.
Prompts
Capability reference
Identifier filters also accept their BrAPI *DbId / *DbIds spellings where equivalent: for example, imageDbId for imageDbIds, studyDbIds for studies, and observationVariableDbIds for variables. Array filters accept a lone string or multiple IDs. Supply one spelling per filter; conflicting spellings are rejected.
brapi_connect tool
baseUrl and auth are optional: omitted values come from BRAPI_<ALIAS>_* env vars, the built-in aliases, then BRAPI_DEFAULT_* (see Per-alias credentials); alias (default default, pattern ^[a-zA-Z0-9_-]+$) keeps several servers registered at once; auth.mode is none, bearer, api_key, sgn (Breedbase /token exchange), or oauth2 (client credentials)
- Returns the orientation envelope:
server identity, auth summary, capabilities (supported, notableGaps), active dialect, content counts, attribution for built-in servers, and nextToolSuggestions naming the entry-point finders this server can serve
- Typed errors:
auth_session_required, auth_base_url_mismatch, alias_base_url_unset, alias_base_url_invalid, private_address_blocked, auth_token_exchange_failed, auth_no_access_token, upstream_unauthorized, upstream_forbidden, capability_discovery_unavailable (retryable); a failed connect leaves any earlier registration under the alias intact
- When both discovery routes return HTTP 404,
capability_discovery_not_found asks for the full BrAPI base URL, including its version prefix. A root URL gets a candidate ending in /brapi/v2.
- Optional for an alias the server has a URL for (
default when BRAPI_DEFAULT_BASE_URL is set, a built-in, or a BRAPI_<ALIAS>_BASE_URL alias): any other tool or resource connects it on first use, as brapi_connect with no baseUrl or auth would, and concurrent first calls share one connect. An alias with no URL of its own still fails unknown_alias, even with BRAPI_DEFAULT_* set, so a mistyped alias never reaches the default server. Those tools and resources declare the connect failures they can hit (the token, discovery, auth-wall, alias_base_url_invalid, and private_address_blocked errors above), each with a recovery hint
brapi_server_info tool
alias optional; forceRefresh (default false) refetches the capability profile instead of reading the cache
- Returns the same orientation envelope as
brapi_connect
brapi_describe_filters tool
endpoint is one of studies, germplasm, observations, variables, images, variants, locations; unknown_endpoint carries availableEndpoints
- Each filter has
name, type, description, and example; the catalog follows the v2.1 spec, and individual servers may honor a subset
brapi_find_studies tool
- Filters:
crop, trialTypes, seasons, locations, programs, trials, studyNames, variables (studies that recorded those variable IDs), active; on SGN servers (CassavaBase, Breedbase, Sweetpotatobase), which ignore the location filter on /studies, locations is applied client-side over the scanned studies, and totalCount is the matched count
distributions over programName, studyType, seasons, locationName, commonCropName
variables has no per-row check, so it is verified by count: the same request without it must report a larger total, otherwise a warning says "Could not verify whether 'variables' narrowed the study results." (also when the total can't be compared, as with a multi-request GET union)
- SGN/Breedbase studies lift missing program IDs and names from
additionalInfo, preserving the raw metadata.
brapi_get_study tool
studyDbId required; resolves program, trial, and location inline through GET /{noun}/{id} when the server advertises it (a list filter by ID otherwise); a record the server doesn't return is omitted with a warning naming the noun and ID; study_not_found when the upstream has no such study
- On SGN/Breedbase servers, missing program fields come from
additionalInfo; when the study has no program ID, the fetched parent trial can supply it for program resolution.
- Companion counts
observationCount, observationUnitCount, variableCount; a count the server can't scope to the study is omitted with a warning, never reported as the server-wide total
brapi_find_germplasm tool
- Filters:
names, germplasmDbIds, germplasmPUIs, accessionNumbers, crops, synonyms, collections, genus, species; text is a client-side substring match on name, PUI, accession, display name, and synonyms that drops non-matching rows. Its first request uses BRAPI_PAGE_SIZE independently of inline loadLimit; it scans every upstream row when the set fits one dataframe walk (50,000 rows at the default page size). Above that, a first-page miss stops after one request and reports the actual rows scanned; it does not establish absence from the catalog, so pair it with a server-side filter.
- Use
studies, trials, or programs to scope the result. When the finder has a total from a single route, bounded count probes compare each scope with the same filters minus that scope. A lower count confirms narrowing. Equal, unavailable, or inconclusive counts leave the scope unverified and appear in warnings.
distributions over commonCropName, genus, species, collection, countryOfOriginCode
brapi_get_germplasm tool
germplasmDbId required; returns attributes and direct parents; germplasm_not_found when the upstream has no such germplasm
- Companion counts
studyCount, directParentCount, directDescendantCount
brapi_walk_pedigree tool
- Supply at least one
germplasmDbIds value (germplasmDbId also accepted). The first 20 distinct roots are walked in input order. Pass deferredRoots into a follow-up call.
direction is ancestors (default), descendants, or both. maxDepth defaults to 3 and positive values above 10 use 10, reported in the output. The walk stops at 1,000 nodes or 10,000 edges and sets truncated.
both is the union of the two walks: ancestors expand only through /pedigree and descendants only through /progeny, so a descendant's other parent is not pulled in
- One edge per parent–child pair;
cycleCount counts the edges marked isCycle, where a germplasm becomes its own ancestor — shared ancestors and siblings are not cycles
leafCount counts graph terminals, including depth-boundary nodes; confirmedLeafCount counts non-root nodes whose relevant lookups successfully returned no relatives. frontier / frontierCount distinguish depth-limited, safety-skipped, failed and unsupported directions; deadEndCount still counts nodes with failed lookups
nodes and edges each fit loadLimit and a 24,000-byte budget for both array JSON and serialized rendered rows. Trimmed previews retain the discovered graph in nodesDataframe and edgesDataframe; a first row over budget yields zero inline rows. Preview trimming never changes traversal truncated
- Safety-capped graph tables are marked
truncated and contain only discovered nodes/edges. knownOmittedRelativeCount and omittedRelativesDataframe retain already-fetched omitted relatives with germplasmDbId, expansionNodeDbId, side and ordinal; unrequested directions have unknown counts. Large frontiers also stage a frontierDataframe
- Retrieve omitted IDs with
SELECT germplasmDbId, expansionNodeDbId, side FROM <table> ORDER BY ordinal LIMIT 20 OFFSET 0, advance by rows actually shown, then walk those IDs in batches of up to 20 roots. If zero fit, narrow the projection or aggregate; these tables do not resume traversal
diagram: "mermaid" | "dot" adds the discovered graph (including rows beyond the preview), with partial coverage when safety-capped; edges are drawn parent → child and loop-closing edges dashed. Either format is left out with a warning past 50,000 characters, and Mermaid past 500 edges
brapi_find_variables tool
- Filters:
variables, variableNames, variablePUIs, traitClasses, ontologies, studies, methods, scales, crop. Multiple distinct studies are unioned by variable ID with studyDbIds provenance under one shared page, row and time budget. studyCoverage reports complete, partial, failed and unprocessed studies; successful studies remain available when another fails.
text ranks every fetched row and moves matches to the top without dropping the rest; every match leads results[] in rank order and carries textMatchRank (in results and the staged dataframe), and textMatchCount counts the matches among fetched rows. ontologyCandidates lists the top 10 (ranks 1–10), each with source (puiMatch, nameMatch, synonymMatch, traitClassMatch)
- Exact PUI matches lead, then exact normalized names. Equally scored name matches favor the shorter normalized name. Matching ignores a trailing pipe-delimited PUI when it matches the record's PUI. Returned names retain the original text.
distributions over ontologyDbId, traitClass, scaleName
brapi_find_observations tool
- Filters:
studies, germplasm, variables, observationUnits, observations, seasons, programs, trials, observationLevels, timestampFrom / timestampTo
- Study- or germplasm-scoped SGN/Breedbase queries use advertised
/observationunits?includeObservations=true, preserving zero-valued measurements. Unit totals drive paging; child fields take precedence over inherited unit metadata, and repeated observation IDs are counted once. Observation-level filters are checked after flattening; appliedFilters separates upstream requests from client-side criteria on both output surfaces
- Outside that embedded-unit route, a GET query with no
studies, trials, observationUnits, or observations anchor runs a one-row count probe first and skips the bulk pull when the probe fails or reports more than 5,000 matches; warnings says so. Germplasm predicates are checked before staging, and counts describe confirmed matches. When collection cannot proceed, brapi_germplasm_performance can supply contributing study IDs for a study-scoped retry
distributions over observationVariableName, studyName, germplasmName, observationLevel, season (labeled by seasonDbId, else name plus year, else name, else year)
brapi_federated_find tool
- Pass
aliases and query: { entity, filters }. The entity is studies, germplasm, or observations. Use the canonical names in the entity's filters schema (for example, studies). BrAPI ID aliases apply only at the top level of standalone finder calls. Pass the filters and set the merged preview's loadLimit at the top level.
- Rows retain
sources with each source's alias, local DbId, and record. Germplasm groups across aliases only when an exact nonblank PUI occurs once per contributing alias. conflicts names fields whose non-null values differ. Equal local IDs or names alone leave the records separate.
- Check
coverage for partial, failed, or skipped aliases. collectedCount counts source rows and mergedCount counts grouped output rows, including rows staged when the inline preview is cut. Interpret these counts within the reported coverage.
brapi_find_images tool
- Filters:
images, observationUnits, observations, studies, imageFileNames, mimeTypes, descriptiveOntologyTerms; returns metadata only, with bytes via brapi_get_image
- MIME predicates are checked case-insensitively before staging. Contradictions and rows with missing MIME metadata are excluded and disclosed separately; incomplete scans cannot establish that no upstream match exists
- With MIME verification,
totalCount counts confirmed matches in the scan; upstreamTotalCount retains the upstream total when available
distributions over mimeType, studyName, observationUnitName, descriptiveOntologyTerms
brapi_get_image tool
- Supply at least one
imageDbIds value. The first five distinct IDs are fetched in input order, up to 20 MB each. Pass deferredImageDbIds into a follow-up call. images_unsupported fires when the server doesn't advertise /images.
- Each image's
source is imagecontent or the imageURL fallback. Both sources require an effective image/* MIME type (case and parameters normalized; metadata is used when the byte response has no type). Non-image responses and fetch failures land in per-image errors[]; successful siblings still return
- Bytes appear once as
content[] image blocks. images[] carries metadata, MIME, byte size and source only; format() renders metadata without repeating base64
brapi_find_locations tool
- Filters:
locations, locationNames, countryCodes (alphabetic codes uppercased; numeric upstream codes preserved), countryNames (English names resolved to alpha-3; on SGN-family servers (CassavaBase, Sweetpotatobase, Breedbase) a name also sends alpha-2, ISO numeric, and the E.164 calling code, and a row matched only by a numeric code is kept when its countryName names the requested country, dropped when it names another, and kept with a warning when it doesn't resolve; explicit countryCodes are never re-checked, and totalCount, distributions, and staging reflect the check), locationTypes, abbreviations; unresolved names fail unless an effective country-code restriction remains. Optional bbox applies before staging; a nonempty box requires all four ordered bounds (minLat, maxLat, minLon, maxLon) or fails before location retrieval. An empty box is omitted.
distributions over countryCode, locationType; GeoJSON uses [longitude, latitude] by default. The BrAPI test-server dialect declares swapped Point coordinates, reported as coordinateAxisOrder: "swapped" with or without a bbox. Axis order never depends on the requested box or preview size
brapi_find_variants tool
- Filters:
variantSets, variants, references, and a genomic region of referenceName + start (inclusive) / end (exclusive), 0-based
- Reference and overlapping half-open region predicates are verified before staging. Contradictions and records without enough location metadata are excluded and disclosed separately; touching interval endpoints do not overlap
- Empty or reversed windows return no matches without fetching variant rows. During region verification,
totalCount counts confirmed matches in the scan and upstreamTotalCount retains the upstream total when available
distributions over variantType, referenceName, variantSetDbId
brapi_find_genotype_calls tool
- Needs at least one of
variantSetDbId, variantSetDbIds, germplasmDbIds, callSetDbIds, variantDbIds (no_filters otherwise); optional callFormat (VCF, FLAPJACK, DARTSEQ, JSON)
- Variant sets are listed by
brapi_raw_get({ path: "/variantsets" }), optionally with params.studyDbId; on Breedbase-family servers they belong to genotyping projects that brapi_find_studies does not list
distributions over callSetName, variantName, variantSetDbId, plus the server's callFormatting; search_endpoint_disabled when the active dialect marks POST /search/calls as dead
- The upstream pull stops at
BRAPI_GENOTYPE_CALLS_MAX_PULL (default 100,000) and sets truncated. When the shared upstream deadline stops a pull after the first page, collected calls remain available, hasMore is set, and warnings explains the stop. loadLimit and the 24,000-byte inline budget bound the preview, with shown / cap reporting the cut and every collected call staged.
- Scalar upstream
genotype.values become single-element arrays in finder results and staged calls. They retain their values; a bare numeric scalar alone does not establish an allele call
brapi_dataframe_describe tool
dataframe optional: omit to list every dataframe, or name one for columns, row count, and provenance (originating tool, baseUrl, query, expiry), which only auto-registered df_* tables carry
- On an HTTP deployment where every caller shares the
default tenant, listing without a name works inside an MCP session when BRAPI_SESSION_ISOLATION=true, and shows only that session's dataframes; a session-less request, or any request with isolation off, fails with list_all_disabled_on_shared_http
brapi_dataframe_query tool
sql is one read-only statement. Use SELECT for rows and aggregation, DESCRIBE or SHOW for a known table or query, and SUMMARIZE for column statistics. SQL refusals carry a specific data.gateReason under sql_rejected. Qualify a column named current_schema with its table alias. Use different column, alias, CTE, or table names for identifiers reserved by the system-catalog gate.
- A query that fails on the data (a cast that does not convert) fails as
sql_execution_error, a dataframe name that no longer exists as missing_table, and a registerAs name already in use as register_as_clash
- Returns
rowCount, typed columns, and leading rows bounded by preview, rowLimit, and BRAPI_CANVAS_MAX_ROWS, each clamped to the next, then 24,000 bytes on each serialized row array and rendered row section (escaping and markers included). shown is the delivered count; cap remains the effective row ceiling. An oversized first row returns zero rows: use a narrower projection or aggregation
registerAs (identifier, ≤63 characters) saves the full result as a new dataframe for chaining
- Page persisted results with deterministic
ORDER BY and LIMIT/OFFSET, advancing the offset by rows actually returned, not the requested limit. Without registerAs, rerun with it before paging a saved result
brapi_dataframe_drop tool
dataframe required; returns dropped: false, not an error, for an unknown name
- Registered only when
BRAPI_CANVAS_DROP_ENABLED=true
brapi_dataframe_export tool
format is csv, parquet, or json; optional columns or sql (mutually exclusive) and filename (no path separators or ..; omit for a timestamp-suffixed default); returns the absolute path, sizeBytes, and rowCount
- Typed errors:
export_dir_unset, dataframe_not_found, invalid_filename, mutually_exclusive_projection
- Registered only over stdio with
BRAPI_EXPORT_DIR set
brapi_build_phenotype_matrix tool
studies required (≥1), optional variables / germplasm subsets; shape wide (default) or long; aggregate mean (default), median, first, or all (always long form); loadLimit caps matching observations per study, defaulting to 50,000 independently of the finder preview setting
- Pages each study's observations against the upstream total, preferring embedded observation units on SGN/Breedbase when advertised so zeros are retained; unit totals count raw units, while
loadLimit counts matching observations. Other servers retain the /observations and fallback paths. Study / variable / germplasm subsets are checked on returned rows
extraFilters are forwarded, then checked against the rows the matrix is built from, as on brapi_find_observations: warnings names a key the rows contradict and the keys no row can speak to
- Returns the matrix as a dataframe plus
observationCount, germplasmCount, variableCount, and variableLegend mapping SQL-safe column names to variable names; truncated / cap flag a study whose scan stopped before its total (at loadLimit, the page cap, a failed, empty, or repeated page, or the call deadline) and the notice names it with the rows examined
- Long rows retain observation and unit IDs, germplasm name, season, and available field design from embedded units. A season is labeled by its
seasonDbId, else name plus year, else name, else year. Use designLegend to map relationship columns to their original design levels. replicateIndex is encounter order.
- Wide cells pool observations across studies.
countLegend maps each value column to its count column, which counts numeric values used by mean or median, one value when first has a row, and zero when no value contributes.
studies retains the requested IDs; coverage.studies distinguishes contributed, empty, failed, partial, and unprocessed outcomes with collected counts. coverage.partial and truncated disclose failed or incomplete pulls on both output surfaces. A failed study does not prevent the others from building the matrix; the call fails only when every study failed. no_observation_path when the server exposes neither observation route
brapi_germplasm_performance tool
germplasmDbId required; SGN/Breedbase uses advertised germplasm-scoped embedded units, walking their raw total without the study-discovery cap. Other servers discover up to 200 studies. Explicit studyDbIds skips discovery and restricts collection to those studies; optional variables subset; germplasm_not_found when the upstream has no such germplasm
perVariable rows carry n, mean, median, sd (omitted when n < 2 or non-numeric), min, max, studyCount, studyDbIds, and seasons (labeled by seasonDbId, else name plus year, else name, else year)
studyCount / studyDbIds remain contributors only. Additive coverage distinguishes contributed, empty, failed, partial, and unprocessed studies; scoped-unit scans report raw units, pages, total when known, and completion. An incomplete unit walk cannot establish the unseen study count. Repeated observation IDs are counted once; distinct-ID replicates and zero values remain. Optional loadLimit caps matching observations per study, defaulting to 50,000 on explicit and discovered study paths; page, observation, and deadline limits are disclosed, and deadline-skipped studies receive one count warning
truncated: true identifies incomplete observation scans; coverage.partial also covers failed studies
brapi_export_genotype_matrix tool
variantSetDbId required (no_filters otherwise; list sets with brapi_raw_get({ path: "/variantsets" })), optional germplasmDbIds and variantDbIds (alias variantDbId; calls the server returns for other variants are left out); format is matrix-json, vcf-lite (adds vcf text), or plink (adds ped / map text), and every format registers the call set × variant dataframe
- Rows are call sets (one sample's calls), led by
callSetDbId, callSetName, and germplasmDbId. The germplasm is resolved through the call set's sample by batch lookups; it is null when unresolved, with a warning saying so. Join to brapi_build_phenotype_matrix on germplasmDbId; a germplasm with several call sets joins once per call set.
variantColumnLegend maps SQL-safe column names back to variant IDs. When the set has more variants than maxColumns, the matrix keeps that many columns (listed in variantColumnLegend), sets truncated, and the warning says to pass the remaining variants as variantDbIds (from brapi_find_variants) in further calls; search_endpoint_disabled when the active dialect marks POST /search/calls as dead
- VCF POS and PLINK base-pair positions are one-based: valid zero-based BrAPI
start values 0 and 500 export as 1 and 501. Missing or invalid positions retain . (VCF) / 0 (PLINK) placeholders.
- PLINK allele indices use available REF/ALT labels, or positive numeric labels when metadata cannot resolve the marker. Missing calls use
0 0. Ambiguous numeric scalar calls remain verbatim in the raw dataframe but export as missing in VCF-lite and PLINK, with a warning; dosage is not inferred into an allele genotype
- An empty call search returns a queryable zero-row dataframe with its
callSetDbId, callSetName, and germplasmDbId columns and no-match guidance
maxCalls / maxColumns can lower the configured BRAPI_GENOTYPE_CALLS_MAX_PULL / BRAPI_GENOTYPE_MATRIX_MAX_COLUMNS ceilings. truncated means a ceiling or the shared upstream deadline ended the pull early, and warnings names the cause.
brapi_submit_observations tool
studyDbId plus 1–5,000 observations; a row with observationDbId updates via PUT, one without creates via POST, and nothing is deleted
mode: "preview" (default) returns valid, invalid, routing counts, and perRowWarnings without writing; mode: "apply" asks the caller to confirm (force: true skips it) and writes only on the round that redeems the server's record of that prompt, for the same caller, server, study, and rows — a pre-supplied or replayed answer is asked again — and returns posted, updated, and studyObservationCount (omitted with a warning when the server can't scope /observations to the study); failures are observations_unsupported, study_not_found, post_unsupported, put_unsupported, and user_declined
- Review
perRowWarnings for values that conflict with a declared scale and units, or for variables, units, or update targets outside the study. flagged counts each warned row once and appears in the apply confirmation. Review scan-level warnings for incomplete checks. Advisory findings leave the existing validity and write routing intact.
- Registered only when
BRAPI_ENABLE_WRITES=true; requires the brapi:write:observations scope
brapi_raw_get tool
path is a relative route such as /samples (a full URL fails as cross_origin_path); optional params and loadLimit
- Returns the envelope (
url, metadata, result) plus a suggestion when a curated tool covers the endpoint or takes the IDs it lists. List previews (result arrays or result.data) fit loadLimit and 24,000 bytes on each serialized row array and rendered row section, markers and escaping included; non-list results and envelope siblings are preserved. Every fetched row omitted inline stays staged, including an oversized first row that leaves zero inline rows
params.page / params.pageSize fetches only the requested upstream page; a trimmed page is staged without walking more pages. SQL offsets page that staged table independently of upstream pagination: use deterministic ORDER BY, advance by actual rows shown, and use a narrower projection when zero rows fit
brapi_raw_search tool
noun (e.g. observations, calls, germplasm) and a body posted verbatim to POST /search/{noun}; async searches are polled to completion
- Returns
kind (sync or async), searchResultsDbId, result, and a suggestion; previews and stages like brapi_raw_get, with body.page / body.pageSize restricting collection to the requested upstream page; search_endpoint_disabled when the active dialect marks the route as dead
brapi://server/info resource
- Orientation envelope for the
default connection as application/json
- Same payload as
brapi_server_info called with no arguments
brapi://calls resource
- Capability profile for the
default connection: supported services with their HTTP methods and versions, plus crops
- Reflects what
/serverinfo + /calls returned at the last load
brapi://study/{studyDbId} resource
- Same payload as
brapi_get_study on the default connection
study_not_found when the upstream has no such study
brapi://germplasm/{germplasmDbId} resource
- Same payload as
brapi_get_germplasm on the default connection
germplasm_not_found when the upstream has no such germplasm
brapi://filters/{endpoint} resource
- Same payload as
brapi_describe_filters; unknown_endpoint for an endpoint outside the catalog
- Listing
brapi://filters returns one resource per endpoint
brapi://variable/{observationVariableDbId} resource
- The
/variables/{id} record (trait, scale, method, ontology) on the default connection
variable_not_found when the upstream has no such variable
brapi_eda_study prompt
- Arguments:
studyDbId required; alias optional
- Returns one user message: a six-step playbook (orient, variables, coverage, missing data, IQR outliers, optional pedigree walk) ending in a markdown report with recommended next steps
brapi_meta_analysis prompt
- Arguments:
germplasmDbIds (comma-separated) and traitName required; alias optional, run once per alias for multi-server analyses
- Returns one user message: a seven-step playbook (resolve the trait, discover studies, build the observation table, harmonize scales, summarize per study and across studies, optional pedigree walk) ending in a report that cites every dataframe handle or filter map used
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
BrAPI-specific:
- Shared finder contract: the seven filter finders (studies, germplasm, variables, observations, images, locations, variants) take
alias, loadLimit, and extraFilters (keys from brapi_describe_filters), and return results, hasMore, distributions, and an optional dataframe handle; results stops at loadLimit or 24,000 bytes on either array JSON or serialized escaped row text, whichever binds first, retaining the first matched row even when it alone exceeds the budget. truncated / shown / cap report the cut
- Dataframe spillover: when
results holds fewer rows than matched, finders stage the matched set (paging the rest of the result, up to 50 pages and 50,000 rows) in a DuckDB df_<uuid> table and return its handle
- Dialect adapters (
spec, brapi-test, breedbase, cassavabase, bms), detected per connection, translate v2.1 plural filters into the form each server family honors, drop filters it ignores, and switch to POST /search/{noun} when a GET would narrow a multi-value filter; BRAPI_<ALIAS>_DIALECT pins one
- When a compatible POST search is unavailable, finders can split a scalar-only GET into bounded requests and deduplicate their results by resource ID. Alternatives within one filter are ORed and different filters are ANDed. Check the warnings and coverage for combinations the scan could not complete.
- Several connections at once under named aliases, with three public Breedbase servers built in and credentials resolved per alias from env vars, so they stay out of the LLM context
- Capability-aware calls: each connection's
/serverinfo + /calls profile is cached and checked before a tool calls an endpoint; a per-connection concurrency cap and exponential-backoff retries cover 429/5xx
Agent-friendly output:
- Upstream names, identifiers, and advisory fields render as literal text. Structured values and generated pedigree diagrams retain their original semantics
- Typed failures: every connection-scoped tool and resource fails with
unknown_alias for an alias that is neither registered nor configured on the server (a configured alias connects on first use) and with private_address_blocked, caching and registering nothing, when its base URL is a private or reserved address the server may not reach; a filter finder fails with all_filters_dropped instead of widening to an unfiltered pull when the dialect drops every filter supplied, and brapi_build_phenotype_matrix fails with dialect_all_filters_dropped when the dialect drops the study filter for every requested study
- An empty or whitespace-only ID or filter value fails at the input schema instead of reaching the upstream, where a blank filter widens the pull and a blank ID malforms the request path; an empty
text still means no text filter
- Query echo on every finder:
totalCount, returnedCount, and appliedFilters; embedded observation pulls separate upstream requests from client-side criteria, and brapi_find_studies lists client-side locations separately. A refinementHint points at a complete dataframe or suggests narrower filters when the scan stopped short; empty results carry a notice, and warnings disclose limitations
- Graceful partial failure:
brapi_get_image returns per-image errors[] and warnings[] rows instead of failing the batch
- Discriminated outputs:
brapi_submit_observations returns a mode-discriminated result (preview / apply), brapi_raw_search reports kind, and brapi_get_image reports each image's source
Working with dataframes
When a finder's inline results holds fewer rows than matched — loadLimit or the 24,000-byte inline budget bound first — the response carries a dataframe handle: tableName, rowCount, columns, createdAt, and expiresAt. totalCount is the upstream total for unfiltered walks, the matched total for a complete locally filtered walk, and absent when a locally filtered scan is incomplete. truncated and warnings disclose a stopped walk, with maxRows when the row cap fired. Columns renamed to pass the SQL identifier check map back to their upstream keys in columnLegend.
Staging notices name the table and the tools to describe or query it. Finder previews stage collected matches when cut, including the merged collection from brapi_federated_find. Raw reads and pedigree walks stage fetched rows omitted from their previews. Matrices are staged for SQL. brapi_dataframe_export is available on configured stdio deployments.
Dataframe names are capability tokens, not row-level ACLs: anyone holding a name in the same session or tenant bucket (see Deployment shapes) can read its rows. Provenance lasts BRAPI_DATASET_TTL_SECONDS (default 24h); set BRAPI_CANVAS_DROP_ENABLED=true to expose brapi_dataframe_drop for explicit cleanup.
Getting started
Public Hosted Instance
A public instance is available at https://brapi.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:
Self-Hosted / Local
Add the following to your MCP client configuration file.
Or with npx (no Bun required):
Or with Docker:
For Streamable HTTP, set the transport and start the server:
No env vars are required: the built-in aliases (bti-cassava, bti-sweetpotato, bti-breedbase-demo) connect as-is, and brapi_connect accepts any other BrAPI v2 URL at runtime. For servers that need a login, set credentials as env vars so passwords, tokens, and keys stay out of the LLM context (see Per-alias credentials).
Prerequisites
- Bun v1.4.4 or higher (or Node.js v24+).
@duckdb/node-api, installed as a regular dependency, with prebuilt native bindings for macOS, Linux (glibc and musl), and Windows on x64 and arm64. Cloudflare Workers is not supported.
Installation
- Clone the repository:
- Navigate into the directory:
- Install dependencies:
- Configure environment:
Configuration
Every variable is optional.
See .env.example for the full list of optional overrides.
Per-alias credentials
brapi_connect fills baseUrl and auth from env vars when the agent omits them, in this order:
- Agent input, within the pairing rules below.
- Per-alias env vars:
BRAPI_<ALIAS>_*, uppercased with hyphens as underscores (my-server → BRAPI_MY_SERVER_*).
- Built-in aliases: see Built-in aliases.
BRAPI_DEFAULT_BASE_URL, for an alias with no URL or credentials of its own.
Env credentials go only to the server configured with them:
- An alias's credentials pair with its
BRAPI_<ALIAS>_BASE_URL, else its enabled built-in URL. A caller baseUrl that points elsewhere fails with auth_base_url_mismatch. Credentials with no URL of their own, including those left behind by a built-in disabled via BRAPI_BUILTIN_ALIASES_DISABLED, fail with alias_base_url_unset and are never sent to BRAPI_DEFAULT_BASE_URL.
BRAPI_DEFAULT_* credentials attach only when the resolved URL is BRAPI_DEFAULT_BASE_URL; an alias pointed anywhere else connects without auth unless it has credentials of its own. With no BRAPI_DEFAULT_BASE_URL set, default credentials fail with alias_base_url_unset.
URLs compare after normalizing host case, default ports, and trailing slashes. Caller-supplied auth is never mixed with env credentials.
Each alias carries one credential family, and the auth mode follows from which fields are set. Mixing families within an alias raises a ValidationError.
BRAPI_<ALIAS>_DIALECT pins the dialect adapter (spec, brapi-test, breedbase, cassavabase, bms) when detection picks the wrong one; auto or unset detects it.
The agent then calls brapi_connect({ alias: 'bti-cassava' }) with no baseUrl, no auth, and no secrets in the prompt, or skips that call: any tool given alias: 'bti-cassava' connects it the same way on first use.
Built-in aliases
These public BrAPI v2 endpoints connect with no configuration. Their orientation envelope carries license, citation, and homepage in an attribution block (Creative Commons Attribution).
The registry holds only servers verified for anonymous reads. Servers that require login, including the Triticeae Toolbox (T3) wheat, oat, and barley hosts, connect through BRAPI_<ALIAS>_BASE_URL plus credentials (see .env.example).
BRAPI_<ALIAS>_BASE_URL overrides a built-in URL, e.g. to point bti-sweetpotato at a staging mirror via BRAPI_BTI_SWEETPOTATO_BASE_URL. BRAPI_<ALIAS>_USERNAME and friends attach credentials on top of the built-in URL; each Breedbase instance has its own user table, so write access needs a separate account on each. BRAPI_BUILTIN_ALIASES_DISABLED=bti-cassava,bti-breedbase-demo removes entries.
Citation: all three built-ins reference Morales et al. 2022, "Breedbase: a digital ecosystem for modern plant breeding." G3 12(7): jkac078. doi:10.1093/g3journal/jkac078.
Running the server
Local development
Docker
The image defaults to HTTP transport, stateful session mode, and logs to /var/log/brapi-mcp-server. OpenTelemetry peer dependencies are installed by default; build with --build-arg OTEL_ENABLED=false to omit them.
Deployment shapes
Two kinds of state scope by tenant and, by default, by MCP session: connection state (registered aliases and exchanged upstream tokens) and dataframes (df_<uuid> tables, usable by anyone who holds the name within its bucket). Three configurations set where those buckets end:
Stdio is always a single session. Clients on MCP protocol revision 2026-07-28 carry no session on any transport, so outside the per-user-credentials shape they land in the shared tenant workspace, where re-registering an alias re-points every such caller's later calls to it.
On HTTP without per-user auth, brapi_dataframe_describe lists dataframes without a name only for a request with its own session-scoped canvas, and brapi_dataframe_query rejects system-catalog reads in every shape, so a caller without a known df_<uuid> name can't enumerate other callers' tables.
Project structure
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catch in tool logic
- Use
ctx.log for logging, ctx.state for tenant-scoped storage — no console, no direct persistence access
- Add new tools to the matching group in
src/mcp-server/tools/definitions/index.ts; src/index.ts composes the groups behind their feature flags
- Wrap upstream calls: validate raw → normalize → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks and tests before submitting:
License
Apache-2.0 — see LICENSE for details.