Brapi Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.12.1Updated Nov 21, 2026

Collaborative BrAPI v2.1 MCP workspace: studies, germplasm, genotypes across Breedbase, T3, more.

VerifiedStreamable HTTPWeb executableDatabasesData & AnalyticsAI & ML

Overview

AI-generated overview

Bridges BrAPI v2 plant-breeding servers so an assistant can search studies, germplasm, observations and genotypes, then pivot and query them as dataframes.

What you can do
  • Connect to BrAPI v2 servers under aliases and read their capability profile
  • Find and fetch studies, germplasm, variables, locations, images and variants
  • Walk germplasm pedigrees as a graph with cycle detection and Mermaid or DOT diagrams
  • Pull observations and genotype calls, with bounded filters and truncation notices
  • Build germplasm × trait phenotype matrices and per-germplasm trait statistics
  • Describe and query staged dataframes with read-only SQL, and export genotype matrices as VCF-lite or PLINK text
When to use it
Useful when working with crop or plant breeding data held on BrAPI-compatible servers such as Breedbase or T3, for exploratory analysis of a study, cross-study meta-analysis, pedigree inspection, or assembling genotype and phenotype matrices.
Requirements
Runs as a remote endpoint or locally via npx (Node.js). A BrAPI v2 base URL is needed, either through BRAPI_DEFAULT_BASE_URL or by passing a URL to the connect tool; per-alias credentials can come from environment variables. Optional settings cover page size, HTTP host/port/path, transport type, log level and auth mode.
Before you install
The write tool for submitting observations is off by default and must be enabled with BRAPI_ENABLE_WRITES; its apply mode writes to the upstream study. Dataframe export writes files to disk and is only available over stdio with an export directory set. Connections may carry bearer tokens, API keys or OAuth credentials, and queries send requests to third-party BrAPI servers.

Installation

In SourceWeft

  1. Open Brapi Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fbrapi-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "brapi": {
      "type": "http",
      "url": "https://brapi.caseyjhand.com/mcp"
    }
  }
}

README

@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

Public Hosted Server: https://brapi.caseyjhand.com/mcp


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

ToolDescription
brapi_connectAuthenticate to a BrAPI v2 server, register it under an alias, and return the orientation envelope
brapi_server_infoReturn the orientation envelope for an alias, optionally refreshing capabilities
brapi_describe_filtersList valid filter names for an endpoint, for use in any finder's extraFilters
brapi_find_studiesFind studies by crop, trial type, season, location, program, or recorded observation variable
brapi_get_studyFetch a study with program, trial, and location resolved, plus companion counts
brapi_find_germplasmFind germplasm by name, synonym, accession, PUI, crop, or free text
brapi_get_germplasmFetch a germplasm with attributes, direct parents, and companion counts
brapi_walk_pedigreeWalk ancestry or descendancy as a deduplicated DAG with cycle detection
brapi_find_variablesFind observation variables by name, trait class, or ontology term, with free-text ranking
brapi_find_observationsPull observation records by study, germplasm, variable, season, or unit
brapi_federated_findFind studies, germplasm, or observations across connection aliases with source coverage
brapi_find_imagesFind image metadata by unit, observation, study, ontology term, or MIME type
brapi_get_imageFetch up to 5 images inline as image content blocks
brapi_find_locationsFind research stations by country, type, abbreviation, or bounding box
brapi_find_variantsFind variants by variant set, reference, or genomic region
brapi_find_genotype_callsPull genotype calls through async search, bounded by a deployment pull ceiling
brapi_dataframe_describeList dataframes, or describe one with columns, row count, and provenance
brapi_dataframe_queryRun read-only SQL across dataframes
brapi_dataframe_dropOpt-in. Drop a dataframe by name
brapi_dataframe_exportOpt-in, stdio-only. Export a dataframe to disk as CSV, Parquet, or JSON
brapi_build_phenotype_matrixBuild a germplasm × trait matrix from one or more studies as a dataframe
brapi_germplasm_performancePer-variable aggregates (n, mean, median, sd, min, max) for one germplasm across its studies
brapi_export_genotype_matrixPivot a variant set's calls into a call set × variant matrix, with VCF-lite or PLINK text
brapi_submit_observationsOpt-in. Two-phase observation write: preview validates, apply confirms and writes
brapi_raw_getPassthrough to any GET /{path} endpoint no curated tool covers
brapi_raw_searchPassthrough to any POST /search/{noun} endpoint, with async polling handled

