# Brainbase MCP reference

This reference describes the explicit public Brainbase MCP at
`https://api.brainbaselabs.com/mcp`. Prefer the connected tool schema if a
deployed version differs.

## Stable tool inventory

Discovery:

```text
orgs_list
teams_list
```

Agents and settings:

```text
agents_list
agents_create
agents_get
agents_update
instructions_update
agents_get_revision
agents_delete
```

Registry packages and components:

```text
templates_search
templates_get
skills_search
skills_get
skills_attach
skills_detach
mcp_servers_list
mcp_servers_upsert
mcp_servers_remove
playbooks_list
playbooks_upsert
playbooks_archive
```

Evals:

```text
evals_list
evals_create
evals_get
evals_update
evals_delete
evals_run
evals_results
```

Orchestrations:

```text
orchestrations_list
orchestrations_create
orchestrations_get
orchestrations_update
orchestrations_delete
orchestration_members_add
orchestration_members_remove
orchestration_edges_upsert
orchestration_edges_remove
schedules_upsert
schedules_remove
schedules_test
```

Tasks:

```text
tasks_create
tasks_list
tasks_get
tasks_followup
tasks_interrupt
tasks_events
```

## Revisions and idempotency

Every editable MCP resource exposes an opaque `revision`. Read immediately
before mutation and pass it as `expected_revision`.
Revision numbers in examples are illustrative placeholders, not values to
copy. Always pass the exact revision returned by the latest read.

Required idempotency keys:

- `agents_create`
- `playbooks_upsert`
- `evals_create`
- `evals_run`
- `orchestrations_create`
- `tasks_create`

Use a unique key of 8–200 characters for a new intent. Reuse the same key only
to retry that identical request.

## Create an agent

Tool: `agents_create`

```json
{
  "idempotency_key": "agent-support-triage-01",
  "title": "Support triage",
  "group_id": "resolved-group-uuid",
  "instructions": "Triage requests and propose the safest next action."
}
```

When `runtime_kind` is omitted, ordinary MCP creation defaults to
`kafka_cloud`. Omit `machine_kind` and `default_model` unless the user chose
them.

Create from a registry template:

```json
{
  "idempotency_key": "agent-support-template-01",
  "title": "Support triage",
  "group_id": "resolved-group-uuid",
  "registry_template_ref": "brainbase/support-triage"
}
```

Search and inspect the exact template first. A versioned reference may be used
when supported by the selected package. Omit runtime, model, and instructions
to preserve the template's values. Report `template_warnings`.

## Update or delete an agent

Tool: `agents_update`

```json
{
  "agent_id": "agent-uuid",
  "expected_revision": 1837462,
  "runtime_kind": "kafka_cloud",
  "default_model": "requested-model",
  "shared_folder_enabled": true,
  "entrypoint": "main"
}
```

Only supplied fields change. Runtime changes apply to future tasks; existing
tasks retain their creation-time runtime snapshot.

For instructions only:

```json
{
  "agent_id": "agent-uuid",
  "expected_revision": 1837462,
  "instructions": "Updated operating instructions."
}
```

Tool: `instructions_update`

Delete only after exact-name confirmation:

```json
{
  "agent_id": "agent-uuid",
  "expected_revision": 1837462,
  "confirm_name": "Support triage"
}
```

Tool: `agents_delete`

## Registry skills

Search before attachment:

```text
skills_search(q="support")
skills_get(creator="brainbase", slug="support-triage")
```

Then attach:

```json
{
  "agent_id": "agent-uuid",
  "expected_revision": 1837462,
  "creator": "brainbase",
  "slug": "support-triage",
  "version": "1.2.0"
}
```

Tool: `skills_attach`

`version` is optional. Detach with the same package identity through
`skills_detach`. Package publishing remains a CLI/registry operation.

## MCP servers

Read with `mcp_servers_list`. Responses include only safe fields and the
booleans `has_headers` and `has_env`.

Targeted upsert:

```json
{
  "agent_id": "agent-uuid",
  "expected_revision": 1837462,
  "name": "ticketing",
  "url": "https://example.com/mcp",
  "is_enabled": true
}
```

Tool: `mcp_servers_upsert`

Targeted remove:

```json
{
  "agent_id": "agent-uuid",
  "expected_revision": 1837462,
  "name": "ticketing"
}
```

Tool: `mcp_servers_remove`

Do not send headers, environment values, tokens, or secrets. A non-secret
upsert preserves hidden credentials already stored for that named server.

