---

Tools

25 tools grouped by shape — connection tools bootstrap a session, find_* tools return a summarized page plus distributions and spill overflow rows into a canvas dataframe that agents on the same session can query or hand off by ID, get_* tools fetch a single record with companion counts, plus pedigree walking, an embedded SQL workspace over spilled rows (DuckDB-backed), file export for human handoff, an additive write surface for observations, and raw passthrough escape hatches.

Orient

Tool	Description
brapi_connect	Authenticate, register the connection under an alias, cache the capability profile, and return the orientation envelope inline. One call fully orients the agent.
brapi_server_info	Re-fetch the orientation envelope for a registered alias — identity, auth, capabilities, content counts, attribution, notes.
brapi_describe_filters	Static BrAPI v2.1 filter catalog for any endpoint — powers extraFilters discovery on every find_* tool.

Retrieve

Tool	Description
brapi_find_studies	Find studies by crop / trial type / season / location / program. Distributions + dataframe spillover.
brapi_get_study	Fetch a study with program / trial / location FKs resolved and companion counts (observations, units, variables).
brapi_find_germplasm	Find germplasm by name, synonym, accession, PUI, crop, or free-text. Distributions + dataframe spillover.
brapi_get_germplasm	Fetch a germplasm with attributes, direct parents, and companion counts (studies, parents, descendants).
brapi_walk_pedigree	BFS-walk ancestry / descendancy as a deduplicated DAG with cycle detection, depth limits, and traversal stats.
brapi_find_variables	Find observation variables by name / class / ontology / free-text; ranked client-side via OntologyResolver when text is supplied.
brapi_find_observations	Pull observation records by study / germplasm / variable / season / unit / timestamp. Dataframe spillover.
brapi_find_images	Filter image metadata by unit / study / ontology / MIME type. Bytes via brapi_get_image.
brapi_get_image	Fetch image bytes for up to 5 imageDbIds inline as type: image blocks. Prefers /imagecontent, falls back to imageURL.
brapi_find_locations	Find research stations by country (ISO alpha-3 code, or English country name resolved client-side) / type / abbreviation, with optional client-side bbox filter.
brapi_find_variants	Find variant records by variant set, reference, or genomic region (1-based inclusive / exclusive).
brapi_find_genotype_calls	Pull genotype calls via async-search polling. Upstream pull bounded by BRAPI_GENOTYPE_CALLS_MAX_PULL (default 100k, max 500k).

Analyze

Tool	Description
brapi_dataframe_describe	Start here after a spillover. Lists dataframes (or describes one) with column schema, row counts, and originating-source provenance.
brapi_dataframe_query	SELECT SQL across in-memory dataframes (DuckDB-backed). Spilled find_* rows auto-register as df_<uuid>. Read-only — multi-statement, non-SELECT, file-reads, and exports rejected. Returns typed columns ({ name, type }[]).
brapi_dataframe_drop	Opt-in via BRAPI_CANVAS_DROP_ENABLED=true. Drop a dataframe by name. Idempotent. Dataframes also expire via TTL when left unmanaged.
brapi_dataframe_export	Opt-in via BRAPI_EXPORT_DIR=<path>, stdio-only. Export a dataframe to disk (CSV / Parquet / JSON) under the configured directory and return the absolute path for the human to open. Optional columns projection or sql filter materializes a derived table for the export, dropped after.
brapi_build_phenotype_matrix	Build a germplasm × trait matrix from one or more studies and materialize it as a canvas dataframe. Supports wide (pivot) or long shape with configurable per-cell aggregation.
brapi_germplasm_performance	Per-variable performance aggregates (n, mean, median, sd, min, max, studyCount) for a single germplasm across all studies where it has observations.
brapi_export_genotype_matrix	Export genotype calls for a variant set as a germplasm × variant canvas dataframe; also serializes to VCF-lite or PLINK .ped/.map text. Distinct-variant columns bounded by BRAPI_GENOTYPE_MATRIX_MAX_COLUMNS (default 10k, max 500k).

Write (opt-in: BRAPI_ENABLE_WRITES=true)

Tool	Description
brapi_submit_observations	Two-phase observation write — mode: preview validates; mode: apply asks the caller to confirm, then fans POST + PUT in parallel. Additive only — no destructive deletion.

Escape hatches

Tool	Description
brapi_raw_get	Passthrough to any BrAPI GET /{path} not covered by curated tools. Emits a routing nudge when one applies.
brapi_raw_search	Passthrough to any POST /search/{noun} with async polling handled transparently. Same nudge pattern.

Alias discovery. Built-in and operator-configured aliases are appended to the brapi_connect description at server startup, so agents see the inventory on tools/list. Restart after env-var changes to refresh.

---

Resources

URI-addressable mirrors of the curated tool surface for clients that prefer resources. All resources use the default connection — multi-server workflows route through tools.

URI template	Mirrors
brapi://server/info	brapi_server_info (default connection)
brapi://calls	Raw capability profile
brapi://study/{studyDbId}	brapi_get_study
brapi://germplasm/{germplasmDbId}	brapi_get_germplasm
brapi://filters/{endpoint}	brapi_describe_filters
brapi://variable/{observationVariableDbId}	Observation variable record (trait, scale, method, ontology)

---

Prompts

Multi-step BrAPI workflow templates — pure user-message generators, no side effects.

Name	Args	Purpose
brapi_eda_study	studyDbId, alias?	EDA playbook for one study — orient, variables, coverage, missing data, outliers, pedigree, structured report.
brapi_meta_analysis	germplasmDbIds (CSV), traitName, alias?	Cross-study meta-analysis — trait resolution, study discovery, harmonization, per-germplasm × per-study and across-study summaries.

---

Multi-agent workflows

The server has two stateful layers and two scoping axes:

Layer	Default scope	Why
Connection state (aliases, exchanged tokens)	Tenant + session	Credentials and live tokens. Tenant gates by user (jwt/oauth) or collapses to 'default' (none). Session sub-scope (BRAPI_SESSION_ISOLATION=true, default) prevents concurrent HTTP sessions in one tenant from sharing each other's tokens.
Dataframes (df_<uuid> tables)	Tenant + session	Within one (tenant, session), agents share by df_<uuid> name — possession grants full read/write/drop, auto-expires in 24h, provenance recorded. The underlying canvas is tenant-gated by the framework; the session sub-scope is enforced by the bridge's keying.

Within one (tenant, session), dataframes act as a self-cleaning shared notebook: hand the df_<uuid> name between parallel agents on the same MCP session, persist it across a multi-step workflow, query / project / aggregate / join from any position. Address-by-name, time-bounded, scoped to that session.