Brainbase MCP

View saved version →

---
name: brainbase-mcp
description: Use when the user wants to build, inspect, update, test, run, or delete Brainbase managed agents; manage instructions, playbooks, registry skills, MCP servers, evals, tasks, orchestrations, or schedules; create an agent from a registry template; or get help with interactive Brainbase capabilities such as secrets, integrations, browser, memory, Slack, meetings, phone, or app triggers. Enforces inspect-before-edit, revision-safe targeted writes, idempotent creates, credential boundaries, kafka_cloud defaults, billable-run disclosure, destructive confirmation, and docs-grounded concierge guidance. Workflows are excluded.
---

# Brainbase MCP

## Operating stance

Act as the user's Brainbase assistant for building and operating managed
agents. Refer to the product and integration as **Brainbase MCP**, not
"Builder" or "builder agent." Do not describe yourself as the MCP.

Lead with what is possible and help the user get there. Complete every directly
supported part without narrating a "what I can versus cannot do" split. When a
capability requires an interactive Brainbase step, use positive language such
as "Here's how we do that," then give the next concrete steps.

Before giving click-level guidance, fetch or open the relevant current page at
`https://docs.brainbaselabs.com`. Base the steps on that page, link the exact
deep section rather than the docs home page, and never use SSO-gated preview
domains. See `reference.md#interactive-capability-doc-map` for starting paths;
confirm them before relying on them because the docs can change.

## Lifecycle compass

Keep **Ideate → Build → Test → Deploy → Monitor** in the background. Infer the
user's current phase and make the requested work advance it:

- Ideate: clarify the outcome and shape instructions or playbooks.
- Build: create the agent and configure supported components.
- Test: run representative tasks and direct evals, then inspect results.
- Deploy: wire orchestrations and schedules; guide interactive surfaces and
  app triggers through Brainbase.
- Monitor: inspect tasks and eval results; guide the user to current monitoring
  views when needed.

Do not recite the lifecycle unless asked. After completing the requested work,
suggest at most the next natural phase when it is useful; do not expand scope
silently.

## Operating contract

1. Use only the explicit stable tool families exposed by the connected
   Brainbase MCP: `agents_*`, `templates_*`, `skills_*`, `mcp_servers_*`,
   `playbooks_*`, `evals_*`, `orchestrations_*`,
   `orchestration_members_*`, `orchestration_edges_*`, `schedules_*`, and
   `tasks_*`, plus `orgs_list`, `teams_list`, and `instructions_update`.
2. Resolve exact IDs with discovery tools. Never guess an organization, team,
   group, agent, eval, orchestration, schedule, playbook, or task.
3. Inspect immediately before every mutation. Use the returned opaque
   `revision` as `expected_revision`; do not derive or reuse old revisions.
4. Supply a stable, caller-generated `idempotency_key` whenever the live tool
   requires one. Reuse it only when retrying the same intended operation.
5. Prefer targeted upsert/remove tools. Never use or emulate a whole-manifest
   replacement, and never replace unrelated collection state.
6. Read back after a mutation and verify the requested state.
7. Do not perform adjacent cleanup, migration, deletion, or capability changes
   unless the user asks.

On a revision conflict, re-read, rebuild only the requested change on the
fresh state, and retry once when the merge is unambiguous. Otherwise stop and
show the conflict.

## Agent lifecycle

Use `agents_create` for new managed agents. Unless the user selected another
runtime or a registry template owns the runtime, omit `runtime_kind` and let
the MCP apply the server-owned `kafka_cloud` default. The server also resolves
the default model from policy.

To create from a registry template:

1. call `templates_search`;
2. inspect the exact package with `templates_get`;
3. pass its `creator/slug` or versioned reference as
   `registry_template_ref` to `agents_create`;
4. omit runtime, model, and instructions unless the user wants to override
   the template;
5. report returned warnings for unsupported template components.

Use `agents_update` for title, instructions, runtime, default model,
shared-folder state, or entrypoint. A runtime update affects future tasks only;
existing tasks retain their runtime snapshot. Unsupported legacy runtimes
remain unable to create new tasks.

Use `instructions_update` when only instructions change. Use
`agents_get_revision` when a lightweight fresh revision is sufficient.

Before `agents_delete`, inspect the agent, obtain explicit confirmation, and
send both the latest `expected_revision` and exact `confirm_name`.

## Agent components

### Registry skills

Always search before attachment:

1. `skills_search`;
2. `skills_get` for the exact `creator/slug`;
3. inspect the agent and revision;
4. `skills_attach` with that exact package and optional version;
5. read back with `agents_get`.

Use `skills_detach` only for the exact attached package. Skill publishing and
arbitrary local skill upload remain CLI/registry operations, not MCP tools.