## Playbooks

Read with `playbooks_list`, which returns `revision` and the active items.

```json
{
  "agent_id": "agent-uuid",
  "expected_revision": 1837462,
  "idempotency_key": "playbook-triage-ticket-01",
  "title": "Triage ticket",
  "description": "Classify and route a support ticket.",
  "body": "Inspect the request and propose the next action."
}
```

Tool: `playbooks_upsert`

Include `playbook_id` when updating an existing playbook. Archive with:

```json
{
  "agent_id": "agent-uuid",
  "expected_revision": 1837463,
  "playbook_id": "playbook-uuid",
  "confirm_name": "Triage ticket"
}
```

Tool: `playbooks_archive`

## Evals

Create:

```json
{
  "agent_id": "agent-uuid",
  "idempotency_key": "eval-safe-routing-01",
  "slug": "safe-routing",
  "criteria": "The response proposes a safe and actionable route.",
  "judge_type": "model",
  "output_shape": "binary",
  "enabled": true
}
```

Tool: `evals_create`

Use `evals_get` immediately before `evals_update` or `evals_delete`. Updates
send only requested fields plus `expected_revision`.

Run one eval:

```json
{
  "agent_id": "agent-uuid",
  "idempotency_key": "eval-run-safe-routing-01",
  "eval_id": "eval-uuid",
  "prompt": "A customer cannot sign in after resetting their password.",
  "title": "Safe routing representative case"
}
```

Tool: `evals_run`

The selected eval must have `enabled: true`. If it is disabled, use
`evals_update` with its fresh revision, read it back, and only then run it.
This starts billable work. Inspect the returned task with `tasks_get`, then read
verdicts with:

```text
evals_results(agent_id="agent-uuid", task_id="task-uuid")
```

Delete only after confirming the exact eval slug:

```json
{
  "agent_id": "agent-uuid",
  "eval_id": "eval-uuid",
  "expected_revision": 452187,
  "confirm_name": "safe-routing"
}
```

## Create and update an orchestration

Tool: `orchestrations_create`

```json
{
  "idempotency_key": "orch-support-routing-01",
  "group_id": "group-uuid",
  "name": "Support routing",
  "description": "Route researched support cases.",
  "members": []
}
```

Use `orchestrations_update` for scalar fields such as name, description, icon,
credit limit, or metadata. Use targeted member, edge, and schedule tools for
graph changes.

Member dry run:

```json
{
  "orchestration_id": "orchestration-uuid",
  "expected_revision": 991228,
  "agent_id": "agent-uuid",
  "dry_run": true
}
```

Tool: `orchestration_members_add` or `orchestration_members_remove`

Edge dry run:

```json
{
  "orchestration_id": "orchestration-uuid",
  "expected_revision": 991228,
  "from_agent_id": "agent-a-uuid",
  "to_agent_id": "agent-b-uuid",
  "description": "Hand off the prepared report.",
  "payload_schema": {},
  "settings": {},
  "dry_run": true
}
```

Tool: `orchestration_edges_upsert`

For removal, send `from_agent_id`, `to_agent_id`, `expected_revision`, and
`dry_run` to `orchestration_edges_remove`.

After reviewing a dry-run response, re-read the orchestration. Apply the
mutation with `dry_run: false` and the latest revision.

Delete only after exact-name confirmation through `orchestrations_delete`.

## Schedule trigger

Upsert one schedule without replacing unrelated graph state:

```json
{
  "orchestration_id": "orchestration-uuid",
  "expected_revision": 991229,
  "node_id": "11111111-1111-4111-8111-111111111111",
  "cron_expression": "0 9 * * 1-5",
  "is_active": false,
  "configured_props": {},
  "edges": [
    {
      "to_agent_id": "agent-uuid",
      "description": "Run the weekday report.",
      "payload_schema": {}
    }
  ]
}
```

Tool: `schedules_upsert`

`node_id` is the schedule's stable graph identity and is used by
`schedules_upsert` and `schedules_remove`. After the upsert, re-read with
`orchestrations_get`, find the schedule with the matching `node_id`, and copy
its separate persisted `id`. Test before activation using that persisted value
as `trigger_id`:

```json
{
  "orchestration_id": "orchestration-uuid",
  "trigger_id": "22222222-2222-4222-8222-222222222222",
  "expected_revision": 991230,
  "payload": {
    "source": "manual-test"
  }
}
```

Tool: `schedules_test`

