@agentbrain/mcp-server
Advanced tools
Model Context Protocol server for AgentBrain - connect Claude, Cursor, and Windsurf to repository intelligence
Model Context Protocol (MCP) server for AgentBrain - connect your AI agent directly to repository intelligence.
This MCP server lets Claude Code, Claude Desktop, Cursor, and Windsurf access AgentBrain functionality directly from within your coding sessions. Your AI agent can automatically:
No CLI commands needed - your agent does it all automatically!
npm install -g @agentbrain/mcp-server
macOS/Linux:
# Open in your text editor
code ~/.config/claude-code/mcp.json
# Or use nano
nano ~/.config/claude-code/mcp.json
Windows:
# The config is at:
%USERPROFILE%\.config\claude-code\mcp.json
Add this configuration:
{
"mcpServers": {
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"]
}
}
}
If you have other MCP servers already:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
},
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"]
}
}
}
Exit Claude Code completely and reopen it.
/mcp or check MCP tools listAsk Claude:
"Use the scan_repo tool to analyze my project at /Users/yourname/my-project"
Claude will automatically use the AgentBrain tools!
macOS:
# Open in your text editor
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Or use nano
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows:
# The config is at:
%APPDATA%\Claude\claude_desktop_config.json
Add this configuration:
{
"mcpServers": {
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"]
}
}
}
If you have other MCP servers already:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
},
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"]
}
}
}
Completely quit Claude Desktop (don't just close the window):
Cmd + Q or Claude → Quit ClaudeThen reopen it.
scan_repoload_standardsload_contextsetup_repo ⭐ NEWsave_context ⭐ NEWload_specdetect_doom_loopcreate_specsave_handoffAsk Claude:
"Use the scan_repo tool to analyze my project at /Users/yourname/my-project"
Claude will automatically use the AgentBrain tools!
Cmd + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux)Or manually edit the config file:
macOS:
code ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Linux:
code ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows:
code %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
{
"mcpServers": {
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"]
}
}
}
Completely quit and reopen Cursor.
Cmd + L or Ctrl + L)@ and you should see MCP tools availableIn Cursor chat:
"Scan the current repository using AgentBrain"
Cursor will automatically use the MCP tools!
Method 1: Via UI
Method 2: Edit Config File
macOS:
code ~/Library/Application\ Support/Windsurf/User/globalStorage/windsurf-mcp/settings.json
Linux:
code ~/.config/Windsurf/User/globalStorage/windsurf-mcp/settings.json
Windows:
code %APPDATA%\Windsurf\User\globalStorage\windsurf-mcp\settings.json
{
"mcpServers": {
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"]
}
}
}
Quit completely and reopen.
Look for MCP tools in the Windsurf interface, then ask:
"Use AgentBrain to scan this project"
Once configured, your agent can use these 9 tools:
scan_repo - Analyze Repository StructureWhat it does: Scans your repository and lists all relevant files with language and size info.
Example prompts for your agent:
Cost: Free - no API calls
load_context - Load Full ContextWhat it does: Loads comprehensive documentation about your entire codebase (context.md + dependency-map.md + patterns.md).
Example prompts:
Returns:
{
"content": "# Repository Intelligence\n\n...",
"fromCache": true,
"tokensUsed": 0,
"doom_warning": null // or doom loop details if detected
}
Doom Loop Detection: If you've been modifying the same files repeatedly, doom_warning will contain:
{
"detected": true,
"files": [
"src/auth.ts (8 times · 80%)",
"src/main.ts (6 times · 60%)"
],
"message": "Doom loop detected. Stop coding. Investigate root cause first."
}
Cost:
Note: If the context doesn't exist, it will generate it using your API key.
load_spec - Load Task SpecificationWhat it does: Loads a task specification file by name, or lists all available specs if no task is specified.
Parameters:
repoPath (required): Path to repositorytask (optional): Task description or slug (e.g., "add-oauth-authentication")Example prompts:
Returns: If task specified: The spec content If no task: List of all available specs in .agentbrain/specs/
Cost: Free - reads from disk
Note: Specs must be created first using agentbrain spec CLI command.
Returns:
{
"content": "# Task Specification: Add OAuth\n\n...",
"slug": "add-oauth-authentication",
"doom_warning": null // or doom loop details if detected
}
Example usage:
// List all specs
load_spec({ repoPath: "/path/to/project" })
// Returns: "Available specs:\n\n- add-oauth-authentication\n- implement-notifications"
// Load specific spec
load_spec({ repoPath: "/path/to/project", task: "add-oauth-authentication" })
// Returns: Full spec content with problem, approach, acceptance criteria, etc.
Doom Loop Detection: Like load_context, this tool returns doom warnings if detected.
load_standards - Load Coding StandardsWhat it does: Loads the coding standards file for your specific agent (CLAUDE.md, .cursor/rules, or .windsurfrules).
Example prompts:
Cost: Free - reads from disk
Note: Standards file must exist (create with agentbrain standards CLI command first).
save_handoff - Save Session HandoffWhat it does: Analyzes your recent git changes and creates a handoff document for the next session.
Parameters:
repo_path (required): Path to repositorygoal (optional): Session goal or objectivecommit_count (optional): Number of recent commits to include (default: 5)Example prompts:
Returns:
{
"path": ".agentbrain/handoff.md",
"created": true,
"doom_warning": null // or doom loop details if detected
}
Doom Loop Detection: If a doom loop is detected, a warning section is automatically appended to the handoff document:
## ⚠ Doom Loop Warning
The following files were modified repeatedly before this handoff. Investigate before continuing:
- src/auth.ts (8 times · 80%)
- src/main.ts (6 times · 60%)
This ensures the next session starts with awareness of potential issues.
Cost: ~$0.01
setup_repo ⭐ NEW - Agent-Driven Context SetupWhat it does: Scans the repository and returns file tree + key file contents so your agent can generate context documents. No API key required!
Parameters:
repo_path (required): Path to repositoryExample prompts:
Returns:
{
"repo_path": "/path/to/project",
"file_tree": "src/index.ts (typescript)\nsrc/auth.ts (typescript)\n...",
"key_files": [
{ "path": "package.json", "content": "..." },
{ "path": "src/index.ts", "content": "..." }
],
"instructions": "Based on the file tree and key files above, generate:\n1. context.md\n2. dependency-map.md\n3. patterns.md\nThen call save_context()..."
}
How it works:
save_context() to save themCost: Free - pure file I/O, no API calls
Why this is better:
load_context works instantlysave_context ⭐ NEW - Save Agent-Generated ContextWhat it does: Saves the 3 context documents generated by your agent to .agentbrain/ directory. Works with setup_repo for fully agent-driven setup.
Parameters:
repo_path (required): Path to repositorycontext (required): Content for context.md (architecture, modules, tech stack)dependency_map (required): Content for dependency-map.md (module relationships, data flow)patterns (required): Content for patterns.md (conventions, patterns, standards)Example prompts:
Returns:
{
"success": true,
"files_written": [
".agentbrain/context.md",
".agentbrain/dependency-map.md",
".agentbrain/patterns.md",
".agentbrain/cache.json"
],
"message": "Context saved successfully. load_context will now work without an API key."
}
What it creates:
.agentbrain/context.md - Architecture overview.agentbrain/dependency-map.md - Module relationships.agentbrain/patterns.md - Coding conventions.agentbrain/cache.json - Cache metadata with git hashCost: Free - pure file I/O
After saving:
load_context works instantlyload_standards works (if you also create standards file)load_spec, detect_doom_loop, save_handoff all workcreate_spec - Create Task SpecificationWhat it does: Creates a new task specification file from agent-generated content.
Parameters:
repoPath (required): Path to repositorytask (required): Task description or namecontent (required): Full specification contentExample prompts:
Returns:
{
"specPath": ".agentbrain/specs/add-oauth-authentication.md",
"slug": "add-oauth-authentication"
}
Cost: Free - writes to disk
Note: The agent can analyze your request, draft a comprehensive spec (problem, approach, acceptance criteria, etc.), then call this tool to save it.
detect_doom_loop - Manually Check for Doom LoopsWhat it does: Analyzes recent git history to detect if you're stuck modifying the same files repeatedly.
Parameters:
repo_path (required): Path to repositorycommit_count (optional): Number of commits to analyze (default: 10)threshold (optional): Min occurrences to trigger warning (default: 4)Example prompts:
Returns:
{
"detected": true,
"files": [
{ "path": "src/auth.ts", "count": 8, "percentage": 80 },
{ "path": "src/main.ts", "count": 6, "percentage": 60 }
],
"message": "Doom loop detected. You've modified src/auth.ts 8 times in the last 10 commits (80%). Stop coding and investigate the root cause."
}
Cost: Free - analyzes local git history
When to use:
What to do if detected:
You: "Load the context for /Users/me/my-app"
Agent: *Uses load_context tool*
Agent: "I've loaded the full context. Your app is a React/TypeScript
project with 47 files. I can see you have authentication,
user management, and API integration modules..."
You: "What are the coding standards?"
Agent: *Uses load_standards tool*
Agent: "I've loaded the standards. You're using TypeScript with strict
mode, Prettier for formatting, and following clean architecture
patterns..."
You: "Help me add a new feature for user notifications"
Agent: *Already has full context from earlier*
Agent: "Based on your current architecture, I recommend adding a
NotificationService class in src/services/..."
You: "Save a handoff with goal: Implemented notification system"
Agent: *Uses save_handoff tool*
Agent: "Handoff saved to .agentbrain/handoff.md!
Summary: Added NotificationService, integrated with existing
user system, added tests. Next steps: Add email integration
and push notification support."
AgentBrain MCP tools automatically detect doom loops - situations where you're modifying the same files repeatedly, indicating you may be stuck.
.agentbrain/update.log if threshold exceededThree "decision point" tools include doom warnings:
load_context - When loading full context at session startload_spec - When loading task specificationssave_handoff - When saving session handoffs (also appends to document)Unlike the CLI (which shows warnings once per commit), MCP tools are stateless:
When your agent calls load_context during a doom loop:
Agent: "I've loaded the repository context. However, I notice a doom loop
warning - you've been modifying src/auth.ts 8 times in the last 10
commits (80%). This suggests we may be stuck. Should we step back
and investigate the root cause first?"
The agent can proactively suggest stopping to plan rather than continuing to code.
Doom warnings clear automatically when:
Or manually via CLI:
agentbrain doom --commits 20 --threshold 6 # Check with different thresholds
1. Verify config file location:
Claude Desktop (macOS):
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
2. Check for JSON syntax errors:
3. Restart completely:
4. Check logs:
Claude Desktop:
1. Check the path exists:
# Verify the repository exists
ls ~/my-project # or whatever path you're using
2. Check API key for generation:
If loading context for the first time:
# Check if key exists
echo $ANTHROPIC_API_KEY
# Or
agentbrain config --show
3. Check the repo exists:
ls /path/to/your/project
Adjust sensitivity via CLI:
Doom detection uses these defaults:
To change thresholds, edit the post-commit hook or run manually:
agentbrain doom --commits 15 --threshold 6
Excluded automatically:
False positives are rare - if you see a doom warning, you're likely stuck on a problem.
1. Check if doom detection is enabled:
# Verify post-commit hook exists
ls -la .git/hooks/post-commit
# or for Husky:
ls -la .husky/post-commit
2. Check update log:
cat .agentbrain/update.log | grep DOOM
3. Manually check for doom loop:
agentbrain doom
4. Reinstall hooks if needed:
agentbrain disable --remove-hooks
agentbrain setup --no-confirm
{
"mcpServers": {
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"]
}
}
}
{
"mcpServers": {
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-..."
}
}
}
}
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
},
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_..."
}
}
}
}
Option A: Agent-Driven Setup (Recommended, no API key needed)
You: "Set up AgentBrain for /path/to/project"
Agent: *Uses setup_repo tool*
Agent: "I've analyzed your codebase. Let me generate context documents..."
Agent: *Generates context.md, dependency-map.md, patterns.md*
Agent: *Uses save_context tool*
Agent: "Done! Context saved to .agentbrain/. All tools now work instantly."
Option B: CLI Setup (Requires API key once)
cd /path/to/project
agentbrain init
Both create the cache, making MCP tool calls instant and free.
AgentBrain automatically handles different path formats:
✅ "Load context for /Users/me/my-project" (absolute)
✅ "Load context for ~/my-project" (~ expansion)
✅ "Load context for ../my-project" (relative)
All three work! The MCP server automatically expands them.
Create standards files so load_standards works:
cd /path/to/project
agentbrain standards
Start each day by asking:
"Load the context and standards for /Users/me/my-project"
This gives your agent full project awareness immediately.
Q: Does this cost money? A: Depends on the tool:
scan_repo - Freesetup_repo ⭐ NEW - Free (no API key needed!)save_context ⭐ NEW - Freeload_spec - Freeload_standards - Freedetect_doom_loop - Freecreate_spec - Freeload_context (cached) - Freeload_context (first time with API key) - ~$0.02-0.05save_handoff - ~$0.01Q: Can I use AgentBrain without an API key?
A: YES! Use the new setup_repo + save_context workflow:
setup_repo to scan files (no API call)save_context to save them (no API call)
After that, ALL tools work without an API key!Q: Where does it get the API key?
A: From environment variables (ANTHROPIC_API_KEY or OPENAI_API_KEY) or from ~/.agentbrain/config.json (set via agentbrain config). But with setup_repo + save_context, you don't need one!
Q: Can I use this without the CLI? A: Yes! The MCP server works standalone. You can either:
setup_repo + save_context (no API key, agent-driven)agentbrain init) to generate context (requires API key)Q: Which agent is best? A: All four work great:
Q: How do I update?
npm update -g @agentbrain/mcp-server
MIT
FAQs
Model Context Protocol server for AgentBrain - connect Claude, Cursor, and Windsurf to repository intelligence
We found that @agentbrain/mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.