Get Started

Connect Brainbase MCP

Connect any compatible OAuth-capable MCP client to Brainbase's universal remote Streamable HTTP server at https://api.brainbaselabs.com/mcp. Codex and Claude Code also have optional enhanced packages that add an operating skill for revision-safe changes, testing, and confirmation of destructive or billable actions.

Connect Brainbase MCP

Start with your client's standard remote MCP connection flow. Use a client-specific setup below, adapt the generic configuration for another compatible client, or optionally add the Codex or Claude Code package after connecting.

Brainbase MCP

Streamable HTTP

Universal remote MCP

Connect from any compatible OAuth-capable MCP client.

Brainbase OAuth

Authorize without storing API keys in client configuration.

46 explicit tools

Managed-agent operations with revision and confirmation safety.

Stable remote endpoint

https://api.brainbaselabs.com/mcp

Connect Brainbase MCP

Use a client-specific setup to connect the universal remote Streamable HTTP MCP and complete Brainbase OAuth.

Codex

Remote MCP + OAuth

Command

Connect Codex directly to the public Brainbase MCP.

Run the command and complete the Brainbase OAuth flow Codex opens automatically. Use `codex mcp login brainbase --scopes mcp:all` only to reauthenticate if needed.

codex mcp add brainbase --url https://api.brainbaselabs.com/mcp

Claude Code

Remote MCP + OAuth

Command

Connect Claude Code directly to the public Brainbase MCP.

Run the command, then use Claude Code's MCP connection flow to finish Brainbase OAuth.

claude mcp add --transport http --scope user brainbase https://api.brainbaselabs.com/mcp

Cursor

Remote MCP + OAuth

One-click MCP

Open Cursor with the Brainbase remote server prefilled.

Approve the server, then finish Brainbase OAuth in Cursor.

Install in Cursor

VS Code

Remote MCP + OAuth

One-click MCP

Open VS Code with the remote HTTP configuration prefilled.

Confirm the connection, then authorize Brainbase in VS Code.

Install in VS Code

ChatGPT

Custom MCP app

Guided

Add Brainbase as a custom MCP app through ChatGPT developer mode.

On ChatGPT web, enable developer mode if your plan and workspace allow it, add a custom app with the server URL, then complete Brainbase OAuth.

https://api.brainbaselabs.com/mcp

Open ChatGPT

Claude

Custom connector

Guided

Add Brainbase as a custom remote MCP connector in Claude.

Copy the server URL, open Claude settings, create a custom connector, and complete Brainbase OAuth.

https://api.brainbaselabs.com/mcp

Open Claude

Connect another MCP client

Use the stable endpoint with any compatible OAuth-capable client that supports remote Streamable HTTP MCP.

Streamable HTTP endpoint

Remote MCP + OAuth

Guided

The universal endpoint for any compatible MCP client.

Create a remote Streamable HTTP MCP named Brainbase and let the client start OAuth. Do not add authorization headers or tokens.

https://api.brainbaselabs.com/mcp

JSON configuration

Compatibility setup

Guided

A generic configuration shape to adapt for your client.

Use this only when your client accepts an mcpServers JSON object and supports OAuth for remote HTTP servers.

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

Optional plugin + operating skill

Codex and Claude Code can optionally install an enhanced package that adds the Brainbase operating skill to the same MCP connection.

Codex

MCP + operating skill

Optional package

Install the optional Codex package from the Brainbase marketplace.

Run both commands, complete Brainbase OAuth, then start a new Codex session.

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

Claude Code

MCP + operating skill

Optional package

Install the optional Claude Code package from the Brainbase marketplace.

Run both commands, complete Brainbase OAuth, then restart Claude Code.

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

OAuth happens in the destination client. Follow the authorization flow it opens, sign in to Brainbase, and approve Brainbase-wide access. The protected resource is https://api.brainbaselabs.com; authorization is issued by https://app.brainbaselabs.com.

Never paste tokens

Do not paste API keys, bearer tokens, or session tokens into an MCP client, command, chat, or support message. Authenticate only through the OAuth flow started by your destination client.

How Brainbase MCP behaves

The launch contract exposes 46 explicit tools rather than automatically turning API routes into tools. It covers agents, templates, registry skills, MCP servers, playbooks, evals, orchestrations, schedules, tasks, and normalized task events. Workflows are excluded.