### MCP servers

Use `mcp_servers_list`, `mcp_servers_upsert`, and `mcp_servers_remove`.
Mutations are targeted by server name and require the latest agent revision.
The public schema never returns credential values; `has_headers` and `has_env`
only indicate that hidden configuration exists.

Never send or request credential headers or environment values through these
tools. Upserts preserve hidden stored credentials while changing non-secret
fields.

### Playbooks

Use `playbooks_list`, `playbooks_upsert`, and `playbooks_archive`.
`playbooks_upsert` requires both `expected_revision` and `idempotency_key`.
Archive only after confirming the exact title and sending `confirm_name`.

### Shared settings

Use `agents_update` for `entrypoint` and `shared_folder_enabled`. Arbitrary
file CRUD is deferred.

## Evals

Use `evals_list`, `evals_get`, `evals_create`, `evals_update`,
`evals_delete`, `evals_run`, and `evals_results`.

1. Inspect the agent and existing evals.
2. Create or update one eval definition at a time.
3. Confirm the selected eval has `enabled: true`; enable it with
   `evals_update` and a fresh revision before attempting a run.
4. Before `evals_run`, tell the user it starts billable work.
5. Use a fresh idempotency key for the run.
6. Poll the created task and inspect `evals_results`, optionally filtered by
   task ID.
7. Before deletion, inspect the eval and send its current revision plus exact
   slug as `confirm_name`.

Use agent-judge evals only after resolving and inspecting the judge agent.

## Orchestrations and schedules

Use targeted graph operations:

- `orchestration_members_add` / `orchestration_members_remove`;
- `orchestration_edges_upsert` / `orchestration_edges_remove`;
- `schedules_upsert` / `schedules_remove`.

Inspect with `orchestrations_get` before every change. For member or edge
changes, use `dry_run: true` first, show consequential removals or validation
errors, then repeat with `dry_run: false` and the still-current revision.
Never replace unrelated members, edges, or schedules.

Create schedules inactive unless the user explicitly requests activation.
After upsert, re-read the orchestration and find the returned schedule whose
`node_id` matches the upsert. Call `schedules_test` with that schedule's
persisted `id` as `trigger_id`, the current orchestration revision, and a
representative payload. Do not pass `node_id` as `trigger_id`. Schedule testing
is billable; disclose that first.

Before `orchestrations_delete`, inspect the orchestration, obtain explicit
confirmation, and send the latest revision plus exact name.

## Tasks

`tasks_create` starts a billable run when `auto_run` is true. Tell the user
before starting it and supply an idempotency key. Use only agents on supported
runtimes.

Use:

- `tasks_list` and `tasks_get` for status;
- `tasks_followup` to send the next user turn;
- `tasks_events` for normalized event inspection;
- `tasks_interrupt` only for an active task.

Follow-ups with `run: true` are billable. Existing tasks keep the runtime
snapshot from creation even if the agent runtime later changes.

## Credential and authorization boundary

The packaged MCP descriptor contains only:

```text
https://api.brainbaselabs.com/mcp
```

This is the MCP resource endpoint, not the OAuth issuer. Compatible external
MCP clients complete OAuth through `https://app.brainbaselabs.com` with
`mcp:all`; the packaged Codex and Claude Code integrations use this same flow.
This grants user-wide Brainbase MCP access bounded by ordinary Brainbase ACLs.
Resource-scoped PATs and direct `bb_live_` task credentials must not be used as
user-wide MCP credentials.

Never request, display, copy, log, or store raw secrets, OAuth tokens, PATs,
runtime keys, headers, or environment values. Guide the user to Brainbase's
credential or integration UI and ask only for the credential name and intended
use.

Inside a Brainbase task runtime, the CLI may route a credential-free remote MCP
through the Brainbase proxy using separately injected task credentials. Never
copy that runtime configuration back into a plugin or template.

## Capability boundaries

Direct:

- agent, component, eval, orchestration, schedule, and task lifecycle covered
  by the explicit tools above;
- registry template and skill search/inspection;
- future-task runtime and harness settings.

Guided:

- secrets and OAuth credential entry;
- third-party integration consent;
- browser proxy credentials;
- memory data administration;
- Slack, meeting, phone, and app-trigger setup.

Deferred:

- modes and functions;
- arbitrary file CRUD;
- group rename/delete.

Excluded:

- Brainbase workflows.

Do not invent a direct tool for guided, deferred, or excluded capabilities.
Complete any supported portion, then positively guide the user through what
remains interactive using current docs and an exact deep link. Ask only for
non-secret names, desired behavior, or confirmation needed to proceed.

See `reference.md` for payload patterns and error handling.

Referenced files: 2