Cerebro MCP
Integrates with CrewAI agents via A2A protocol for multi-agent task delegation.
Provides tools for interacting with GitHub repositories, enabling version control and code management.
Integrates with LangChain agents via A2A protocol for orchestration and tool use.
Integrates with OpenAI Codex CLI for code generation and review tasks.
Connects to Salesforce via A2A protocol for CRM operations like campaign and catalog updates.
Connects to SAP via A2A protocol for enterprise resource planning integration.
Provides tools for interacting with Slack, enabling messaging and notifications.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cerebro MCP Build a landing page for my coffee shop"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Cerebro MCP
The brain that builds.
v2.1.0 — All 28 tools fully implemented. Zero stubs. Production-ready.
Universal AI orchestrator — MCP for tools, A2A for agents. Chat thinks, agents specialize, CLI codes. One conversation, working software. No terminal required.
First orchestrator to unify MCP + A2A. Both Linux Foundation standards. Tools speak MCP. Agents speak A2A. Cerebro orchestrates both.
Live Demo · Architecture · API Reference · Agent Guide
The Problem
You have a great idea. You can describe it perfectly. But you can't build it because you don't know how to code.
Claude Chat can plan and brainstorm but can't write files. Claude Code CLI can build software but requires a terminal. Existing orchestrators target developers. There's nothing for the 99% of people who think in ideas, not code.
Related MCP server: MCP Vibe Coding Tools
The Solution
Cerebro MCP makes Claude Chat the brain that controls everything. You describe what you want in plain English. Cerebro decomposes your idea, routes tasks to specialist agents, spawns CLI workers, and reports back in language you understand.
You: "Build me a landing page for my coffee shop with online ordering"
Cerebro: Breaking this into tasks...
→ Designer agent: Creating layout with hero, menu grid, order CTA
→ Coder agent: Building responsive HTML/CSS with cart functionality
→ QA agent: All 12 tests passing. Lighthouse score: 96.
Your landing page is ready at localhost:3000.You never see a terminal. You never write code. You just talk.
Quick Start
npx @synvoya/cerebro-mcpThen add to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"cerebro": {
"command": "npx",
"args": ["@synvoya/cerebro-mcp"]
}
}
}Restart Claude Desktop. Cerebro's 30 tools are now available in Chat.
Just Talk — Zero Setup Mode
Don't want to learn tools? Just use quick_task:
You: "Build me a portfolio website in ~/Projects/my-portfolio"
Cerebro: Auto-creating session... picking Claude Code + Sonnet...
→ Terminal opens, Claude Code starts building
→ Task completed! Files saved to ~/Projects/my-portfolioNo sessions to create. No agents to configure. Just describe what you want and where to save it.
What's New
v2.3.0 — Shell Safety + Execution Modes (April 2026)
Interactive Mode (new default) — See Claude Code's live thinking, tool calls, and file operations in the terminal. No more blind waits.
Quiet Mode — Say "quiet mode" to show only task + result. Previous default behavior.
Shell Escaping Fix — Task descriptions with backticks, quotes, and special characters no longer break terminals.
executionMode preference via configure_model — "show thinking", "hide execution", "interactive", "quiet".
v2.2.0 — Context Watcher (April 2026)
Context Watcher — start_context_watcher opens a persistent terminal showing real-time token usage, progress bar, and handover recommendations. Off by default.
Terminal Preferences — Global auto-close, no-terminal, and watcher toggles via configure_model.
30 MCP Tools — Two new tools: start_context_watcher, stop_context_watcher.
v2.1.0 — All Tools Working (April 2026)
Every single one of Cerebro's 28 tools now works for real. No stubs, no placeholders, no "coming soon."
Code Review —
review_codenow runs a real code review via CLI. Get quality, security, and best practice feedback on your project.Build & Test —
run_buildandrun_testsdetect your build system and run it. Works with npm, Python, Go, Rust, and more.Agent Marketplace —
install_agent_packloads pre-built agent teams from starter kits. Tryweb-app,api-service, orcontent-site.Vision Pipeline — Upload a screenshot to Chat. Chat sees it, describes it, and Cerebro fixes or builds from it. No API key needed — Chat IS the vision layer.
Context Health —
get_context_healthtracks real token usage per session. Warns you at 60%, suggests handover at 80%.
Note:
get_context_healthtracks Cerebro session context (task count and estimated token usage within a Cerebro session), not the Chat conversation window. For Chat context, Claude will naturally suggest starting a new conversation when the window gets full. Real-time Chat context tracking is planned for v3.0.
Token Persistence — Handover tokens now survive server restarts. Your session tokens stay valid across reboots.
Security — AppleScript injection prevention in terminal titles. Token secrets stored with owner-only file permissions.
v2.0.0 — Major Feature Release (April 2026)
Quick Task — Just say what you want. No sessions, no agents, no config. Cerebro figures it out.
Project Reader — Cerebro reads your folder structure and code before making changes. No blind edits.
Multi-Provider CLI — Use Claude Code, OpenAI Codex, or Aider. Switch providers with one sentence.
Visible Terminal Windows — Watch your AI work in real Terminal windows. See every command as it runs.
Auto-Close Terminal — Terminal stays open by default so you can review. Pass
autoCloseTerminal: trueto close automatically.Smart Model Routing — Cerebro uses Sonnet by default. Say "use Opus" to switch. Codex automatically uses its own models (gpt-5.4).
Provider & Model in Results — Chat always tells you which agent, provider, and model completed your task.
Auto Git Init for Codex — Codex requires a git repo. Cerebro auto-initializes one if needed.
What Makes Cerebro Different
Remote Control | Other Orchestrators | Cerebro MCP | |
For | Developers | Developers | Non-coders |
Direction | User → CLI | Dev → agents | Chat → everything |
Protocols | MCP only | Custom | MCP + A2A |
Agent creation | N/A | Config files | Just talk |
Context rot | Not addressed | Manual clear | Fresh per task |
External agents | N/A | N/A | Any A2A agent joins |
Session continuity | Single session | N/A | Signed tokens |
CLI providers | Claude Code only | Single provider | Multi-provider |
Zero setup | N/A | Config required | Just talk |
Architecture
User (non-coder)
│ Natural language, images
▼
Claude Chat (brain)
│ Plans, decomposes, delegates
▼
Cerebro MCP Server (orchestrator)
│ MCP for tools │ A2A for agents
├─────────┼─────────┤
▼ ▼ ▼
CLI Agent External
Workers Swarm MCPs
│ │ │
▼ ▼ ▼
Agent Marketplace + A2A Interop
│
▼
Working ProductDual Protocol
Cerebro is the first orchestrator to implement both standards:
MCP (Model Context Protocol) — how Cerebro talks to tools. CLI, databases, GitHub, Slack.
A2A (Agent-to-Agent Protocol, v0.3) — how agents talk to each other. Internal delegation and external interop.
Both protocols live under the Linux Foundation.
Features
Agent Swarm — Build Your AI Team by Talking
Create specialist agents with natural language. No config files, no YAML.
You: "Add a marketing agent that writes social media posts in a casual tone"
Cerebro: Marketing agent created and added to your swarm.
You: "Write a launch tweet for the coffee shop"
Cerebro → Marketing agent: "your morning just got an upgrade. order your
favorite latte from the couch and pick it up hot."Agents persist across sessions. They learn your preferences. They delegate to each other via A2A.
Fresh Context — Zero Memory Rot
Every agent call gets a fresh context window. Agent definitions and learned preferences persist, but working context is wiped after each task. No stale reasoning accumulates. Ever.
Multi-Provider CLI — Choose Your Tools
Cerebro isn't locked to a single CLI. Route different task types to different providers using natural language.
You: "Use Claude Code for coding tasks and Codex for code review"
Cerebro: Worker routing updated.
→ Coding tasks → Claude Code CLI
→ Code review → OpenAI Codex CLI
You: "What CLI tools do I have installed?"
Cerebro: Detected providers:
✓ Claude Code CLI (authenticated)
✓ Codex CLI v0.118.0 (authenticated)
✗ Aider (not installed)Supported providers: Claude Code, OpenAI Codex, Aider, and any generic shell command. Cerebro auto-detects installed tools and intelligently routes tasks based on agent name, description, and routing rules.
A2A Interop — Your Swarm Has No Walls
Every Cerebro agent is automatically A2A-compliant. They publish Agent Cards at /.well-known/agent-card.json. External A2A agents from Salesforce, SAP, LangChain, CrewAI — anything A2A-compliant — can join your swarm.
You: "Connect the Salesforce agent and update our CRM"
Cerebro: Discovering agent via Agent Card... connected.
→ Salesforce agent: Campaign created, catalog updated.Agent Marketplace — Three Tiers
Anthropic Skills — Curated templates from Anthropic's open-source repo (Apache 2.0)
Community agents — Shared by users, reviewed, tagged
Your agents — Created by you, private by default, optionally shareable
Session Tokens — Survive Chat Handovers
When your chat hits context limits, Cerebro generates a signed handover token. Paste it in a new chat and continue exactly where you left off. Sessions, agents, task history — everything transfers.
Terminal and Watcher Configuration
Control terminal behavior with natural language via configure_model:
User says | Preference | Effect |
"auto close terminals" | autoCloseTerminal: true | Worker terminals close after task completes |
"keep terminals open" | autoCloseTerminal: false | Terminals stay open for review (default) |
"no terminal" / "background mode" | spawnMode: background | CLI tasks run silently, no Terminal windows |
"show terminal" / "visible mode" | spawnMode: visible | Tasks open visible Terminal windows (default) |
"interactive" / "show thinking" | executionMode: interactive | See Claude Code thinking and tool calls live in terminal (default) |
"quiet" / "hide execution" | executionMode: quiet | Terminal shows only task description and final result |
"no watcher" / "disable watcher" | watcherAutoStart: false | Context Watcher will not auto-start (default) |
"enable watcher" | watcherAutoStart: true | Context Watcher auto-starts |
Combine freely. Example scenarios:
Scenario | Config | Behavior |
Full visibility (default) | none needed | Each task opens a Terminal. Watcher available. Terminals stay open |
Fire and forget | auto close terminals | Terminals open then close when done |
Silent mode | no terminal | Everything runs in background. Results in Chat |
Headless / VPS | background mode, disable watcher | No GUI needed. All results via MCP |
Visible + watcher | auto close terminals, enable watcher | Task terminals flash open/close. Watcher stays open |
Quiet terminals | quiet mode | Terminals open but only show task + result |
All preferences persist for the session. Change anytime via configure_model.
Starter Kits
Drop a .cerebro/agents.json in any project and agents auto-spawn on session start.
Built-in kits: web-app (Coder + Designer + QA), api-service (Coder + QA + DevOps), content-site (Designer + Coder + Marketing).
Live Dashboard
Real-time agent status with heartbeats, task broadcasting, and conversation threading. See your AI team working like a project management board.
Vision Pipeline — Screenshot to Fix
Upload a screenshot, mockup, or error message to Chat. Chat (Claude) sees and interprets the image, then orchestrates Cerebro to act on it. No API key needed — Chat IS the vision layer.
You: [uploads screenshot of broken nav bar]
Chat: "I can see the nav overlaps the hero section on mobile. The z-index needs fixing."
→ Cerebro calls implement_from_image
→ Coder agent patches the CSS
→ "Fixed! Nav now layers correctly on all screen sizes."This works because Claude Chat has built-in vision. When you paste an image, Chat describes what it sees and translates that into instructions for Cerebro's CLI workers.
Visible Terminals — Watch Your AI Work
Every task opens a real Terminal window so you can see exactly what's happening. The terminal shows the agent name, provider, model, and live CLI output as it runs. After completion, the terminal stays open for you to review.
Want the terminal to close automatically? Pass autoCloseTerminal: true when delegating tasks.
Note: Claude Code runs in
Project Reader — AI Understands Your Code
Before making changes, Cerebro can read your entire project structure and file contents. The AI understands your codebase before touching it — no blind edits.
You: "Read my project and explain the architecture"
Cerebro: Scanning ~/Projects/my-app...
→ 42 files across 8 directories
→ TypeScript project with React frontend and Express backend...30 MCP Tools
Session Management
Tool | What it does |
| Start a new project workspace. Tell it where to save files. |
| Continue where you left off using a handover token. |
| Park your session for later — everything is saved. |
| Finish and archive a session with all task history. |
| See all your active, paused, and recent sessions. |
Task Execution
Tool | What it does |
| The easiest way to use Cerebro. Just say what you want — auto-creates session, picks provider, and builds. No setup needed. |
| Run a task within an existing session. Auto-routes to the best agent. |
| Read your project's folder structure and file contents so the AI understands your codebase. |
| Check what's happening — see progress on all tasks. |
| Get a human-friendly explanation of code changes. |
| Trigger a build and see the results. |
| Run your test suite and get a summary. |
Agent Swarm
Tool | What it does |
| Create a specialist agent by describing what it should do. "Add a QA agent that reviews code for security issues." |
| See all agents in your swarm with their status. |
| Change an agent's persona, skills, or preferences. |
| Remove an agent from your swarm. |
| Check what a specific agent is working on. |
| Install a pre-built team: |
| Send a task directly to a specific agent. Returns provider, model, and results. |
Vision (Image Pipeline)
Tool | What it does |
| Paste a screenshot or mockup — Cerebro interprets it and suggests actions. |
| Turn a screenshot or design into working code. |
| Visual diff between expected and actual — find what changed. |
Session Continuity
Tool | What it does |
| Generate a signed token to continue in a new chat window. |
| Check if a handover token is still valid. |
| See how much context window remains before you need a handover. |
Context Watcher
Tool | What it does |
| Start real-time token tracking with a live terminal dashboard. |
| Stop the context watcher and close the dashboard. |
What the Context Watcher Tracks
The Context Watcher estimates token usage — it does not read Claude's actual context window.
What | Tracked? | How |
Cerebro MCP tool calls (main Chat) | Yes | Counts each tool call, applies per-tool token estimates |
Conversation overhead (system prompt, tool defs) | Yes | Fixed 15k token base estimate |
Per-turn conversation cost | Yes | ~1500 tokens per tool call turn |
What happens inside spawned CLI terminals | No | Each terminal is an independent Claude Code session |
Claude's real context window size | No | No API available — all values are estimates |
Other MCP server calls | No | Only Cerebro tools are tracked |
The watcher answers: "How full is my main Chat based on Cerebro tool call volume?" — which is what matters for knowing when to handover. It is off by default. Start it with start_context_watcher when you want visibility.
Worker Configuration
Tool | What it does |
| Route tasks to different CLI providers. "Use Codex for QA tasks." |
| See which CLI tools are installed on your system. |
| Set the AI model and effort level. "Use Opus with high effort." |
CLI Provider Setup
Claude Code (recommended)
npm install -g @anthropic-ai/claude-code
claude-code authOpenAI Codex
npm install -g @openai/codex
codex authThen in Chat:
You: "Use Codex for code review tasks"
Cerebro: Routing updated — code review tasks → Codex CLI.Aider
pip install aider-chatCerebro auto-detects all installed providers via detect_providers.
Note: Cerebro automatically handles model compatibility between providers. If you configure Sonnet as your model, Cerebro will use it for Claude Code but skip it for Codex (which uses its own OpenAI models like gpt-5.4). No manual configuration needed.
Project Structure
cerebro-mcp/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # 28 MCP tools registered
│ ├── session/ # Session lifecycle + SQLite store
│ ├── router/ # Task routing + decomposition
│ ├── workers/ # CLI providers, terminal spawner,
│ │ # model config, pool, Cowork (V2), MCP relay
│ ├── agents/ # Swarm, runner, confidence, delegation,
│ │ # memory, marketplace, heartbeat, threading
│ ├── a2a/ # A2A server, client, Agent Cards, lifecycle
│ ├── vision/ # Image relay + interpreter
│ ├── context-watcher/ # Token tracking + terminal dashboard
│ ├── handover/ # Engine, context monitor, directory
│ ├── notifications/ # Webhooks + push alerts
│ ├── dashboard/ # Agent status dashboard
│ ├── security/ # HMAC-SHA256 crypto
│ ├── reporter/ # CLI output → human-friendly summaries
│ └── types/ # TypeScript type definitions
├── agents/ # Built-in agent templates
├── starter-kits/ # Shareable .cerebro/ configs
└── tests/ # Vitest test suiteDevelopment
git clone https://github.com/Synvoya/cerebro-mcp.git
cd cerebro-mcp
npm install
npm run build
npm testCurrent stats: v2.1.0 · 69 files · ~6,500 lines of TypeScript · 28 MCP tools (all fully implemented) · 40/40 tests passing
Roadmap
MCP server with 28 tools — all fully implemented (v2.1.0)
Session management with signed tokens
Agent swarm with conversation-based CRUD
A2A protocol for agent-to-agent communication
Agent marketplace (3-tier)
Heartbeat presence + task broadcasting
Message threading between agents
Auto-registration via
.cerebro/agents.jsonStarter kits (web-app, api-service, content-site)
Claude Code CLI integration (subprocess management)
Multi-provider CLI (Claude Code, Codex, Aider, generic shell)
Quick task — zero-setup execution via natural language
Project reader — AI reads your codebase before making changes
Visible terminal spawner (branded agent windows)
Model and effort configuration via natural language
Cowork integration (pending Anthropic API)
Agent dashboard web UI
Remote CLI workers (VPS/cloud)
Context Watcher — real-time Chat context window tracking with live terminal dashboard (v3.0)
Community agent repository
Contributing
See CONTRIBUTING.md for guidelines. No CLA required — contributions are licensed under Apache 2.0.
License
Apache 2.0 — see LICENSE. Copyright (c) 2026 Synvoya.
Links
Website: cerebro.synvoya.com
npm: @synvoya/cerebro-mcp
GitHub: Synvoya/cerebro-mcp
Company: Synvoya
Built with passion by Hibi and the Synvoya team. The brain that builds.
Available Tools
30 toolsanalyze_imageA
Interpret an image and suggest actions. How it works: the user uploads an image to Chat, Chat (Claude) sees and describes it, then calls this tool with the description. No API key needed — Chat IS the vision layer.
Inputs: sessionId (required), description (required), context.
compare_screenshotsB
Visual diff between expected and actual. Chat compares two images and describes the differences, then this tool structures the findings and can trigger fixes.
Inputs: actual (required), expected (required), sessionId (required), differences (required).
configure_modelA
Set model, effort level, and terminal mode. Say 'Use Opus for coding' or 'Set high effort' or 'Run in background mode'
Inputs: instruction (required).
configure_workersA
Configure which CLI tools handle which tasks. Say 'Use Claude for coding and Codex for testing' or 'Set Aider as default'
Inputs: instruction (required).
create_agentB
Define a new specialist agent via natural language description
Inputs: name (required), sessionId (required), description (required), tools, +1 more.
create_sessionA
Create a new Cerebro session and project workspace
Inputs: projectPath (required), description.
delegate_to_agentA
Explicitly route a task to a specific agent, overriding auto-routing
Inputs: task (required), agentId (required), sessionId (required), autoCloseTerminal.
detect_providersA
Detect which CLI coding tools are installed and available on this system
Inputs: no named parameters.
end_sessionB
Complete and archive a session
Inputs: sessionId (required).
execute_taskC
Send a task to the appropriate worker or agent for execution
Inputs: sessionId (required), description (required), targetAgent.
get_agent_statusB
Get detailed status and history for a specific agent
Inputs: agentId (required).
get_context_healthA
Report current context window usage and handover readiness
Inputs: sessionId (required).
get_statusC
Get current project progress and task status
Inputs: sessionId (required).
implement_from_imageA
Build or fix code based on an image. Chat sees the image, describes it, and this tool sends the description to a CLI worker to implement. Works for: screenshots of bugs to fix, mockups to build, error messages to resolve.
Inputs: sessionId (required), description (required), targetPath.
install_agent_packA
Install pre-built agent templates from the marketplace
Inputs: packName (required), sessionId (required).
list_agentsA
Show all agents in the current session with their status
Inputs: sessionId (required).
list_sessionsA
List all active, paused, and recent sessions
Inputs: no named parameters.
pause_sessionB
Pause an active session for later resumption
Inputs: sessionId (required).
prepare_handoverA
Generate a signed handover token for session continuity across chats
Inputs: sessionId (required).
quick_taskA
The easiest way to use Cerebro — just describe what you want built or fixed. Auto-creates a session, picks the right CLI provider, and executes. Use this when the user says things like 'build me a website' or 'fix this bug' or 'review this code' without specifying sessions or agents. If no projectPath is given, ask the user where to save files.
Inputs: task (required), model, provider, projectPath, +1 more.
read_projectA
Read the project folder structure and file contents. Use this to understand a codebase before making changes. Returns directory tree and optionally file contents for specified files or all files.
Inputs: sessionId (required), path, maxDepth, filePattern, +1 more.
remove_agentB
Delete an agent from the swarm
Inputs: agentId (required).
resume_sessionB
Resume an existing session using a handover token
Inputs: token (required).
review_codeC
Get a human-friendly explanation of code changes
Inputs: sessionId (required), filePath.
run_buildC
Trigger a project build and return results
Inputs: sessionId (required).
run_testsC
Run the test suite and return results
Inputs: sessionId (required).
start_context_watcherA
Open a persistent terminal showing real-time token usage. Tracks every Cerebro tool call with estimated tokens and handover recommendation.
Inputs: sessionId (required), noTerminal, autoCloseTerminal.
stop_context_watcherA
Stop the Context Watcher and close terminal. Tracking data preserved.
Inputs: no named parameters.
update_agentB
Modify an existing agent's definition, skills, or preferences
Inputs: agentId (required), sessionId (required), name, tools, +2 more.
validate_tokenC
Check if a handover token is valid
Inputs: token (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Several tools overlap in purpose, such as quick_task vs execute_task vs delegate_to_agent, and the multiple status/health tools (get_status, get_agent_status, get_context_health) could cause misselection. Descriptions help distinguish them, but the boundaries are not always clear.
All 30 tools follow a consistent verb_noun snake_case pattern (e.g., create_session, list_agents, run_build). The pattern is uniform and predictable, making it easy to infer functionality from names.
At 30 tools, this server feels overloaded for its domain. Several tools could be consolidated (e.g., quick_task overlaps with execute_task), and the count exceeds the 25-tool threshold that indicates too many tools.
The tool set covers session lifecycle, agent CRUD, task execution, project operations, image handling, and configuration well. Minor gaps exist (e.g., no explicit session update), but core workflows are supported without dead ends.
Maintenance
Related MCP Connectors
Build and run agents and automations across hundreds of apps using natural language.
Coding agents build full-stack apps in persistent workspaces and share them by link.
Build and host full-stack apps from a prompt, with agents that reach you on WhatsApp and email.
Build agents to automate any background task. Works with your ChatGPT/Claude subscription.
Related MCP Servers
- AlicenseAqualityBmaintenanceOrchestrates multiple AI coding agents declaratively to automate software development workflows for engineering teams.14973 PyPI1,213Apache 2.0
- AlicenseBqualityDmaintenanceTransforms any prompt into a fully functional, production-ready product with zero human intervention by providing 150+ autonomous tools covering all aspects of software development.331MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to scaffold, edit, live-preview, and deploy full-stack apps with built-in database, email, and push notification capabilities through natural language.19MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to research topics, analyze codebases, generate requirements and user stories, scaffold starter projects, and run multi-step development workflows through natural language.42 npmMIT