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:

https://api.brainbaselabs.com/mcp

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

{
  "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:

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:

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:

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:

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.

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:

node scripts/validate.mjs

Validate with Claude Code:

claude plugin validate --strict .

Test locally in Codex:

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

See 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

License

MIT