# Brainbase MCP

The official Brainbase MCP for any compatible MCP client.

Any compatible MCP client can connect to Brainbase over Streamable HTTP and
OAuth. This repository also includes optional Codex and Claude Code packages
that bundle the same MCP connection with a companion operating skill.

## What it provides

- A credential-free remote MCP connection to
  `https://api.brainbaselabs.com/mcp`
- Client-managed Brainbase OAuth with no pasted API keys or bearer tokens
- Agent, component, eval, task, orchestration, schedule, template, and skill
  tools for any compatible MCP client
- An optional maintained operating skill for clients that support packaged
  skills
- Revision-safe targeted writes, idempotent creates, destructive confirmation,
  and explicit billable-run guidance
- Optional Codex, Claude Code, and Brainbase package manifests

Workflows are intentionally excluded.

## Permissions and safety

Brainbase OAuth requests the `mcp:all` scope. This grants the client
user-wide access to Brainbase resources that the signed-in user can already
access under normal Brainbase permissions. It is not limited to one agent.

That means the MCP can:

- inspect and update agents, including an agent it is attached to;
- manage supported agent components, evals, orchestrations, and schedules;
- start tasks and eval runs that may consume paid Brainbase usage; and
- archive or delete supported resources after revision and name confirmation.

The package contains no tokens, secrets, credential headers, or environment
values. OAuth credentials remain in the installing client and Brainbase.

Inspect changes before approving them, especially operations marked billable or
destructive.

## Requirements

- A Brainbase account
- An MCP client with remote Streamable HTTP and OAuth support
- Permission to open `app.brainbaselabs.com` to complete OAuth

## Connect from any MCP client

Configure a remote HTTP MCP server named `brainbase` with this URL:

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

For clients that accept an `mcpServers` object, adapt this credential-free
configuration:

```json
{
  "mcpServers": {
    "brainbase": {
      "type": "http",
      "url": "https://api.brainbaselabs.com/mcp"
    }
  }
}
```

Do not add authorization headers or paste tokens into the configuration.
Complete Brainbase OAuth through the client when prompted.

## Optional: install the Codex package

The Codex package installs the MCP connection and companion operating skill:

```sh
codex plugin marketplace add BrainbaseHQ/brainbase-mcp --ref main
codex plugin add brainbase-mcp@brainbase
```

Complete OAuth when Codex prompts during installation or first use, then start
a new thread.

Try:

> Use $brainbase-mcp to list my Brainbase agents and explain which one is safe
> to modify.

Remove it with:

```sh
codex plugin remove brainbase-mcp@brainbase
codex plugin marketplace remove brainbase
```

## Optional: install the Claude Code package

The Claude Code package installs the same MCP connection and operating skill:

```sh
claude plugin marketplace add --scope user BrainbaseHQ/brainbase-mcp
claude plugin install --scope user brainbase-mcp@brainbase
```

Complete OAuth when Claude Code prompts, restart Claude Code, and invoke a
Brainbase tool.

Remove it with:

```sh
claude plugin uninstall --scope user brainbase-mcp@brainbase
claude plugin marketplace remove --scope user brainbase
```

Removing the plugin removes its local configuration. If an OAuth credential may
have been exposed, report it through the private process in
[SECURITY.md](SECURITY.md).

## First-use workflow

1. List organizations and teams rather than guessing IDs.
2. Inspect an agent and obtain its current opaque revision.
3. Make one targeted change.
4. Read the resource back and verify the result.
5. Test behavior with a task or eval before deploying a schedule.

The companion skill applies this workflow automatically when installed.
Otherwise, follow the same sequence directly with the MCP tools.

## Capability boundaries

Directly supported operations include:

- Agent inspection, creation, updates, archive, and deletion
- Instructions, playbooks, registry skills, and MCP server configuration
- Eval lifecycle and result retrieval
- Orchestration members, edges, schedules, and trigger testing
- Task creation, follow-ups, interruption, and normalized events
- Registry template and skill discovery

Interactive or guided operations include secret entry, third-party OAuth,
browser credentials, memory administration, Slack, meetings, phone, and
external app triggers.

Arbitrary file CRUD, functions, modes, and legacy workflows are not exposed by
this MCP.

## Repository layout

- `.mcp.json` — shared credential-free remote MCP descriptor
- `.codex-plugin/` — Codex plugin metadata
- `.claude-plugin/` — Claude Code plugin and marketplace metadata
- `.agents/plugins/marketplace.json` — Codex marketplace metadata
- `skills/brainbase-mcp/` — maintained skill and reference material
- `components/mcps/brainbase/` — Brainbase package MCP component
- `brainbase.json` — optional Brainbase registry package manifest
- `scripts/validate.mjs` — dependency-free package validation

## Development

Run the repository validation:

```sh
node scripts/validate.mjs
```

Validate with Claude Code:

```sh
claude plugin validate --strict .
```

Test locally in Codex:

```sh
codex plugin marketplace add .
codex plugin add brainbase-mcp@brainbase
```

See [CONTRIBUTING.md](CONTRIBUTING.md) before changing manifests or releasing a
new version.

## Versioning and releases

The package follows semantic versioning. A release updates the version in
`package.json`, both client plugin manifests, and `brainbase.json`.

When the skill or MCP component changes, regenerate the corresponding
`brainbase.json` checksum before release. Pull requests and `main` are validated
by GitHub Actions.

This repository is the canonical source for the Brainbase MCP distribution.
Any compatible MCP client can connect directly to the remote endpoint. The npm
package is intentionally disabled; optional Codex and Claude Code packages
install from this Git repository.

## Support

- Product documentation: <https://docs.brainbaselabs.com>
- Product website: <https://brainbaselabs.com>
- Bugs and feature requests:
  <https://github.com/BrainbaseHQ/brainbase-mcp/issues>
- Security reports: [SECURITY.md](SECURITY.md)

## License

[MIT](LICENSE)