Scout MCP Server

MCP (Model Context Protocol) server that exposes Swarm Scout query capabilities to other agents.

What is This?

This MCP server allows any MCP-compatible agent (like Claude Desktop) to use Swarm Scout as a tool for querying and analyzing codebases. Instead of the agent manually using bash and grep, it can ask Scout (which has its own LLM-powered analysis) to find context.

Features

• ceregrep_query: Query Scout to find context in codebases
• Natural language queries (e.g., "Find all async functions", "Explain the auth flow")
• Automatic code exploration using ceregrep's bash + grep tools
• LLM-powered analysis and context gathering

Prerequisites

1. Swarm Scout CLI installed globally:

   npm install -g swarm-scout

1. Python ≥ 3.10 (for pip installation) or uvx (for no-install usage)

Installation

Option 1: Using uvx (Recommended - No Installation Required)

# No installation needed! Just use uvx to run it
uvx scout-mcp

Option 2: Install via pip

pip install scout-mcp

Option 3: Install from source (Development)

cd mcp-server
pip install -e .

Usage

Using with uvx (Recommended)

The easiest way to use scout-mcp is with uvx, which runs the package without installation:

uvx scout-mcp

Add to Claude Desktop

Method 1: Using Claude MCP CLI (Easiest)

claude mcp add scout uvx scout-mcp

This automatically adds scout-mcp to your Claude configuration.

Method 2: Manual Configuration

Edit your Claude Desktop MCP configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "scout": {
      "command": "uvx",
      "args": ["scout-mcp"]
    }
  }
}

If you installed via pip:

{
  "mcpServers": {
    "scout": {
      "command": "scout-mcp"
    }
  }
}

Add to Other MCP Clients

For any MCP-compatible client, add to your mcp.json or equivalent config file:

{
  "mcpServers": {
    "ceregrep": {
      "command": "uvx",
      "args": ["ceregrep-mcp"],
      "env": {}
    }
  }
}

Add to Scout Itself (Recursive Pattern)

You can even use Scout's own MCP client to connect to this server! Add to .swarmrc:

{
  "mcpServers": {
    "scout-context": {
      "type": "stdio",
      "command": "uvx",
      "args": ["scout-mcp"]
    }
  }
}

Now Scout can delegate context-finding to another instance of itself!

Available Tools

ceregrep_query

Query ceregrep to find context in a codebase.

Parameters:

• query (required): Natural language query
• cwd (optional): Working directory to run ceregrep in
• model (optional): LLM model to use
• verbose (optional): Enable verbose output

Example queries:

• "Find all async functions in this codebase"
• "Explain how the authentication system works"
• "Show me all API endpoints"
• "Find files that handle database connections"
• "Analyze the project architecture"

Agent Tools (7 Specialized Agents)

All ceregrep agents are automatically exposed as MCP tools! External systems like Claude Code can invoke specialized agents directly.

Available agents:

1. agent_debug_agent - Debugging expert

• Analyzes error messages and stack traces
• Identifies root causes of bugs
• Suggests fixes with explanations

1. agent_context_agent - Context discovery specialist

• Explores codebases systematically
• Maps architecture and code flows
• Provides comprehensive context

1. agent_postgres_agent - PostgreSQL specialist

• Database schema analysis
• Query optimization
• SQL best practices

1. agent_review_agent - Code review expert

• Reviews code for quality and best practices
• Identifies security vulnerabilities
• Suggests improvements

1. agent_test_agent - Test writing specialist

• Writes comprehensive unit/integration tests
• Identifies test coverage gaps
• Follows testing best practices

1. agent_docs_agent - Documentation expert

• Generates API documentation
• Writes README files and guides
• Creates clear, comprehensive docs

1. agent_orchestrator_agent - Meta-agent coordinator

• Coordinates multiple specialized agents
• Breaks down complex problems
• Synthesizes responses from agents

Parameters (all agents):

• prompt (required): The prompt/query to send to the agent
• cwd (optional): Working directory to run in
• model (optional): LLM model to use
• verbose (optional): Enable verbose output

Example usage:

• agent_debug_agent: "Why is my authentication failing with a 401 error?"
• agent_context_agent: "Explain the payment processing system architecture"
• agent_review_agent: "Review the authentication middleware for security issues"

Example: Using Agents from Claude Code

Once you've added ceregrep-mcp to Claude Code, you can ask Claude to use specialized agents:

User: "Use the debug-agent to investigate why login is returning 401 errors"

Claude Code: (Sees agent_debug_agent as available tool, invokes it)

The debug agent will:

1. Explore your authentication code
2. Check error handling patterns
3. Analyze JWT validation logic
4. Provide specific debugging guidance

Response format:

## Debug Agent Response

**Prompt:** Investigate why login is returning 401 errors

I've analyzed your authentication system. Here's what I found:

1. JWT Token Validation (src/auth/middleware.ts:45)
   - The token expiration check is failing
   - Issue: Clock skew between server and client

2. Suggested Fix:
   - Add a 30-second leeway to token validation
   - Update JWT_VERIFY_OPTIONS to include clockTolerance

[... detailed debugging context ...]

How It Works

1. Agent sends a natural language query to ceregrep_query tool
2. MCP server invokes the Scout CLI with the query
3. Scout uses its own LLM + bash + grep tools to explore the codebase
4. Results are returned to the requesting agent

This creates a recursive agent pattern where agents can delegate complex context-finding to specialized sub-agents.

Configuration

The MCP server uses the Scout CLI, which reads configuration from:

• .swarmrc in the working directory (recommended)
• .ceregrep.json in the working directory (deprecated but supported)
• ~/.swarmrc (global config)
• Environment variables (ANTHROPIC_API_KEY, CEREBRAS_API_KEY)

Development

Project Structure

mcp-server/
├── mcp_server.py           # Main MCP server
├── tool_discovery.py       # Auto-discovery system
├── tools/
│   ├── base_tool.py        # Base tool class
│   └── ceregrep_query_tool.py  # Ceregrep query tool
├── pyproject.toml          # Dependencies
└── README.md               # This file

Adding New Tools

1. Create a new file in tools/
2. Inherit from BaseTool
3. Implement name, description, input_schema, and execute()
4. Restart server - tool is auto-discovered!

Agent Discovery and Caching

The MCP server automatically discovers agents by running scout agent list --json. To optimize performance:

• Agent list is cached for 5 minutes - New agents will be visible within 5 minutes without restarting the MCP server
• Cache refreshes automatically - After 5 minutes, the agent list is refreshed on the next tool list request
• Manual refresh - Restart the MCP server to immediately refresh the agent list

This means you can:

1. Create a new agent with scout agent init or scout agent import
2. Use it in Claude Code within 5 minutes (or restart the MCP server for immediate availability)

Troubleshooting

"scout command not found"

Install the Scout CLI globally:

npm install -g swarm-scout

MCP connection errors

Ensure Python ≥ 3.10 and uv are installed:

python --version  # Should be ≥ 3.10
uv --version      # Should be installed

Query failures

Check Scout configuration:

scout config  # View current config

Ensure API keys are set:

• ANTHROPIC_API_KEY for Claude
• CEREBRAS_API_KEY for Cerebras

License

AGPL-3.0-or-later