Do not pass the schedule's `node_id` as `trigger_id`. Schedule testing can
start billable work. Remove a schedule by its `node_id` and current revision
through `schedules_remove`.

## Tasks

Create:

```json
{
  "idempotency_key": "task-support-case-01",
  "agent_id": "agent-uuid",
  "title": "Representative support case",
  "initial_messages": [
    {
      "role": "user",
      "content": "A customer cannot sign in after resetting their password."
    }
  ],
  "auto_run": true
}
```

Tool: `tasks_create`

`auto_run: true` starts billable work. Use `tasks_get` for status and
`tasks_events` for normalized events.

Follow up:

```json
{
  "task_id": "task-uuid",
  "content": "Now propose the safest next step.",
  "run": true
}
```

Tool: `tasks_followup`

`run: true` starts another billable turn. Use `tasks_interrupt` only for an
active task.

## Interactive capability doc map

Before giving click-level Brainbase UI guidance, fetch the relevant page and
verify the current steps. Use the exact deep link in the response rather than
the docs home page. These are starting paths, not a substitute for reading the
page:

- Lifecycle: `https://docs.brainbaselabs.com/docs/agent-lifecycle`
- Testing: `https://docs.brainbaselabs.com/docs/agent-lifecycle/testing`
- Deploying: `https://docs.brainbaselabs.com/docs/agent-lifecycle/deploying`
- Agent anatomy: `https://docs.brainbaselabs.com/docs/anatomy-of-an-agent`
- Instructions: `https://docs.brainbaselabs.com/docs/agent/instructions`
- Playbooks: `https://docs.brainbaselabs.com/docs/agent/playbooks`
- Registry skills: `https://docs.brainbaselabs.com/docs/agent/skills`
- Tools and integrations: `https://docs.brainbaselabs.com/docs/agent/tools`
- Surfaces and connected apps:
  `https://docs.brainbaselabs.com/docs/agent/surfaces`
- Memory: `https://docs.brainbaselabs.com/docs/agent/memory`
- Browser: `https://docs.brainbaselabs.com/docs/agent/browser`
- Shared file system: `https://docs.brainbaselabs.com/docs/agent/file-system`
- Secrets: `https://docs.brainbaselabs.com/docs/agent/secrets`
- Entrypoint: `https://docs.brainbaselabs.com/docs/agent/entrypoint`
- Evals: `https://docs.brainbaselabs.com/docs/monitoring/evaluations`
- Tasks: `https://docs.brainbaselabs.com/docs/monitoring/tasks`
- Orchestrations:
  `https://docs.brainbaselabs.com/docs/orchestrations/building-an-orchestration`
- External and app triggers:
  `https://docs.brainbaselabs.com/docs/orchestrations/external-triggers`
- Models: `https://docs.brainbaselabs.com/docs/models`
- Harnesses: `https://docs.brainbaselabs.com/docs/harnesses`

For guided or deferred capabilities, complete the directly supported portion
first. Then positively explain how to finish the interactive step, grounded in
the fetched docs. Do not turn a capability boundary into a dead end.

## Credential and capability rules

- The packaged MCP descriptor is credential-free and relies on native OAuth.
- The MCP resource endpoint is `https://api.brainbaselabs.com/mcp`.
- The OAuth issuer and authorization server are
  `https://app.brainbaselabs.com`; do not substitute the MCP or control-plane
  host.
- MCP OAuth requires `mcp:all` and remains bounded by normal Brainbase ACLs.
- Resource-scoped PATs and `bb_live_` task credentials are not user-wide MCP
  credentials.
- Responses never include credential values, headers, or environment values.
- Never ask the user to paste a token or secret into chat.
- Guide secret, OAuth, browser-proxy, memory, Slack, meeting, phone, and
  app-trigger setup through the appropriate Brainbase UI.
- Modes, functions, arbitrary file CRUD, and group rename/delete are deferred.
- Brainbase workflows are excluded.

## Conflict and error handling

- `400` or `422`: validate the live schema, IDs, cron, graph membership, eval
  shape, and required confirmation fields.
- `401`: complete or refresh client-native OAuth.
- `403`: check ordinary Brainbase access and ensure the credential is
  user-scoped with `mcp:all`.
- `404`: re-discover the exact resource.
- `409`: re-read, rebuild the targeted change on the fresh revision, and retry
  once only when unambiguous.

Never solve a conflict by dropping `expected_revision`, inventing a credential,
or replacing unrelated collection state.