@agentbrain/mcp-server

Model Context Protocol (MCP) server for AgentBrain - connect your AI agent directly to repository intelligence.

What is This?

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:

• 🔍 Scan your repository structure
• 📖 Load comprehensive codebase context
• 📝 Load task specifications
• 📋 Read coding standards
• 💾 Save session handoffs
• ⚠️ Detect doom loops automatically

No CLI commands needed - your agent does it all automatically!

Installation

npm install -g @agentbrain/mcp-server

Setup by Platform

🔵 Claude Code

Step 1: Edit Claude Code MCP Config

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

Step 2: Add AgentBrain to Config

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"]
    }
  }
}

Step 3: Restart Claude Code

Exit Claude Code completely and reopen it.

Step 4: Verify It's Working

1. Start a new session in Claude Code
2. Type /mcp or check MCP tools list
3. You should see "agentbrain" with 9 tools available

Step 5: Try It Out!

Ask Claude:

"Use the scan_repo tool to analyze my project at /Users/yourname/my-project"

Claude will automatically use the AgentBrain tools!

🟣 Claude Desktop

Step 1: Edit Claude Desktop Config

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

Step 2: Add AgentBrain to Config

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"]
    }
  }
}

Step 3: Restart Claude Desktop

Completely quit Claude Desktop (don't just close the window):

• macOS: Cmd + Q or Claude → Quit Claude
• Windows: Right-click taskbar icon → Quit

Then reopen it.

Step 5: Verify It's Working

1. Start a new conversation in Claude Desktop
2. Look for the 🔌 icon in the toolbar or bottom of the chat
3. Click it - you should see "agentbrain" with 9 tools:
   • scan_repo
   • load_standards
   • load_context
   • setup_repo ⭐ NEW
   • save_context ⭐ NEW
   • load_spec
   • detect_doom_loop
   • create_spec
   • save_handoff

Step 6: Try It Out!

Ask Claude:

"Use the scan_repo tool to analyze my project at /Users/yourname/my-project"

Claude will automatically use the AgentBrain tools!

🔵 Cursor

Step 1: Open Cursor MCP Settings

1. Open Cursor
2. Press Cmd + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux)
3. Type "MCP" and select "MCP: Configure Servers"

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

Step 2: Add AgentBrain Configuration

{
  "mcpServers": {
    "agentbrain": {
      "command": "npx",
      "args": ["-y", "@agentbrain/mcp-server"]
    }
  }
}

Step 3: Restart Cursor

Completely quit and reopen Cursor.

Step 4: Verify

1. Open a project in Cursor
2. Open the Cursor chat (usually Cmd + L or Ctrl + L)
3. Type @ and you should see MCP tools available
4. Or check the MCP panel in settings

Step 5: Use It

In Cursor chat:

"Scan the current repository using AgentBrain"

Cursor will automatically use the MCP tools!

🟢 Windsurf

Step 1: Open Windsurf Settings

Method 1: Via UI

1. Open Windsurf
2. Go to Settings (gear icon)
3. Search for "MCP" or "Model Context Protocol"
4. Add new server configuration

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

Step 2: Add AgentBrain

{
  "mcpServers": {
    "agentbrain": {
      "command": "npx",
      "args": ["-y", "@agentbrain/mcp-server"]
    }
  }
}

Step 3: Restart Windsurf

Quit completely and reopen.

Step 4: Verify & Use

Look for MCP tools in the Windsurf interface, then ask:

"Use AgentBrain to scan this project"

Available Tools

Once configured, your agent can use these 9 tools:

1. scan_repo - Analyze Repository Structure

What it does: Scans your repository and lists all relevant files with language and size info.

Example prompts for your agent:

• "Scan this repository at /path/to/project"
• "Show me the structure of my codebase"
• "What files are in this project?"

Cost: Free - no API calls

2. load_context - Load Full Context

What it does: Loads comprehensive documentation about your entire codebase (context.md + dependency-map.md + patterns.md).

Example prompts:

• "Load the context for /path/to/project"
• "Give me the full context of this codebase"
• "Load project intelligence for my app"

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:

