brapi-mcp-server

Brapi Connect

brapi_connect

Idempotent

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.

Input Schema

Name	Required	Description	Default
`auth`	No	Auth payload. Omit to use credentials configured server-side for this alias (or no auth when none are configured).
`alias`	No	Alias for this connection. Use distinct aliases to register multiple BrAPI servers in one session.	default
`baseUrl`	No	BrAPI v2 base URL (absolute URL) including any path prefix — e.g. https://test-server.brapi.org/brapi/v2. Omit to use the configured default for this alias.

Output Schema

Name	Required	Description
`auth`	No	Auth summary for the active connection.
`alias`	No	Connection alias.
`error`	No	Present when the call failed. Absent on success.
`notes`	No	Server-specific quirks or degradation notes.
`server`	No	Normalized server identity block.
`baseUrl`	No	BrAPI v2 base URL for this connection.
`content`	No	Content summary (crops + optional totals).
`dialect`	No	Active dialect adapter — translates outbound filters and declares known-dead routes for this server.
`fetchedAt`	No	ISO 8601 timestamp of when this envelope was composed.
`attribution`	No	Attribution metadata for built-in known-server connections. Absent when the alias is not built-in or points away from its built-in base URL.
`capabilities`	No	Capability profile derived from /serverinfo or /calls.
`nextToolSuggestions`	No	Entry-point finders (studies, germplasm, variables, locations — in that order) whose GET or POST /search route this server exposes under the active dialect. Empty when none apply.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedOct 18, 2026

changedOutput schema / properties / attribution / description

Previous value: -"Attribution metadata for built-in known-server connections. Absent for custom (env-only) connections."New value: +"Attribution metadata for built-in known-server connections. Absent when the alias is not built-in or points away from its built-in base URL."

changedOutput schema / properties / capabilities / description

Previous value: -"Capability profile derived from /serverinfo."New value: +"Capability profile derived from /serverinfo or /calls."

changedOutput schema / properties / capabilities / properties / supportedCount / description

Previous value: -"Total distinct services the server advertises in /calls."New value: +"Total distinct services the server advertises in /serverinfo or /calls."

changedOutput schema / properties / dialect / properties / id / description

Previous value: -"Active dialect id (e.g. \"spec\", \"cassavabase\"). Names a registered adapter that translates outbound filters and declares known-dead routes."New value: +"Active dialect id (e.g. \"spec\", \"cassavabase\")."

changedOutput schema / properties / dialect / properties / inferredMappingCount / description

Previous value: -"Number of filter translations inferred from naming conventions but not independently verified. A non-zero count means some result narrowing on this server may not fire as expected."New value: +"Filter translations inferred from naming conventions, unverified; when non-zero, some narrowing on this server may not fire."

changedOutput schema / properties / dialect / properties / verifiedMappingCount / description

Previous value: -"Number of filter translations the dialect has empirically verified against a live server. Higher means more confidence in the translation table."New value: +"Filter translations verified against a live server. Absent when the dialect publishes no mapping summary."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `auth_session_required`: Caller-supplied credentials on an HTTP deployment without per-user auth, from a request that carries no MCP session. `auth_base_url_mismatch`: The alias has server-configured credentials and the supplied baseUrl differs from the server configured for it. `alias_base_url_unset`: The alias has server-configured credentials but no base URL of its own (no BRAPI_<ALIAS>_BASE_URL and no enabled built-in), so they pair with no server. `auth_token_exchange_failed`: SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Token endpoint responded but did not return an access_token. `upstream_unauthorized`: The server answered HTTP 401 on /serverinfo or /calls — it requires login for capability discovery. `upstream_forbidden`: The server answered HTTP 403 on /serverinfo or /calls — the request (anonymous or credentialed) lacks read access. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `auth_session_required`: Caller-supplied credentials on an HTTP deployment without per-user auth, from a request that carries no MCP session. `auth_base_url_mismatch`: The alias has server-configured credentials and the supplied baseUrl differs from the server configured for it. `alias_base_url_unset`: The alias has server-configured credentials but no base URL of its own (no BRAPI_<ALIAS>_BASE_URL and no enabled built-in), so they pair with no server. `alias_base_url_invalid`: With no `baseUrl` passed, the base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL, or the OAuth token URL, is on a private or reserved address this server may not reach. `auth_token_exchange_failed`: SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Token endpoint responded but did not return an access_token. `upstream_unauthorized`: The server answered HTTP 401 on /serverinfo or /calls — it requires login for capability discovery. `upstream_forbidden`: The server answered HTTP 403 on /serverinfo or /calls — the request (anonymous or credentialed) lacks read access. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "auth_session_required",
-  "auth_base_url_mismatch",
-  "alias_base_url_unset",
-  "auth_token_exchange_failed",
-  "auth_no_access_token",
-  "upstream_unauthorized",
-  "upstream_forbidden"
-]New value: +[
+  "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"
+]

changedOutput schema / properties / nextToolSuggestions / items / properties / args / description

Previous value: -"Arguments to call the tool with. Alias only — narrow further with the tool filters."New value: +"Arguments to start the tool with (alias only)."

Changed4 schema fields changedSep 24, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "alias",
-      "baseUrl",
-      "server",
-      "auth",
-      "capabilities",
-      "dialect",
-      "content",
-      "notes",
-      "fetchedAt"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "alias",
+      "baseUrl",
+      "server",
+      "auth",
+      "capabilities",
+      "dialect",
+      "content",
+      "nextToolSuggestions",
+      "notes",
+      "fetchedAt"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `auth_token_exchange_failed`: SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Token endpoint responded but did not return an access_token. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `auth_session_required`: Caller-supplied credentials on an HTTP deployment without per-user auth, from a request that carries no MCP session. `auth_base_url_mismatch`: The alias has server-configured credentials and the supplied baseUrl differs from the server configured for it. `alias_base_url_unset`: The alias has server-configured credentials but no base URL of its own (no BRAPI_<ALIAS>_BASE_URL and no enabled built-in), so they pair with no server. `auth_token_exchange_failed`: SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Token endpoint responded but did not return an access_token. `upstream_unauthorized`: The server answered HTTP 401 on /serverinfo or /calls — it requires login for capability discovery. `upstream_forbidden`: The server answered HTTP 403 on /serverinfo or /calls — the request (anonymous or credentialed) lacks read access. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "auth_token_exchange_failed",
-  "auth_no_access_token"
-]New value: +[
+  "auth_session_required",
+  "auth_base_url_mismatch",
+  "alias_base_url_unset",
+  "auth_token_exchange_failed",
+  "auth_no_access_token",
+  "upstream_unauthorized",
+  "upstream_forbidden"
+]

addedOutput schema / properties / nextToolSuggestions

Added value: +{
+  "description": "Entry-point finders (studies, germplasm, variables, locations — in that order) whose GET or POST /search route this server exposes under the active dialect. Empty when none apply.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A finder the connected server supports, with the arguments to start it.",
+    "properties": {
+      "args": {
+        "additionalProperties": false,
+        "description": "Arguments to call the tool with. Alias only — narrow further with the tool filters.",
+        "properties": {
+          "alias": {
+            "description": "Connection alias to pass to the suggested tool.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "alias"
+        ],
+        "type": "object"
+      },
+      "reason": {
+        "description": "Why this tool applies to the connected server.",
+        "type": "string"
+      },
+      "toolName": {
+        "description": "Entry-point finder tool this server can serve.",
+        "enum": [
+          "brapi_find_studies",
+          "brapi_find_germplasm",
+          "brapi_find_variables",
+          "brapi_find_locations"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "toolName",
+      "reason",
+      "args"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

First observedSep 19, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true): it discloses that credentials can be server-side and omitted, that aliases can be re-pointed, that multiple concurrent connections are supported, and critically that on sessionless deployments aliases share one namespace so re-registering re-points other callers' future calls. These are non-obvious state semantics an agent must know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and return value, then layered with operational caveats. The single dense paragraph is long but nearly every clause carries unique, actionable information; a slight tightening would help readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists and the description still names what the envelope contains (server identity, capability profile, content summary, suggested next tools). For a connection/registration tool with rich auth semantics, no decision-relevant detail is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the schema already documents the auth variants and parameter shapes, and the description mostly echoes the omit-fallbacks for auth/baseUrl. It does add routing value by enumerating the built-in and operator-configured aliases and clarifying that aliases are shortcuts only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (open a connection to a BrAPI v2 server, authenticate) and names the return payload (orientation envelope). It clearly distinguishes itself from the 20 sibling brapi_* tools, which operate on already-connected aliases rather than establishing one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to call it -- to connect any server by baseUrl, to pass auth, or to re-point an alias -- and contrasts that with the default behavior of other tools, which auto-connect configured aliases on first use. Even enumerates the currently callable known servers and operator aliases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All brapi-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.