Orchestrations

Orchestration Tools

An orchestration can own custom MCP server definitions of its own, independent of any member agent's tools. Every member agent receives them the next time it bootstraps a task. Use one when several agents in the same process need the same tool server — an internal ticketing MCP, a shared search index — instead of configuring it on each agent.

How to set orchestration tools

01Open the orchestration's Tools page.
02Click Add MCP server.
03Enter a name, transport (a URL for a remote server or a command for one that runs in the member's own sandbox), and any arguments, headers, or environment variables it needs.
04Save your changes.

How composition works

At each task's bootstrap, an agent's available MCP servers are composed by name from three layers, in priority order:

The reserved built-in. When MAS is serving brainbase-linear for an agent, it always wins over any row of that name — an orchestration cannot define a same-named server (see below), and even an agent's own row of that name does not override it.
The agent's own server of that name. An enabled server on the agent overrides the orchestration's definition and wins over the optional brainbase_meeting / brainbase_github built-ins; a disabled server on the agent suppresses the orchestration's definition entirely.
The orchestration's inherited definition. Used only when neither of the above claims the name.

Edits land on the next manifest pull

Adding, editing, or removing an orchestration MCP server changes what a member receives the next time it pulls its manifest. For most tasks that is the next task bootstrap. A task already in progress picks up the edit only if it pulls again, for example after a harness restart or an in-task brainbase agent pull.

URLs and secret references

Secret references: ${NAME} inside an env or header value references one of the orchestration's own secrets by name. It is validated against the orchestration's current secret keys when you save, and expanded inside the member's sandbox at run time. MAS never stores or returns the referenced value — API responses carry only variable names and, for a referenced value, the secret's name.
Reserved names: A server name starting with brainbase- or brainbase_ is rejected, so an orchestration server cannot collide with a platform built-in.
Destination validation: A remote server's url must be HTTPS, with no userinfo, no dot segments, no fragment, and no loopback, private, link-local, or otherwise reserved destination. This is checked when you save it, and checked again by the MCP proxy every time a member connects.

Overrides and suppression

An inherited server appears on the agent's own Tools page as a read-only block naming the orchestration it comes from, with Override and Suppress actions. Override copies the server's URL or command to the agent as an agent-owned row. Environment-variable and header values are never returned by the API, so they are not carried over: enter them again on the override, or reference orchestration secrets as ${NAME}. Suppress adds a disabled server of the same name to the agent, which stops the agent from receiving the inherited one without giving it a definition of its own.

The inherited definition is never copied onto the agent

brainbase agent status shows an inherited server for visibility, but brainbase agent push leaves the orchestration's copy unchanged — it is not part of the agent's own manifest. If you edited the inherited block locally before pushing, the CLI warns that the edit was not applied anywhere.

Belonging to more than one orchestration

No inheritance when membership is ambiguous

An agent that belongs to more than one orchestration inherits nothing from either — the platform cannot tell which orchestration's servers should apply. Its inherited-tools read reports the condition rather than guessing.

When changes take effect

Adding or editing a server: Applies the next time the member pulls its manifest, which for most tasks is the next task bootstrap. A task already running picks up the change only if it pulls again.
Removing a server: The member stops receiving it on its next manifest pull, usually the next task bootstrap.
Removing an agent from the orchestration: The agent loses the inherited servers on its next manifest pull, usually the next task bootstrap.

Non-goals for v1

Orchestration-level OAuth for MCP servers. Every orchestration server authenticates with static values — headers, environment variables, or secret references — not a connected OAuth session.
The legacy kafka (KLS-hosted) runtime does not receive orchestration MCP servers.
Health or connectivity status for an inherited server is not surfaced separately from the agent's own tool status.

Where this appears

The orchestration's own Tools page, where servers are added, edited, and removed.
The agent's Tools page, as a read-only inherited block with Override and Suppress.
brainbase agent status, which lists inherited servers and flags an override or suppression.
brainbase mcp list, which prints the agent's own rows plus inherited entries; the synthesized built-ins (brainbase-linear, brainbase_meeting, brainbase_github) don't appear there.

API

Endpoint	Behavior
`GET /v2/orchestrations/{id}/mcp-servers`	Returns `{enabled, servers[]}`. A deployment without the feature answers `enabled: false` with an empty list rather than 503 — but a missing or inaccessible orchestration still answers `404`.
`POST /v2/orchestrations/{id}/mcp-servers`	Creates a server; `201` on success. Body: `{name, url, command, args, env, headers, is_enabled, icon, icon_color}` — at least one of `url` or `command` is required; only `name` is otherwise required.
`PUT /v2/orchestrations/{id}/mcp-servers/{name}`	Partial update, named by the path; the name itself cannot be changed. `env` and `headers` are write-only and merge by omission: omitted keeps the stored value, `null` clears it, `{}` is a no-op, and a non-empty object replaces it entirely. `args: null` clears args to `[]`. `is_enabled: null` is rejected with `400`.
`DELETE /v2/orchestrations/{id}/mcp-servers/{name}`	Removes a server by name; `204` on success. Members stop receiving it on their next manifest pull, usually the next task bootstrap.
`GET /v2/agents/{id}/mcp-servers/inherited`	Returns `{enabled, source, ambiguous, degraded, warnings[], servers[]}`, where `source` is `{kind, id, name}` (or `null`) and each server in `servers[]` carries `status: inherited \| overridden \| suppressed`. Needs a principal that represents the user: a session or a user-scoped PAT. A resource-scoped PAT (agent, thread, or task) answers `404`.

A missing orchestration, agent, or server answers 404

All five endpoints answer 404 for an orchestration or agent that doesn't exist or that the caller can't reach — the same cannot-confirm-existence rule as orchestration secrets. PUT and DELETE also answer 404 when the name doesn't match an existing server on that orchestration.

A server object in any response is {id, name, url, command, args, is_enabled, icon, icon_color, env_refs, env_keys, headers_refs, headers_keys, created_at, updated_at} — on the inherited-tools read, each server additionally carries status: inherited | overridden | suppressed. As with orchestration secrets, values are write-only: env_keys and headers_keys list the configured variable names, and env_refs / headers_refs name the orchestration secret a ${NAME}-referenced value points at — the value itself is never in the response.

Auth follows the same rules as orchestration secrets: a member with manage access can read, a PAT needs the publish scope to write, and the inherited-tools read on the agent takes a session or a user-scoped PAT and answers 404 to a resource-scoped one.

Status	Code	Meaning
`400`	`invalid_name` / `reserved_name`	The name is malformed, or starts with `brainbase-` / `brainbase_`.
`400`	`transport_required`	Neither `url` nor `command` was given.
`400`	`reference_not_allowed`	A `${` appeared in `url`, `command`, or `args`. A `${` in `name` answers `invalid_name` instead; `icon` and `icon_color` are not checked.
`400`	`invalid_value`	A field failed validation.
`400`	`invalid_secret_reference` / `unknown_secret_reference`	A `${NAME}` reference is malformed, or names a key the orchestration does not currently have.
`400`	`invalid_destination`	The URL failed the HTTPS / userinfo / dot-segment / fragment / loopback / private / link-local / reserved checks.
`409`	`scoped_mcp_server_exists`	A server with that name already exists on this orchestration.
`503`	`orchestration_mcp_servers_disabled`	The feature is off for this deployment.
`503`	`orchestration_secrets_unavailable`	A `${NAME}` reference could not be validated against the orchestration's secrets.
`503`	`mcp_destination_policy_unavailable`	The destination URL could not be validated.
`404`	—	An unknown or inaccessible orchestration, an unknown server name, an unknown or inaccessible agent, or a credential that isn't allowed to read this orchestration's or agent's topology.

A 400, 409, or 503 body is {"detail": {"code": "...", "message": "..."}}. A 404 is different — it carries a plain string detail (for example {"detail": "MCP server not found"}), not the code / message envelope, because it is a generic not-found rather than a validation, conflict, or availability outcome specific to this feature.