Resources

ResourceDescription
brapi://server/infoOrientation envelope for the default connection
brapi://callsRaw capability profile (/serverinfo + /calls) for the default connection
brapi://study/{studyDbId}One study with program, trial, and location resolved
brapi://germplasm/{germplasmDbId}One germplasm with attributes and parents
brapi://filters/{endpoint}Filter catalog for one endpoint
brapi://variable/{observationVariableDbId}One observation variable (trait, scale, method, ontology)

Every resource reads the default connection and mirrors a tool; tool-only clients and multi-server workflows use the tools.

Prompts

PromptDescription
brapi_eda_studyExploratory-data-analysis playbook for one study, ending in a structured report
brapi_meta_analysisCross-study meta-analysis playbook for a germplasm × trait combination

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.

text
1. brapi_find_observations { studies: ["s-422"] }   → leading rows inline + dataframe.tableName = "df_<uuid>" (when results holds fewer rows than matched)2. brapi_dataframe_describe { dataframe: "df_<uuid>" }   → schema + provenance (originating tool, baseUrl, query, expiry)3. brapi_dataframe_query { sql: "SELECT germplasmName, value FROM df_<uuid> WHERE observationVariableDbId = 'V1' LIMIT 100" }   → typed columns + bounded rows

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:

json
{  "mcpServers": {    "brapi-mcp-server": {      "type": "streamable-http",      "url": "https://brapi.caseyjhand.com/mcp"    }  }}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json
{  "mcpServers": {    "brapi-mcp-server": {      "type": "stdio",      "command": "bunx",      "args": ["@cyanheads/brapi-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

Or with npx (no Bun required):

json
{  "mcpServers": {    "brapi-mcp-server": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@cyanheads/brapi-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

Or with Docker:

json
{  "mcpServers": {    "brapi-mcp-server": {      "type": "stdio",      "command": "docker",      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/brapi-mcp-server:latest"]    }  }}

For Streamable HTTP, set the transport and start the server:

sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http# Server listens at http://localhost:3010/mcp

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

  1. Clone the repository:
sh
git clone https://github.com/cyanheads/brapi-mcp-server.git
  1. Navigate into the directory:
sh
cd brapi-mcp-server
  1. Install dependencies:
sh
bun install
  1. Configure environment:
sh
cp .env.example .env# edit .env if you need credentials or non-default settings

Configuration

Every variable is optional.

VariableDescriptionDefault
BRAPI_DEFAULT_BASE_URLBase URL for the default alias (e.g. https://test-server.brapi.org/brapi/v2).—
BRAPI_DEFAULT_* credentialsOne credential family for the default alias; see Per-alias credentials.—
BRAPI_DEFAULT_API_KEY_HEADERAPI-key header for the default alias, and the fallback header for any api_key auth that names none.Authorization
BRAPI_BUILTIN_ALIASES_DISABLEDComma-separated built-in aliases to remove (case-insensitive).—
BRAPI_LOAD_LIMITDefault inline row cap for finders; a 24,000-byte budget also bounds the inline rows, and the matched set spills to a dataframe when either cuts them short.1000
BRAPI_PAGE_SIZEUpstream pageSize for spillover page walks. The dataframe ceiling is pageSize × 50, capped at 50,000 rows.1000
BRAPI_MAX_CONCURRENT_REQUESTSPer-connection concurrency cap.4
BRAPI_RETRY_MAX_ATTEMPTS / BRAPI_RETRY_BASE_DELAY_MSRetries on 429/5xx and timeouts, and the exponential-backoff base delay. Eligible timeout retries require room for another attempt in the shared budget.3 / 500
BRAPI_REQUEST_TIMEOUT_MSDefault per-request HTTP timeout. Primary embedded observation-unit reads can use the remaining shared call budget.30000
BRAPI_CALL_DEADLINE_MSShared upstream budget starting at the MCP call's start. Dataframe walks get up to 80% of this budget within the same deadline. Leave headroom under your client's request timeout, which defaults to 60 seconds in the MCP TypeScript SDK.50000
BRAPI_COMPANION_TIMEOUT_MSTimeout for non-critical enrichment calls (FK lookups, count probes), which also skip retries.8000
BRAPI_SEARCH_POLL_TIMEOUT_MS / BRAPI_SEARCH_POLL_INTERVAL_MSAsync /search polling budget and interval. Polling also stops at the shared upstream deadline.60000 / 1000
BRAPI_DATASET_TTL_SECONDSLifetime of dataframe provenance (the handle's expiresAt).86400
BRAPI_REFERENCE_CACHE_TTL_SECONDSTTL for cached capability profiles and reference data (programs, trials, locations).3600
BRAPI_ALLOW_PRIVATE_IPSAllow RFC 1918 / loopback targets. Dev only.false
BRAPI_SESSION_ISOLATIONScope connections and the default canvas to the MCP session when one exists; false shares them across the tenant. See Deployment shapes.true
BRAPI_ENABLE_WRITESFeature flag. Registers brapi_submit_observations.false
BRAPI_CANVAS_DROP_ENABLEDFeature flag. Registers brapi_dataframe_drop.false
BRAPI_EXPORT_DIRFeature flag. Output directory for brapi_dataframe_export; setting it registers the tool, over stdio only.—
BRAPI_CANVAS_MAX_ROWS / BRAPI_CANVAS_QUERY_TIMEOUT_MSResponse row cap and per-query timeout for brapi_dataframe_query. The cap may not exceed the framework's CANVAS_DEFAULT_ROW_LIMIT (default 10000); startup fails if it does.10000 / 30000
BRAPI_GENOTYPE_CALLS_MAX_PULLUpstream call ceiling per brapi_find_genotype_calls or brapi_export_genotype_matrix call. Max 500000.100000
BRAPI_GENOTYPE_MATRIX_MAX_COLUMNSVariant-column ceiling per brapi_export_genotype_matrix matrix. Max 500000.10000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTHTTP server port.3010
MCP_SESSION_MODEHTTP session mode. This server requires stateful (apply-mode writes confirm over the session, and isolation keys off it); an HTTP start fails if it resolves to stateless.auto (resolves stateful)
MCP_AUTH_MODEAuthentication: none, jwt, or oauth.none
MCP_REQUEST_STATE_KEYSecret of at least 32 bytes, the same on every instance, that seals the requestState a confirmation round returns; any other state is refused before the handler runs. Recommended with BRAPI_ENABLE_WRITES.—
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).info
LOG_TOOL_FAILURE_PAYLOADSLog each failed tool call's arguments and result (key-name redaction only).false
STORAGE_PROVIDER_TYPEStorage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.in-memory
OTEL_ENABLEDEnable OpenTelemetry.false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOpt-in OTLP log export endpoint; the base OTEL_EXPORTER_OTLP_ENDPOINT never enables it.—

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:

  1. Agent input, within the pairing rules below.
  2. Per-alias env vars: BRAPI_<ALIAS>_*, uppercased with hyphens as underscores (my-server → BRAPI_MY_SERVER_*).
  3. Built-in aliases: see Built-in aliases.
  4. 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.

Vars setResolved mode
_USERNAME + _PASSWORDsgn (Breedbase /token exchange)
_BEARER_TOKENbearer
_API_KEY (+ optional _API_KEY_HEADER)api_key
_OAUTH_CLIENT_ID + _OAUTH_CLIENT_SECRET (+ optional _OAUTH_TOKEN_URL)oauth2
(none set)none

BRAPI_<ALIAS>_DIALECT pins the dialect adapter (spec, brapi-test, breedbase, cassavabase, bms) when detection picks the wrong one; auto or unset detects it.

sh
# .env — attach write credentials to the built-in 'bti-cassava' aliasBRAPI_BTI_CASSAVA_USERNAME=aliceBRAPI_BTI_CASSAVA_PASSWORD=...# (BASE_URL omitted — the built-in registry covers it)
# Static API key as alias 'prod'BRAPI_PROD_BASE_URL=https://my-brapi.example.com/brapi/v2BRAPI_PROD_API_KEY=...BRAPI_PROD_API_KEY_HEADER=X-API-Key

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).

AliasUpstreamHosted byCropNotes
bti-cassavacassavabase.orgBoyce Thompson InstituteCassavaNextGen Cassava
bti-sweetpotatosweetpotatobase.orgBoyce Thompson InstituteSweet potato
bti-breedbase-demobreedbase.orgBoyce Thompson InstituteDemoSample data only, for onboarding and tests

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

  • Build and run the production version:

    sh
    # One-time buildbun run rebuild
    # Run the built serverbun run start            # transport from MCP_TRANSPORT_TYPE (stdio default)bun run start:stdiobun run start:http
    # Or run from source with hot reloadbun --watch src/index.ts
  • Run checks and tests:

    sh
    bun run devcheck         # Lint, format, typecheck, security, changelog syncbun run test             # Vitest suitebun run lint:mcp         # Validate MCP definitions

Docker

sh
docker build -t brapi-mcp-server .docker run --rm -p 3010:3010 brapi-mcp-server

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:

ShapeSettingsIsolationBest for
Per-session (default)MCP_AUTH_MODE=none + HTTP stateful + BRAPI_SESSION_ISOLATION=trueEach MCP session gets its own connections and canvas. Requests without a session share one tenant-wide namespace, so brapi_connect refuses their caller-supplied auth with auth_session_required; keyless connections and operator env credentials still work.Multi-user hosting without SSO
Per-user credentialsMCP_AUTH_MODE=jwt or oauth (+ HTTP stateful)Each user's JWT tid claim is its own tenant; sessions sub-scope inside it when isolation is on.Multi-user hosting with institutional SSO; the strongest separation
Shared workspaceMCP_AUTH_MODE=none + BRAPI_SESSION_ISOLATION=falseAll callers share one tenant's connections and canvas.One researcher running parallel agents on shared upstream credentials

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

DirectoryPurpose
src/index.tscreateApp() entry point: registers tools (behind their feature flags), resources, and prompts, and inits services.
src/configServer env parsing (Zod), per-alias credential resolution, and the built-in alias registry.
src/mcp-server/toolsTool definitions (*.tool.ts) and shared helpers. Twenty-five tools across connection, retrieval, analysis, write, and raw passthrough.
src/mcp-server/resourcesResource definitions (*.resource.ts).
src/mcp-server/promptsPrompt definitions (*.prompt.ts).
src/servicesBrAPI client, dialect adapters, filter catalog, canvas bridge, capability registry, ISO country resolver, ontology resolver, reference-data cache, server registry.
tests/Unit and integration tests mirroring src/.

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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

Source: README.md at commit 522a187

Tools

23

brapi_connect

Brapi Connect

Open a connection to a BrAPI v2 server, authenticate, and return the full orientation envelope (server identity, capability profile, content summary, suggested next tools). Other BrAPI tools connect an alias the server has a URL configured for (a built-in or operator-configured alias, or `default` on a deployment with a default server) on first use; call this to connect any other server by `baseUrl`, to pass `auth`, or to re-point an alias. Supports multiple concurrent connections via named aliases. Credentials can be configured server-side and omitted from this call. When a request carries no MCP session on a deployment without per-user auth, aliases live in one namespace shared by every such caller: re-registering an alias re-points their later calls to it. Built-in known servers (callable with no `baseUrl` or `auth` — public BrAPI v2 endpoints): `bti-breedbase-demo`, `bti-cassava`, `bti-sweetpotato`. Operator-configured aliases on this deployment (credentials and/or baseUrl read from server env vars): `default`, `cassava`. Aliases are shortcuts only; any other BrAPI v2 server is reachable by passing `baseUrl` directly.

ParametersauthaliasbaseUrl

brapi_build_phenotype_matrix

Brapi Build Phenotype Matrix

Pull observations across one or more studies and pivot them into a germplasm × trait matrix materialized as a canvas dataframe. Returns a dataframe handle (read it with brapi_dataframe_describe and brapi_dataframe_query) plus a summary of dimensions and aggregate method. Long-form output is suitable for downstream GROUP BY analysis by study, germplasm, or variable. A study whose pull fails is named in warnings and the rest still build the matrix; the call fails only when every study failed.

ParametersaliasshapestudiesrequiredaggregategermplasmloadLimitvariablesextraFilters

brapi_server_info

Brapi Server Info

Return the full orientation envelope for a BrAPI connection — server identity, capabilities, content counts, suggested finders, and notes. Pass forceRefresh to refetch the cached capability scan; pass an alias to read a non-default connection.

ParametersaliasforceRefresh

brapi_describe_filters

Brapi Describe Filters

List the valid filter names for a BrAPI endpoint (studies, germplasm, observations, variables, images, variants, locations) — companion lookup for the `extraFilters` passthrough on any `find_*` tool. Entries reflect the BrAPI v2.1 spec; individual servers may implement subsets.

Parametersendpointrequired

brapi_federated_find

Brapi Federated Find

Find studies, germplasm, or observations across BrAPI connection aliases. Reuses each finder’s filters, dialect handling, and read limits. Rows retain their source alias and DbId. Only an unambiguous exact germplasm PUI can group records across aliases. Returns per-alias coverage and stages the merged collection when the inline limit is reached.

ParametersqueryrequiredaliasesrequiredloadLimit

brapi_find_studies

Brapi Find Studies

Locate studies matching crop, trial type, season, location, program, or recorded observation variable. Enriches results with program/trial/location context in one call. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).

ParameterscropaliasactivetrialsseasonsprogramsloadLimitlocationsvariablesstudyNamestrialTypesextraFilters

brapi_get_study

Brapi Get Study

Fetch a single study by DbId with its program, trial, and location records resolved where those lookups succeed. Response includes cheap observation/observation-unit/variable counts as drill-down signals.

ParametersaliasstudyDbIdrequired

brapi_find_germplasm

Brapi Find Germplasm

Find germplasm by name, synonym, accession number, PUI, crop, study, trial, program, or free-text query. Matches across registered synonyms. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL) instead of paging row-by-row.

ParameterstextaliascropsgenusnamestrialsspeciesstudiesprogramssynonymsloadLimitcollections+4 more

brapi_get_germplasm

Brapi Get Germplasm

Fetch a single germplasm by DbId with attributes and direct parents. Response companions report study count, direct parent count, and direct descendant count — signals for pedigree depth and observation coverage.

ParametersaliasgermplasmDbIdrequired

brapi_walk_pedigree

Brapi Walk Pedigree

Walk germplasm ancestry or descendancy as a deduplicated DAG with cycle detection and depth limits. leafCount counts graph terminals, confirmedLeafCount counts successfully verified leaves, and frontier records unresolved directions. Nodes and edges each fit loadLimit and a 24,000-byte preview budget; trimmed discovered graphs and already-fetched omitted relatives are staged for brapi_dataframe_describe and brapi_dataframe_query (SQL). Diagrams describe only the discovered graph, never unvisited relatives.

ParametersaliasdiagrammaxDepthdirectionloadLimitgermplasmDbIdsrequired

brapi_germplasm_performance

Brapi Germplasm Performance

Aggregate a single germplasm's observations across studies, returning per-variable statistics (n, mean, median, sd, min, max), contributing studies, seasons, and collection coverage. SGN/Breedbase uses advertised germplasm-scoped observation units with embedded measurements, including zeros. Other servers discover up to 200 studies before pulling per study. Pass studyDbIds to skip discovery and restrict collection to known studies. Per-study observation limits, page limits, failures, and incomplete scans appear in coverage and warnings. For the underlying matrix, use brapi_build_phenotype_matrix.

ParametersaliasloadLimitvariablesstudyDbIdsgermplasmDbIdrequired

brapi_find_variables

Brapi Find Variables

Find observation variables (traits) by name, trait class, ontology term, or free-text query. Free-text queries are ranked against every fetched row by PUI, name, synonym, and trait text; every match leads results[] with its textMatchRank, and a candidate carries the ontology PUI of its row as termId when the row has one. results[] holds the leading rows up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).

ParameterscroptextaliasscalesmethodsstudiesloadLimitvariablesontologiesextraFilterstraitClassesvariablePUIs+1 more

brapi_find_observations

Brapi Find Observations

Pull observation records filtered by study, germplasm, variable, season, or observation unit. SGN/Breedbase uses advertised embedded units for study or germplasm scopes. Other GET observation queries without a study, trial, observation unit, or observation anchor run a one-row count probe and skip the bulk pull when the probe fails or reports more than 5,000 rows. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when those bounds cut it short, read the staged dataframe with brapi_dataframe_describe and brapi_dataframe_query (SQL).

ParametersaliastrialsseasonsstudiesprogramsgermplasmloadLimitvariablestimestampToextraFiltersobservationstimestampFrom+2 more

brapi_find_images

Brapi Find Images

Filter images by observation unit, observation, study, descriptive ontology term, file name, or MIME type. Named mimeTypes are verified case-insensitively on each scanned row. Returns metadata only — use brapi_get_image to fetch bytes inline. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).

ParametersaliasimagesstudiesloadLimitmimeTypesextraFiltersobservationsimageFileNamesobservationUnitsdescriptiveOntologyTerms

brapi_get_image

Brapi Get Image

Fetch image bytes for up to 5 imageDbIds and return them inline as `type: image` content blocks. Falls back to the metadata `imageURL` when the server lacks dedicated image-content delivery or that request fails. No filesystem side-effects.

ParametersaliasimageDbIdsrequired

brapi_find_locations

Brapi Find Locations

Find research stations / field sites by country, abbreviation, type, location ID, or free-text. Pass countryCodes directly or use English countryNames to resolve ISO codes. On SGN-family servers (CassavaBase, Sweetpotatobase, other Breedbase deployments), resolved names also search alpha-2, ISO numeric, and E.164 calling codes, and a row matched only by a numeric code is dropped when its countryName names another country. Optional bbox restricts rows to a latitude/longitude window. The BrAPI Community Test Server dialect reads GeoJSON Points in [lat, lon, alt] order; other dialects use [lon, lat, alt]. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).

ParametersbboxaliasloadLimitlocationscountryCodescountryNamesextraFiltersabbreviationslocationNameslocationTypes

brapi_find_variants

Brapi Find Variants

Find variant records by variant set, reference sequence, or genomic region. Named reference and region filters are verified on each scanned row using exact reference names and overlap with the 0-based half-open window [start, end). results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).

ParametersendaliasstartvariantsloadLimitreferencesvariantSetsextraFiltersreferenceName

brapi_find_genotype_calls

Brapi Find Genotype Calls

Pull genotype calls for a call set × variant set. Filter to bound cost — at minimum, set one of `variantSetDbId`, `variantSetDbIds`, `germplasmDbIds`, `callSetDbIds`, or `variantDbIds`. The upstream pull is capped by deployment policy; when the pull is truncated, narrow the filters. results[] holds the leading calls up to `loadLimit` and a 24,000-byte budget; when it holds fewer than were collected, every collected call is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL) instead of paging row-by-row.

ParametersaliasloadLimitcallFormatcallSetDbIdsvariantDbIdsgermplasmDbIdsvariantSetDbIdvariantSetDbIds

brapi_export_genotype_matrix

Brapi Export Genotype Matrix

Pull genotype calls for a variant set and pivot them into a call set × variant matrix. Each row is one call set (one sample's calls), led by callSetDbId, callSetName, and germplasmDbId — the germplasm resolved through the call set's sample, null when unresolved. Join to brapi_build_phenotype_matrix on germplasmDbId; a germplasm with several call sets joins once per call set. `variantDbIds` restricts the pull to chosen variants, such as a region's from brapi_find_variants. `matrix-json` registers a wide canvas dataframe; `vcf-lite` adds VCF-subset text in `vcf`; `plink` adds .ped/.map text in `ped`/`map`. Text formats pull /variants metadata and convert zero-based BrAPI start to one-based positions; missing/invalid positions use `.`/`0`. Read the dataframe with brapi_dataframe_describe and brapi_dataframe_query (SQL). `variantColumnLegend` maps SQL-safe columns to original variant IDs.

ParametersaliasformatrequiredmaxCallsmaxColumnsvariantDbIdsgermplasmDbIdsvariantSetDbIdrequired

brapi_dataframe_describe

Brapi Dataframe Describe

Start here after a spillover. Lists dataframes (or describes one) with columns, row counts, and originating-source provenance. The dataframe name appears inline on every find_* response that spilled (`result.dataframe.tableName`) — pass it as `dataframe` to inspect schema and provenance before writing the first brapi_dataframe_query. On a shared HTTP endpoint without per-caller auth, listing without a name is available only where each MCP session has its own workspace, and never to a request without a session; pass a known name instead.

Parametersdataframe

brapi_dataframe_query

Brapi Dataframe Query

Run read-only SQL across in-memory dataframes. Dataframes auto-populate when find_* tools spill (named `df_<uuid>`) — the dataframe name appears inline on every find_* response that spilled (`result.dataframe.tableName`), so the typical flow is find_* → read the name → query here. Use brapi_dataframe_describe to inspect schema and provenance for a known name. Use `LIMIT/OFFSET` to walk results, projection to trim columns, and aggregation to summarize. Use `registerAs` to chain — the result lands as a new dataframe.

ParameterssqlrequiredpreviewrowLimitregisterAs

brapi_raw_get

Brapi Raw Get

Passthrough to BrAPI GET /{path} without foreign-key resolution. List results (result array or result.data) return a leading preview within loadLimit and a 24,000-byte budget on each serialized row representation; an oversized first row returns no inline rows. Omitted fetched rows remain in a dataframe readable with brapi_dataframe_describe and brapi_dataframe_query. Explicit params.page/pageSize fetches only that upstream page, staging it if trimmed. Non-list results and envelope siblings are preserved. Emits a suggestion when a curated tool covers the endpoint.

ParameterspathrequiredaliasparamsloadLimit

Version history

11
  1. v0.12.1LatestNov 21, 2026
  2. v0.12.0Nov 21, 2026
  3. v0.11.0Nov 11, 2026
  4. v0.10.1Oct 19, 2026
  5. v0.10.0Oct 18, 2026
  6. v0.9.1Oct 18, 2026
  7. v0.9.0Oct 18, 2026
  8. v0.8.1Oct 4, 2026
  9. v0.8.0Sep 24, 2026
  10. v0.7.13Sep 19, 2026
  11. v0.7.12Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts