Skip to main content
Glama

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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "brapi_connect"
  }
}

Input Schema

NameRequiredDescriptionDefault
authNoAuth payload. Omit to use credentials configured server-side for this alias (or no auth when none are configured).
aliasNoAlias for this connection. Use distinct aliases to register multiple BrAPI servers in one session.default
baseUrlNoBrAPI 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

NameRequiredDescriptionDefault
authNoAuth summary for the active connection.
aliasNoConnection alias.
errorNoPresent when the call failed. Absent on success.
notesNoServer-specific quirks or degradation notes.
serverNoNormalized server identity block.
baseUrlNoBrAPI v2 base URL for this connection.
contentNoContent summary (crops + optional totals).
dialectNoActive dialect adapter — translates outbound filters and declares known-dead routes for this server.
fetchedAtNoISO 8601 timestamp of when this envelope was composed.
attributionNoAttribution metadata for built-in known-server connections. Absent when the alias is not built-in or points away from its built-in base URL.
capabilitiesNoCapability profile derived from /serverinfo or /calls.
nextToolSuggestionsNoEntry-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.

  1. Changed2 schema fields changed
    • 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. `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."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_not_found`: Both /serverinfo and /calls return HTTP 404. `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",
      -  "alias_base_url_invalid",
      -  "private_address_blocked",
      -  "auth_token_exchange_failed",
      -  "auth_no_access_token",
      -  "upstream_unauthorized",
      -  "upstream_forbidden",
      -  "capability_discovery_unavailable"
      -]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_not_found",
      +  "capability_discovery_unavailable"
      +]
  2. Changed9 schema fields changed
    • 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)."
  3. Changed4 schema fields changed
    • 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"
      +}
  4. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare openWorldHint=true, idempotentHint=true and readOnlyHint=false, but the description adds material context beyond them: no-MCP-session callers share one alias namespace, so re-registering an alias silently re-points other callers' later requests, and credentials may be configured server-side and omitted. That names the actual side effect of an alias write, which the annotations alone do not convey; the envelope's contents are covered by the output schema, so nothing critical is missing.

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 verb and return payload, then conditional guidance, then the inventories — a sensible order. However, the closing sentence "Aliases are shortcuts only; any other BrAPI v2 server is reachable by passing `baseUrl` directly" restates the already-given baseUrl rule, and the nested parentheticals make the middle dense.

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?

For a connection-bootstrap tool with an output schema and full schema coverage, this is complete: it covers auth fallbacks, alias namespacing, concurrency, known-server shortcuts, and the re-pointing caveat. Nothing an agent needs to call it correctly is absent.

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 baseline is 3, but the description adds real semantics: `alias` selects among concurrent connections and is re-pointable, `baseUrl` must include any path prefix and is only needed for non-aliased servers, and `auth` may be omitted to fall back to server-side credentials. It stops short of mapping individual auth modes, which is acceptable since the schema's oneOf variants already document them.

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 compound action — open a connection to a BrAPI v2 server, authenticate, and return an orientation envelope — and explicitly contrasts it with the sibling family, which "connect an alias the server has a URL configured for ... on first use." An agent can distinguish this bootstrap tool from the find/get siblings without opening either schema.

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?

Gives explicit when-to-use conditions ("call this to connect any other server by `baseUrl`, to pass `auth`, or to re-point an alias") plus the when-not case (other BrAPI tools already auto-connect built-in and operator-configured aliases). It also names the three built-in servers and the deployment aliases so the agent knows when this call is unnecessary.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.