• First time: ~$0.02-0.05 (generates documentation)
• After that: $0.00 (uses cache)

Note: If the context doesn't exist, it will generate it using your API key.

3. load_spec - Load Task Specification

What it does: Loads a task specification file by name, or lists all available specs if no task is specified.

Parameters:

• repoPath (required): Path to repository
• task (optional): Task description or slug (e.g., "add-oauth-authentication")

Example prompts:

• "Load the spec for add-oauth-authentication"
• "Show me available specs"
• "Load the task spec for user authentication"

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.

4. load_standards - Load Coding Standards

What it does: Loads the coding standards file for your specific agent (CLAUDE.md, .cursor/rules, or .windsurfrules).

Example prompts:

• "Load the coding standards for this project"
• "What are my code standards?"
• "Show me the project conventions"

Cost: Free - reads from disk

Note: Standards file must exist (create with agentbrain standards CLI command first).

5. save_handoff - Save Session Handoff

What it does: Analyzes your recent git changes and creates a handoff document for the next session.

Parameters:

• repo_path (required): Path to repository
• goal (optional): Session goal or objective
• commit_count (optional): Number of recent commits to include (default: 5)

Example prompts:

• "Save a handoff for this session"
• "Create a handoff document with goal: implemented auth"
• "Generate a session summary with the last 10 commits"

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

6. setup_repo ⭐ NEW - Agent-Driven Context Setup

What 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 repository

Example prompts:

• "Set up AgentBrain for this project"
• "Scan /path/to/project and help me generate context"
• "Initialize AgentBrain context for my repo"

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:

1. Scans repository to find 30 most relevant files
2. Returns file tree and actual file contents
3. Your agent reads and analyzes the code
4. Agent generates 3 context documents based on what it learned
5. Agent calls save_context() to save them

Cost: Free - pure file I/O, no API calls

Why this is better:

• No API key needed - your agent does the analysis
• Agent understands - it reads actual code, not generated summaries
• Customizable - agent can focus on what matters for your current task
• One-time setup - after saving, load_context works instantly

7. save_context ⭐ NEW - Save Agent-Generated Context

