.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/brapi-mcp-server</h1> <p><b>A collaborative BrAPI v2.1 workspace for multi-agent research via MCP. Search studies, germplasm, genotypes, & more - across Breedbase, T3, Sweetpotatobase, & any BrAPI v2-compliant server.</b> <div>25 Tools • 6 Resources • 2 Prompts • Multi-agent collaboration</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

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

Retrieve

Analyze

Write (opt-in: BRAPI_ENABLE_WRITES=true)

Escape hatches

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.

Prompts

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

Multi-agent workflows

The server has two stateful layers and two scoping axes:

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.

Default (isolated) shape. Under MCP_AUTH_MODE=none + HTTP stateful (the default), each MCP session carves its own connection state and its own canvas. Two researchers connected to the same host don't see each other's brapi_connect aliases, exchanged SGN/OAuth tokens, or spilled df_<uuid> rows. Stdio always behaves as one session (single-process, no concurrency).

Shared-workspace shape. Set BRAPI_SESSION_ISOLATION=false for cross-session collaboration in one tenant — multiple MCP sessions then share connection state and one default canvas, the way pre-0.5.3 deployments behaved. Useful when planning, analysis, and writeup agents run as separate MCP clients but operate as one researcher on shared upstream credentials.

On privileged data. The df_<uuid> name is a capability token within a canvas — not row-level access control. Anyone holding the name within the same (tenant, session) bucket can read its rows. Under default isolation, that bucket is one MCP session. Under BRAPI_SESSION_ISOLATION=false, the bucket widens to the whole tenant (all callers under auth=none, or one user's sessions under jwt/oauth). Treat dataframe names like authenticated share links — pass within the bucket, not externally. The 24h TTL caps blast radius; the provenance trail (originating tool, baseUrl, query) supports audit. Belt-and-braces: brapi_dataframe_describe requires an explicit dataframe name on shared-trust HTTP (no list-all enumeration), and brapi_dataframe_query rejects system-catalog reads (information_schema, pg_catalog, sqlite_master, duckdb_*) — so a caller without a known df_<uuid> name can't fish through either surface.

BrAPI-specific features

• Dataframe spillover — find_* tools cap in-context rows at loadLimit and materialize larger unions (up to 50k rows / 50 pages) as DuckDB-backed df_<uuid> canvas dataframes. Discover with brapi_dataframe_describe, query with brapi_dataframe_query (SQL paging via LIMIT/OFFSET, projection, aggregation). Read-only enforcement at the SQL gate; session-scoped by default (tenant-scoped under BRAPI_SESSION_ISOLATION=false) — see Multi-agent workflows.
• Multi-server session — ServerRegistry maps aliases to live BrAPI connections; one session can span Breedbase, T3, and Sweetpotatobase in parallel.
• Built-in known-server registry — bti-cassava, bti-sweetpotato, bti-breedbase-demo, t3-wheat, t3-oat, t3-barley resolve out-of-the-box without env vars; orientation envelope carries CC-BY attribution.
• Capability-aware calls — CapabilityRegistry caches /serverinfo per connection and guards every tool call against unsupported endpoints. Falls back to /calls when /serverinfo is sparse.
• Dialect adaptation — spec / brapi-test / breedbase / cassavabase / bms dialects translate v2.1 plural filter keys to the singular form each server family honors, drop filters known to be broken, normalize sparse-shape encodings, and escalate to POST /search/{noun} when GET would silently downcast multi-value filters. Detected from /serverinfo (server-name / organization-name); pin per-alias via BRAPI_<ALIAS>_DIALECT. Verified-vs-inferred mapping counts surface on the orientation envelope so agents see the confidence floor at a glance.
• DuckDB required — @duckdb/node-api is a regular dependency; startup fails closed when the framework canvas is unavailable. Not supported on Cloudflare Workers (no native binary in that runtime).
• Async-search transparency — brapi_find_genotype_calls and brapi_raw_search handle the POST /search/{noun} → GET /search/{noun}/{id} 202-retry pattern automatically.
• Pedigree DAG walks — brapi_walk_pedigree BFS-traverses ancestry / descendancy with cycle detection (BrAPI only exposes one generation per call); a 1,000-node safety cap bounds the walk and sets truncated when reached.
• Image content — brapi_get_image fetches bytes inline as MCP type: image blocks, preferring /images/{id}/imagecontent with imageURL fallback.
• Free-text variable ranking — OntologyResolver scores variables against a query (PUI / name / synonym / trait-class) so find_variables text:"..." returns ranked candidates even without /ontologies.
• Auth variants in one schema — tagged-union covers none / bearer / api_key / sgn (session-token exchange) / oauth2 (client-credentials).
• Typed error contracts — every declared failure mode carries a stable data.reason, an HTTP-style code, and a recovery.hint so clients can route deterministically.

Built on @cyanheads/mcp-ts-core — declarative definitions, unified error handling, pluggable auth (none / jwt / oauth), swappable storage, structured logging with optional OTel, STDIO + Streamable HTTP transports.

Working with dataframes

When a find_* tool's upstream total exceeds loadLimit, the full union materializes as a canvas dataframe and the response carries an inline dataframe handle ({ tableName, rowCount, columns, createdAt, expiresAt, … }). Upstream column names that aren't SQL-safe identifiers — reserved words like end, digit-leading IDs — are sanitized for the dataframe, and a columnLegend on the handle maps each renamed column back to its original key. SQL is the paging idiom — use LIMIT/OFFSET to walk pages, projection (SELECT col1, col2) to trim columns, and aggregation (COUNT, GROUP BY, AVG) to summarize without materializing every row.

Dataframe names are session-scoped capability tokens by default — pass tableName to any other agent on the same MCP session (or a downstream step in the same workflow) and they query the same workspace by name without re-pulling from the upstream. The brapi_dataframe_* tools offer SQL manipulation and more. See Multi-agent workflows for cross-session / cross-tenant rules.

1. brapi_find_observations { studies: ["s-422"] }
   → first-page rows inline + dataframe.tableName = "df_<uuid>" (when totalCount > loadLimit)
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
4. brapi_dataframe_query { sql: "SELECT COUNT(*) AS n, AVG(CAST(value AS DOUBLE)) AS mean FROM df_<uuid> WHERE observationVariableDbId = 'V1'" }
   → aggregate without round-tripping all rows

Dataframes auto-expire via TTL (BRAPI_DATASET_TTL_SECONDS, default 24h). Set BRAPI_CANVAS_DROP_ENABLED=true to expose brapi_dataframe_drop for explicit cleanup.

Getting started

Add to your MCP client config — pick one runner:

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

Swap command/args for npx -y @cyanheads/brapi-mcp-server@latest (no Bun) or docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/brapi-mcp-server:latest.

For Streamable HTTP:

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 six built-in aliases (bti-cassava, bti-sweetpotato, bti-breedbase-demo, t3-wheat, t3-oat, t3-barley) resolve out-of-the-box, and agents can connect to any other BrAPI v2 URL at runtime via brapi_connect. For credentialed servers, prefer env vars over agent input so passwords / tokens / API keys stay out of the LLM context — see Per-alias credentials.

Prerequisites: Bun v1.3.11+ or Node.js v24+. @duckdb/node-api is a required dependency — supported on Linux/macOS/Windows × x64 plus Linux/macOS arm64 (no Windows arm64; no Cloudflare Workers).

Configuration

Every variable is optional.

Per-alias overrides follow the BRAPI_<ALIAS>_* pattern — see .env.example for every override and inline comments.

Per-alias credentials

brapi_connect resolves baseUrl and auth from env vars when the agent omits them — credentials never enter the LLM context. Four layers of precedence:

1. Explicit agent input — always wins.
2. Per-alias env vars — BRAPI_<ALIAS>_* (uppercased, hyphens → underscores: my-server → BRAPI_MY_SERVER_*).
3. Built-in known-server registry — see Built-in aliases.
4. Default env vars — BRAPI_DEFAULT_*, only when the alias differs from default. Not layered on top of a built-in URL — defaults belong to the default server.

Each alias carries one credential family — auth mode is derived from which fields are set:

Mixing families within an alias raises a ValidationError.

# .env — attach write credentials to the built-in 'bti-cassava' alias
BRAPI_BTI_CASSAVA_USERNAME=alice
BRAPI_BTI_CASSAVA_PASSWORD=...
# (BASE_URL omitted — built-in registry covers it)

# Static API key as alias 'prod'
BRAPI_PROD_BASE_URL=https://my-brapi.example.com/brapi/v2
BRAPI_PROD_API_KEY=...
BRAPI_PROD_API_KEY_HEADER=X-API-Key

Then the agent calls brapi_connect({ alias: 'bti-cassava' }) — no baseUrl, no auth, no secrets in the prompt.

Built-in aliases

The server ships with a curated registry of public BrAPI v2 endpoints. Each resolves out-of-the-box; the orientation envelope surfaces license, citation, and homepage in its attribution block under Creative Commons Attribution.

Set BRAPI_<ALIAS>_BASE_URL to repoint at a staging mirror or fork (env wins over the built-in URL — hyphens in the alias become underscores in the env var, so t3-wheat → BRAPI_T3_WHEAT_BASE_URL). Set BRAPI_<ALIAS>_USERNAME etc. to attach credentials on top of the built-in URL — each Breedbase instance has its own user table, so write access requires separate registration on each upstream. Use BRAPI_BUILTIN_ALIASES_DISABLED=bti-cassava,t3-wheat to strip specific entries.

Citation: all six 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

# Hot-reload dev (Bun runs TS directly)
bun --watch src/index.ts

# Production
bun run rebuild
bun run start            # transport via MCP_TRANSPORT_TYPE (stdio default)
bun run start:stdio      # or pin explicitly
bun run start:http

# Checks
bun run devcheck         # lint + format + typecheck + security + changelog sync
bun run test             # Vitest
bun run lint:mcp         # validate MCP definitions

Docker

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

Defaults to HTTP transport, stateful session mode (engages the mcp-session-id lifecycle — precondition for BRAPI_SESSION_ISOLATION=true; hijack protection requires layering MCP_AUTH_MODE=jwt|oauth on top), logs to /var/log/brapi-mcp-server. OTel peer deps are installed by default — --build-arg OTEL_ENABLED=false to omit.

Deployment shapes

brapi-mcp-server runs in three shapes — pick the one that matches your trust domain. The differentiator is what isolates connection state (registered aliases, cached upstream tokens) and dataframes: nothing, the MCP session, or the auth tenant.

Shape selection guide:

• Multi-user public/institutional HTTP, no SSO. Use the per-session default. Each researcher's stateful HTTP session is isolated even though they all resolve to tenantId='default'.
• Multi-user with institutional SSO. MCP_AUTH_MODE=jwt (HS256, MCP_AUTH_SECRET_KEY) or oauth (JWKS, OAUTH_ISSUER_URL + OAUTH_AUDIENCE). Each user's tid claim carves a tenant — the outer scope. BRAPI_SESSION_ISOLATION=true (default) then sub-scopes inside each tenant for users running parallel sessions, and JWT/OAuth identity binding gives real session-hijack protection on top.
• One researcher, parallel agents. If multiple agents (planner, analyst, writeup) connect as separate MCP clients but should share one workspace, set BRAPI_SESSION_ISOLATION=false and rely on shared trust. This is the shared-workspace shape.
• Stdio. Always one session; isolation is moot. The flag has no effect.

Belt-and-braces under shared trust. Even with BRAPI_SESSION_ISOLATION=false, brapi_dataframe_describe requires an explicit dataframe name on HTTP (no list-all enumeration), and brapi_dataframe_query rejects system-catalog reads (information_schema, pg_catalog, sqlite_master, duckdb_*). The dataframe name is the capability token; possession proves it.

Development

See CLAUDE.md for full architectural rules. Short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage — no console, no direct persistence
• Register new tools in the tools array of createApp() in src/index.ts
• Wrap upstream calls: validate raw → normalize → return output schema; never fabricate missing fields

git clone https://github.com/cyanheads/brapi-mcp-server.git
cd brapi-mcp-server
bun install
cp .env.example .env       # edit if you need credentials
bun run devcheck && bun run test

PRs welcome.

License

Apache-2.0 — see LICENSE.