Area	Behavior
Agents	List, inspect, create, update, and delete. MCP-created agents default to `kafka_cloud` unless a runtime or template supplies another value.
Components	Update instructions and playbooks, search and attach skills, and manage MCP servers without returning credential values.
Evals and schedules	Create, update, run or test, inspect results, and delete. Enabled evals are required before a run.
Orchestrations	Manage orchestrations, members, edges, and schedule triggers with targeted operations.
Tasks	Create runs, send follow-ups, inspect or interrupt tasks, and read normalized events.
Registry templates	Search and inspect packages, then create a new agent from supported runtime, model, instruction, skill, and MCP components.

Re-read before changing

Editable resources include an opaque revision. Updates and lifecycle deletes require expected_revision; a stale value returns a conflict. Re-read the resource, preserve unrelated state, and reapply the intended change. Creates require idempotency keys, and top-level deletes require exact-name confirmation.

Some operations start billable work

Starting a task, running an eval, testing a schedule, or sending a follow-up with execution enabled can consume Brainbase credits. Review the target agent, prompt, and expected work before confirming.

Client compatibility

Brainbase MCP works with any client that supports remote Streamable HTTP MCP and OAuth. Setup surfaces differ, but every connection uses the same endpoint, tools, authorization scope, and safety contract.

Destination	Connection	Optional enhancement
Any compatible MCP client	Stable Streamable HTTP URL or adapted generic configuration	Not required.
Codex	Direct MCP commands	Optional package with the Brainbase operating skill.
Claude Code	Direct MCP command	Optional package with the Brainbase operating skill.
Cursor	One-click remote MCP connection	Not required.
VS Code and GitHub Copilot	One-click remote MCP connection	Not required.
ChatGPT	Guided custom MCP app where available	Not required.
Claude	Guided custom remote MCP connector	Not required.

Client setup surfaces differ, but the MCP connection is the same. See the official OpenAI app guide, Claude custom connector guide, Cursor MCP install guide, and VS Code MCP guide for each host's connection surface.

Optional enhanced packages

Codex and Claude Code users can optionally install the public packages at BrainbaseHQ/brainbase-mcp. Each package connects the same Brainbase MCP and adds an operating skill that guides the client through the complete safe-build workflow.

Operating skill: inspect-before-edit behavior, targeted writes, revisions, eval and trigger testing, credential boundaries, and confirmed deletion.
Client manifest: thin platform-specific metadata that installs the MCP connection and operating skill.
Reference material: maintained capability guidance without credentials, generated files, or the original testing PDF.

The agent template is different

Selecting Brainbase MCP in Brainbase's agent-template picker creates a managed agent from brainbase/brainbase-mcp. It does not install a Codex or Claude Code package. Authorize the new agent's Brainbase MCP from its Tools page if prompted.

Granted access

OAuth grants the mcp:all scope. This scope is user-wide rather than limited to one agent, so the consent screen does not show an agent or organization picker. It does not bypass authorization: every action remains bounded by the signed-in user's normal Brainbase organization, role, and resource ACLs.

Build and update agents you are allowed to access.
Test agents with representative tasks and inspect their results.
Run agents from the connected client.
Workflows are excluded from Brainbase MCP.

After connecting

Start by asking the client to list the Brainbase agents available to you. You can then ask it to create or refine an agent, test that agent with a real example, or run it on a task. If you installed an optional enhanced package, invoke the Brainbase skill explicitly when you want the client to follow its complete safe-build workflow.

Workflows are excluded

Brainbase MCP does not expose workflows. Use agents, orchestrations, schedules, evals, and tasks through the documented MCP capabilities.

Troubleshooting

Authorization did not open: Remove the stale Brainbase connection, add https://api.brainbaselabs.com/mcp again, and complete OAuth in the same destination client.
Expected agents are missing: Confirm that you signed in with the right Brainbase account and that the account has access to those agents.
The optional skill does not appear: Confirm that you installed the Codex or Claude Code enhanced package, then start a new chat or restart the destination client.
Tools do not appear: Refresh or restart the destination client after connecting or installing.
The client cannot connect: Confirm that it supports remote Streamable HTTP MCP and OAuth. Otherwise, use another compatible client or the Brainbase CLI or API. Never substitute pasted tokens.