@cyanheads/brapi-mcp-server

Инструменты

25 инструментов, сгруппированных по типу: инструменты подключения инициализируют сессию; инструменты find_* возвращают сводную страницу с распределениями и выгружают избыточные строки в canvas-датафрейм, который агенты той же сессии могут запрашивать или передавать по ID; инструменты get_* получают отдельную запись с сопутствующими счётчиками. Плюс обход родословной, встроенное SQL-рабочее пространство над выгруженными строками (на базе DuckDB), экспорт файлов для передачи человеку, аддитивная поверхность записи наблюдений и прямые обходные каналы (raw passthrough).

Ориентация

Получение

Анализ

Запись (включается через BRAPI_ENABLE_WRITES=true)

Обходные каналы

Обнаружение псевдонимов. Встроенные и настроенные оператором псевдонимы добавляются к описанию brapi_connect при запуске сервера, поэтому агенты видят перечень в tools/list. После изменения переменных окружения перезапустите сервер для обновления.

Related MCP server: Helix MCP Server

Ресурсы

Адресуемые по URI зеркала курируемой поверхности инструментов для клиентов, предпочитающих ресурсы. Все ресурсы используют подключение по умолчанию — мультисерверные сценарии маршрутизируются через инструменты.

Промпты

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

Clients on MCP revision 2026-07-28. That revision is session-less on every transport — requests carry no Mcp-Session-Id — so ctx.sessionId is undefined and a client negotiating it falls back to the shared tenant workspace even under MCP_SESSION_MODE=stateful. Session isolation applies to 2025-era clients; deployments that need a hard boundary for 2026-era clients should carve tenants with MCP_AUTH_MODE=jwt/oauth.

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. Walks larger than loadLimit spill their node and edge sets to two JOINable canvas dataframes and return a bounded inline preview.

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

Переопределения для отдельных алиасов следуют шаблону BRAPI_<ALIAS>_* — см. .env.example для всех переопределений и встроенных комментариев.

Учётные данные для отдельных алиасов

brapi_connect берёт baseUrl и auth из переменных окружения, когда агент их не указывает, — учётные данные никогда не попадают в контекст LLM. Четыре уровня приоритета:

1. Явный ввод агента — всегда имеет приоритет.

2. Переменные окружения для отдельных алиасов — BRAPI_<ALIAS>_* (в верхнем регистре, дефисы → подчёркивания: my-server → BRAPI_MY_SERVER_*).

3. Встроенный реестр известных серверов — см. Встроенные алиасы.

4. Переменные окружения по умолчанию — BRAPI_DEFAULT_*, только когда алиас отличается от default. Не наслаиваются поверх встроенного URL — значения по умолчанию относятся к серверу по умолчанию.

Каждый алиас несёт одно семейство учётных данных — режим аутентификации определяется тем, какие поля заданы:

Смешение семейств в рамках одного алиаса вызывает 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

Затем агент вызывает brapi_connect({ alias: 'bti-cassava' }) — без baseUrl, без auth, без секретов в промпте.

Встроенные алиасы

Сервер поставляется с курируемым реестром публичных BrAPI v2 эндпоинтов. Каждый из них работает из коробки; ориентационная оболочка выводит лицензию, цитирование и домашнюю страницу в своём блоке attribution под лицензией Creative Commons Attribution.

Установите BRAPI_<ALIAS>_BASE_URL, чтобы перенаправить на staging-зеркало или форк (переменные окружения имеют приоритет над встроенным URL — дефисы в алиасе становятся подчёркиваниями в переменной окружения, так что t3-wheat → BRAPI_T3_WHEAT_BASE_URL). Установите BRAPI_<ALIAS>_USERNAME и т.д., чтобы добавить учётные данные поверх встроенного URL — у каждого экземпляра Breedbase своя таблица пользователей, поэтому для доступа на запись требуется отдельная регистрация в каждом апстриме. Используйте BRAPI_BUILTIN_ALIASES_DISABLED=bti-cassava,t3-wheat, чтобы удалить конкретные записи.

Цитирование: все шесть встроенных алиасов ссылаются на Morales et al. 2022, "Breedbase: a digital ecosystem for modern plant breeding." G3 12(7): jkac078. doi:10.1093/g3journal/jkac078.

Запуск сервера

# 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

По умолчанию используется HTTP-транспорт, режим сессий с сохранением состояния (задействует жизненный цикл mcp-session-id — обязательное условие для BRAPI_SESSION_ISOLATION=true; защита от перехвата требует добавления MCP_AUTH_MODE=jwt|oauth поверх), логи пишутся в /var/log/brapi-mcp-server. OTel peer-зависимости устанавливаются по умолчанию — --build-arg OTEL_ENABLED=false, чтобы исключить их.

Формы развёртывания

brapi-mcp-server работает в трёх формах — выберите ту, которая соответствует вашему домену доверия. Отличие заключается в том, что изолирует состояние соединений (зарегистрированные алиасы, кэшированные токены апстрима) и датафреймы: ничего, MCP-сессия или тенант аутентификации.

Руководство по выбору формы:

• Многопользовательский публичный/институциональный HTTP без SSO. Используйте вариант по умолчанию — на сессию. Stateful HTTP-сессия каждого исследователя изолирована, даже если все они разрешаются в tenantId='default'.

• Многопользовательский режим с институциональным SSO. MCP_AUTH_MODE=jwt (HS256, MCP_AUTH_SECRET_KEY) или oauth (JWKS, OAUTH_ISSUER_URL + OAUTH_AUDIENCE). JWT-утверждение tid каждого пользователя выделяет тенант — внешнюю область. BRAPI_SESSION_ISOLATION=true (по умолчанию) затем дополнительно ограничивает сессии внутри каждого тенанта для пользователей, запускающих параллельные сессии, а привязка идентичности JWT/OAuth даёт настоящую защиту от перехвата сессий поверх.

• Один исследователь, параллельные агенты. Если несколько агентов (планировщик, аналитик, оформитель) подключаются как отдельные MCP-клиенты, но должны использовать одно рабочее пространство, установите BRAPI_SESSION_ISOLATION=false и полагайтесь на общую доверенность. Это и есть форма общего рабочего пространства.

• Stdio. Всегда одна сессия; изоляция не имеет значения. Флаг не влияет.

• Клиенты на MCP-ревизии 2026-07-28. По протоколу они не используют сессии, поэтому попадают в общее рабочее пространство тенанта независимо от значения BRAPI_SESSION_ISOLATION. Изолировать их может только форма с учётными данными на пользователя.

Подстраховка при общей доверенности. Даже с BRAPI_SESSION_ISOLATION=false brapi_dataframe_describe требует явное имя dataframe на HTTP (без перечисления всех), а brapi_dataframe_query отклоняет чтение системных каталогов (information_schema, pg_catalog, sqlite_master, duckdb_*). Имя датафрейма — это токен возможности; обладание им доказывает право.

Разработка

Полные архитектурные правила см. в CLAUDE.md. Краткая версия:

• Обработчики выбрасывают исключения, фреймворк перехватывает их — никаких try/catch в логике инструментов

• Используйте ctx.log для логирования и ctx.state для хранения — никакого console, никакого прямого сохранения

• Регистрируйте новые инструменты в массиве tools в createApp() в src/index.ts

• Оборачивайте вызовы апстрима: проверяйте сырые данные → нормализуйте → возвращайте выходную схему; никогда не выдумывайте отсутствующие поля

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

PR приветствуются.

Лицензия

Apache-2.0 — см. LICENSE.