What 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 repository
• context (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:

• "Save the context I generated to .agentbrain/"
• "Write these context files to disk"

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 hash

Cost: Free - pure file I/O

After saving:

• load_context works instantly
• load_standards works (if you also create standards file)
• load_spec, detect_doom_loop, save_handoff all work
• No API key needed for any subsequent operations

8. create_spec - Create Task Specification

What it does: Creates a new task specification file from agent-generated content.

Parameters:

• repoPath (required): Path to repository
• task (required): Task description or name
• content (required): Full specification content

Example prompts:

• "Create a spec for adding OAuth authentication"
• "Save this specification as add-stripe-integration"

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.

9. detect_doom_loop - Manually Check for Doom Loops

What it does: Analyzes recent git history to detect if you're stuck modifying the same files repeatedly.

Parameters:

• repo_path (required): Path to repository
• commit_count (optional): Number of commits to analyze (default: 10)
• threshold (optional): Min occurrences to trigger warning (default: 4)

Example prompts:

• "Check if I'm in a doom loop"
• "Analyze my recent commits for patterns"
• "Am I stuck on any files?"

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:

• When you feel stuck on a problem
• After multiple failed attempts
• Before starting a coding session
• When agent suggests checking

What to do if detected:

• Stop coding immediately
• Review why the file keeps being modified
• Plan a different approach
• Consider refactoring or architectural changes

Complete Workflow Example

Morning: Start Your Day

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..."

During Development

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/..."

End of Day

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."

Doom Loop Detection in MCP

AgentBrain MCP tools automatically detect doom loops - situations where you're modifying the same files repeatedly, indicating you may be stuck.

How It Works

1. Post-commit hook analyzes git history in the background
2. Hook logs detection to .agentbrain/update.log if threshold exceeded
3. MCP tools check for pending doom warnings on every call
4. Warning included in tool responses if detected

Which Tools Return Doom Warnings

Three "decision point" tools include doom warnings:

• load_context - When loading full context at session start
• load_spec - When loading task specifications
• save_handoff - When saving session handoffs (also appends to document)

Stateless Design

Unlike the CLI (which shows warnings once per commit), MCP tools are stateless:

• Warning appears in every tool response while the doom condition exists
• Never marked as "shown" - agents can see warnings multiple times
• This ensures warnings aren't missed in long sessions

Example: Agent Response with Doom Warning

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.

Clearing Doom Warnings

Doom warnings clear automatically when:

• You commit changes to different files (breaking the pattern)
• Enough commits pass that repeated files drop below threshold

Or manually via CLI:

agentbrain doom --commits 20 --threshold 6  # Check with different thresholds

Troubleshooting

"AgentBrain not showing up in my agent"

1. Verify config file location:

Claude Desktop (macOS):

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Check for JSON syntax errors:

• Missing commas between entries
• Missing quotes
• Invalid path format

3. Restart completely:

• Don't just close the window
• Actually quit the application (Cmd+Q / Ctrl+Q)
• Reopen

4. Check logs:

Claude Desktop:

• Go to Help → Show Logs (or Developer → Show Logs)
• Look for MCP connection errors

"Tool calls are failing"

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

"Doom warnings appearing too often"

Adjust sensitivity via CLI:

Doom detection uses these defaults:

• Last 10 commits analyzed
• File must appear 4+ times to trigger (40%+)

To change thresholds, edit the post-commit hook or run manually:

agentbrain doom --commits 15 --threshold 6

Excluded automatically:

• Lock files (package-lock.json, yarn.lock, etc.)
• AgentBrain files (CLAUDE.md, .cursorrules, etc.)
• Markdown documentation files

False positives are rare - if you see a doom warning, you're likely stuck on a problem.

"Doom warnings not appearing when they should"

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

Configuration Examples

Minimal Configuration (Recommended)

{
  "mcpServers": {
    "agentbrain": {
      "command": "npx",
      "args": ["-y", "@agentbrain/mcp-server"]
    }
  }
}

With Environment Variables

{
  "mcpServers": {
    "agentbrain": {
      "command": "npx",
      "args": ["-y", "@agentbrain/mcp-server"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Multiple MCP Servers

{
  "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_..."
      }
    }
  }
}

Tips for Best Results

1. Generate Context (Two Options)

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.

2. Paths Are Flexible

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.

3. Generate Standards

Create standards files so load_standards works:

cd /path/to/project
agentbrain standards

4. Morning Routine

Start each day by asking:

"Load the context and standards for /Users/me/my-project"

This gives your agent full project awareness immediately.

Frequently Asked Questions

Q: Does this cost money? A: Depends on the tool:

• scan_repo - Free
• setup_repo ⭐ NEW - Free (no API key needed!)
• save_context ⭐ NEW - Free
• load_spec - Free
• load_standards - Free
• detect_doom_loop - Free
• create_spec - Free
• load_context (cached) - Free
• load_context (first time with API key) - ~$0.02-0.05
• save_handoff - ~$0.01

Q: Can I use AgentBrain without an API key? A: YES! Use the new setup_repo + save_context workflow:

1. Ask your agent to "Set up AgentBrain for /path/to/project"
2. Agent uses setup_repo to scan files (no API call)
3. Agent reads and analyzes the code
4. Agent generates context documents
5. Agent uses 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:

• Use setup_repo + save_context (no API key, agent-driven)
• Use CLI once (agentbrain init) to generate context (requires API key)

Q: Which agent is best? A: All four work great:

• Claude Code - Official CLI, excellent MCP support, fast and lightweight
• Claude Desktop - Native MCP support, excellent integration
• Cursor - Popular for coding, good MCP support
• Windsurf - Emerging option with MCP support

Q: How do I update?

npm update -g @agentbrain/mcp-server

Related Packages

• @agentbrain/cli - Generate context via command line
• @agentbrain/core - Core library for custom integrations

Support

• Documentation: Main README
• Issues: GitHub Issues
• MCP Protocol: modelcontextprotocol.io

License

MIT