robrain — Claude Code MCP server: what it does, how to install
Stores engineering decisions and rejected alternatives in Postgres. Prevents coding agents from repeating approaches your team already dismissed.
claude mcp add --env PERCEPTION_API_URL=<PERCEPTION_API_URL> --env PERCEPTION_API_KEY=<PERCEPTION_API_KEY> --transport stdio robrain -- npx -y robrainWhat robrain does
The server monitors workspace sessions and extracts architectural decisions directly into Postgres. Records store the selected direction alongside a dedicated rejected[] field for discarded options. When an agent starts work in a new session, it pulls this background context and halts before proposing a dismissed pattern.
The pipeline uses two core parts: Perception extracts structured entries, while Synthesis performs batch checks across the whole database. Running npx robrain synth flags conflicts. You can also trace past reasoning for an individual file with npx robrain explain <path>.
Without an active Perception instance and valid PERCEPTION_API_KEY and PERCEPTION_API_URL values, the server cannot process queries. Self-hosting requires Docker for Postgres and API keys for both Anthropic and OpenAI under the default configuration.
What it helps with
- prevent coding agents from proposing previously rejected design decisions
- share architectural context across different teammates and editors
- detect contradictory technical positions across sessions via
synth - inspect why a specific file was modified using
explain
Example prompts for the agent
- Why did we decide against using Express for this microservice?
- Check our recorded decisions before modifying the database migration.
- List the alternative approaches we ruled out for user authentication.
How to install robrain
Platform CLI
claude mcp add --env PERCEPTION_API_URL=<PERCEPTION_API_URL> --env PERCEPTION_API_KEY=<PERCEPTION_API_KEY> --transport stdio robrain -- npx -y robrainReplace <…> with your own values
Platform CLI
codex mcp add robrain --env PERCEPTION_API_URL=<PERCEPTION_API_URL> --env PERCEPTION_API_KEY=<PERCEPTION_API_KEY> -- npx -y robrainReplace <…> with your own values
Config file
{
"mcpServers": {
"robrain": {
"command": "npx",
"args": [
"-y",
"robrain"
],
"env": {
"PERCEPTION_API_URL": "<PERCEPTION_API_URL>",
"PERCEPTION_API_KEY": "<PERCEPTION_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"robrain": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"robrain"
],
"env": {
"PERCEPTION_API_URL": "<PERCEPTION_API_URL>",
"PERCEPTION_API_KEY": "<PERCEPTION_API_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PERCEPTION_API_URL=<PERCEPTION_API_URL> -e PERCEPTION_API_KEY=<PERCEPTION_API_KEY> robrain npx -y robrainReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about robrain
How do I install robrain in Claude Code?
Run `claude mcp add --env PERCEPTION_API_URL=<PERCEPTION_API_URL> --env PERCEPTION_API_KEY=<PERCEPTION_API_KEY> --transport stdio robrain -- npx -y robrain` in your terminal. Replace the placeholders with your Perception URL and API key.
What does robrain do?
It records engineering choices and rejected alternatives in a Postgres database. It informs your AI assistant when a suggested change contradicts an earlier team verdict.
What is needed to run the self-hosted version?
Start the database and Perception services by executing npx robrain@latest up. You will also need API keys for extraction and embeddings (Anthropic and OpenAI by default).
