feat: Add custom MCP server support

Introduces the ability to configure additional MCP (Model Context Protocol) servers through organization and project configuration files. This feature extends the agent's capabilities by allowing users to define custom tools.

Implements a robust configuration system that:
- Loads and validates MCP server definitions and org-level blocked tools.
- Supports variable substitution in commands, arguments, and environment variables.
- Resolves configuration hierarchy, allowing project-level definitions to override organization-level ones.
- Integrates custom tools into the agent's security context, enforcing explicit tool allowlists and organization-wide blocks.

Updates `CLAUDE.md` with detailed documentation on configuring and managing custom MCP servers, including schema and key behaviors. Provides example configuration files.

Author: derhally

CLAUDE.md

@@ -325,6 +325,61 @@ blocked_commands:
 - `examples/org_config.yaml` - Org config example (all commented by default)
 - `examples/README.md` - Comprehensive guide with use cases, testing, and troubleshooting
 
+#### Custom MCP Servers
+
+The agent supports adding custom MCP (Model Context Protocol) servers via configuration files. This allows extending the agent's capabilities with additional tools.
+
+**Configuration Locations:**
+- **Org-level**: `~/.autocoder/config.yaml` - Available to ALL projects
+- **Project-level**: `{project}/.autocoder/allowed_commands.yaml` - Project-specific
+
+**MCP Server Config Schema:**
+
+```yaml
+# ~/.autocoder/config.yaml (org-level)
+version: 1
+
+mcp_servers:
+  - name: filesystem
+    command: npx
+    args:
+      - "@anthropic/mcp-server-filesystem"
+      - "${PROJECT_DIR}"  # Variable substitution
+    env:
+      SOME_VAR: value
+    allowed_tools:  # REQUIRED - explicit list of tools to allow
+      - read_file
+      - list_directory
+
+# Org-level can block specific tools across ALL projects
+blocked_mcp_tools:
+  - filesystem__write_file    # Block write across all projects
+  - filesystem__delete_file
+```
+
+**Variable Substitution:**
+- `${PROJECT_DIR}` - Absolute path to project directory
+- `${HOME}` - User's home directory
+
+**Tool Naming Convention:**
+- MCP tools follow the pattern `mcp__{server}__{tool}`
+- Config uses short names: `allowed_tools: [read_file]`
+- Becomes: `mcp__filesystem__read_file`
+
+**Key Behaviors:**
+- `allowed_tools` is REQUIRED for each MCP server - must explicitly list tools
+- Org `blocked_mcp_tools` takes precedence - projects cannot allow blocked tools
+- Environment variables merge with parent environment
+- Project can override org MCP server by using the same name
+
+**Example Output:**
+
+```
+Created security settings at /path/to/project/.claude_settings.json
+   - MCP servers: playwright (browser), features (database), filesystem (custom)
+   - Blocked MCP tools (org): filesystem__write_file, filesystem__delete_file
+```
+
 ### Ollama Local Models (Optional)
 
 Run coding agents using local models via Ollama v0.14.0+:

client.py

@@ -1,5 +1,6 @@
 """
 Claude SDK Client Configuration
+Claude SDK Client Configuration
 ===============================
 
 Functions for creating and configuring the Claude Agent SDK client.
@@ -11,13 +12,19 @@
 import shutil
 import sys
 from pathlib import Path
+from typing import Any
 
 from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from claude_agent_sdk.types import HookContext, HookInput, HookMatcher, SyncHookJSONOutput
 from dotenv import load_dotenv
 
 from env_constants import API_ENV_VARS
-from security import SENSITIVE_DIRECTORIES, bash_security_hook
+from security import (
+    SENSITIVE_DIRECTORIES,
+    bash_security_hook,
+    get_effective_mcp_servers,
+    get_effective_mcp_tools,
+)
 
 # Load environment variables from .env file if present
 load_dotenv()
@@ -182,6 +189,37 @@ def get_extra_read_paths() -> list[Path]:
     return validated_paths
 
 
+def substitute_variables(value: str, project_dir: Path) -> str:
+    """
+    Substitute variables in a configuration value.
+
+    Supported variables:
+    - ${PROJECT_DIR} - Absolute path to project directory
+    - ${HOME} - User's home directory
+
+    Args:
+        value: String value that may contain variables
+        project_dir: Path to the project directory
+
+    Returns:
+        String with variables substituted
+    """
+    result = value
+    result = result.replace("${PROJECT_DIR}", str(project_dir.resolve()))
+    result = result.replace("${HOME}", str(Path.home()))
+    return result
+
+
+def substitute_variables_in_list(values: list[str], project_dir: Path) -> list[str]:
+    """Substitute variables in a list of strings."""
+    return [substitute_variables(v, project_dir) for v in values]
+
+
+def substitute_variables_in_dict(values: dict[str, str], project_dir: Path) -> dict[str, str]:
+    """Substitute variables in a dict of strings."""
+    return {k: substitute_variables(v, project_dir) for k, v in values.items()}
+
+
 # Per-agent-type MCP tool lists.
 # Only expose the tools each agent type actually needs, reducing tool schema
 # overhead and preventing agents from calling tools meant for other roles.
@@ -309,6 +347,7 @@ def create_client(
     Note: Authentication is handled by start.bat/start.sh before this runs.
     The Claude SDK auto-detects credentials from the Claude CLI configuration
     """
+    
     # Select the feature MCP tools appropriate for this agent type
     feature_tools_map = {
         "coding": CODING_AGENT_TOOLS,
@@ -327,12 +366,21 @@ def create_client(
     }
     max_turns = max_turns_map.get(agent_type, 300)
 
+   # Load user-configured MCP servers from org and project configs
+    user_mcp_servers, blocked_mcp_tools = get_effective_mcp_servers(project_dir)
+    user_mcp_tools, user_mcp_permissions = get_effective_mcp_tools(
+        user_mcp_servers, blocked_mcp_tools
+    )
+
     # Build allowed tools list based on mode and agent type.
     # In YOLO mode, exclude Playwright tools for faster prototyping.
     allowed_tools = [*BUILTIN_TOOLS, *feature_tools]
     if not yolo_mode:
         allowed_tools.extend(PLAYWRIGHT_TOOLS)
 
+    # Add user-configured MCP tools
+    allowed_tools.extend(user_mcp_tools)
+
     # Build permissions list.
     # We permit ALL feature MCP tools at the security layer (so the MCP server
     # can respond if called), but the LLM only *sees* the agent-type-specific
@@ -367,6 +415,9 @@ def create_client(
         # Allow Playwright MCP tools for browser automation (standard mode only)
         permissions_list.extend(PLAYWRIGHT_TOOLS)
 
+    # Add user-configured MCP tool permissions
+    permissions_list.extend(user_mcp_permissions)
+
     # Create comprehensive security settings
     # Note: Using relative paths ("./**") restricts access to project directory
     # since cwd is set to project_dir
@@ -394,10 +445,22 @@ def create_client(
     if extra_read_paths:
         print(f"   - Extra read paths (validated): {', '.join(str(p) for p in extra_read_paths)}")
     print("   - Bash commands restricted to allowlist (see security.py)")
-    if yolo_mode:
+
+    # Report MCP servers
+    builtin_servers = ["features (database)"]
+    if not yolo_mode:
+        builtin_servers.insert(0, "playwright (browser)")
+    user_server_names = [s["name"] for s in user_mcp_servers]
+    if user_server_names:
+        all_servers = builtin_servers + [f"{name} (custom)" for name in user_server_names]
+        print(f"   - MCP servers: {', '.join(all_servers)}")
+    elif yolo_mode:
         print("   - MCP servers: features (database) - YOLO MODE (no Playwright)")
     else:
         print("   - MCP servers: playwright (browser), features (database)")
+
+    if blocked_mcp_tools:
+        print(f"   - Blocked MCP tools (org): {', '.join(sorted(blocked_mcp_tools))}")
     print("   - Project settings enabled (skills, commands, CLAUDE.md)")
     print()
 
@@ -448,6 +511,35 @@ def create_client(
             "args": playwright_args,
         }
 
+    # Add user-configured MCP servers from org and project configs
+    for server_config in user_mcp_servers:
+        server_name = server_config["name"]
+
+        # Skip if server name conflicts with built-in servers
+        if server_name in mcp_servers:
+            print(f"   - Warning: Custom MCP server '{server_name}' conflicts with built-in, skipping")
+            continue
+
+        # Build server entry with variable substitution
+        server_entry: dict[str, Any] = {
+            "command": substitute_variables(server_config["command"], project_dir),
+        }
+
+        # Add args with variable substitution
+        if "args" in server_config:
+            server_entry["args"] = substitute_variables_in_list(
+                server_config["args"], project_dir
+            )
+
+        # Add env with variable substitution, merging with parent environment
+        if "env" in server_config:
+            server_entry["env"] = substitute_variables_in_dict(
+                server_config["env"], project_dir
+            )
+
+        mcp_servers[server_name] = server_entry
+        print(f"   - Custom MCP server '{server_name}': {server_config['command']}")
+
     # Build environment overrides for API endpoint configuration
     # These override system env vars for the Claude CLI subprocess,
     # allowing AutoCoder to use alternative APIs (e.g., GLM) without

examples/org_config.yaml

@@ -91,6 +91,78 @@ blocked_commands: []
   # - puppet
 
 
+# ==========================================
+# Custom MCP Servers
+# ==========================================
+# Configure additional MCP (Model Context Protocol) servers that will be
+# available to the agent in ALL projects.
+#
+# Each MCP server MUST specify:
+#   - name: Unique identifier for the server
+#   - command: Command to run (e.g., "npx", "python")
+#   - allowed_tools: REQUIRED list of tools to allow (explicit allowlist)
+#
+# Optional fields:
+#   - args: List of command arguments
+#   - env: Environment variables (merged with parent environment)
+#
+# Variable substitution is supported:
+#   - ${PROJECT_DIR} - Absolute path to current project directory
+#   - ${HOME} - User's home directory
+#
+# By default, no custom MCP servers are configured.
+
+mcp_servers: []
+
+  # Example: Filesystem MCP server (read-only)
+  # - name: filesystem
+  #   command: npx
+  #   args:
+  #     - "@anthropic/mcp-server-filesystem"
+  #     - "${PROJECT_DIR}"
+  #   allowed_tools:
+  #     - read_file
+  #     - list_directory
+  #     - search_files
+
+  # Example: Memory MCP server for persistent context
+  # - name: memory
+  #   command: npx
+  #   args:
+  #     - "@anthropic/mcp-server-memory"
+  #   env:
+  #     MEMORY_DIR: "${HOME}/.autocoder/memory"
+  #   allowed_tools:
+  #     - store_memory
+  #     - retrieve_memory
+  #     - search_memory
+
+
+# ==========================================
+# Blocked MCP Tools (Organization-Wide)
+# ==========================================
+# Tools listed here are BLOCKED across ALL projects.
+# Projects CANNOT override these blocks.
+#
+# Tool naming convention: {server}__{tool} or mcp__{server}__{tool}
+# Examples:
+#   - filesystem__write_file    (blocks filesystem server's write_file tool)
+#   - filesystem__delete_file   (blocks filesystem server's delete_file tool)
+#   - myserver__*               (blocks ALL tools from myserver - wildcard)
+#
+# By default, no tools are blocked.
+
+blocked_mcp_tools: []
+
+  # Block dangerous filesystem operations
+  # - filesystem__write_file
+  # - filesystem__delete_file
+  # - filesystem__move_file
+
+  # Block all tools from a specific server (wildcard)
+  # - dangerous_server__*
+
+
 # ==========================================
 # Global Settings (Phase 3 feature)
 # ==========================================

examples/project_allowed_commands.yaml

@@ -103,6 +103,53 @@ commands: []
   #   description: Deploy to staging environment
 
 
+# ==========================================
+# Custom MCP Servers
+# ==========================================
+# Configure additional MCP (Model Context Protocol) servers for THIS PROJECT.
+# These are added to any org-level MCP servers defined in ~/.autocoder/config.yaml
+#
+# Each MCP server MUST specify:
+#   - name: Unique identifier for the server
+#   - command: Command to run (e.g., "npx", "python")
+#   - allowed_tools: REQUIRED list of tools to allow (explicit allowlist)
+#
+# Optional fields:
+#   - args: List of command arguments
+#   - env: Environment variables (merged with parent environment)
+#
+# Variable substitution is supported:
+#   - ${PROJECT_DIR} - Absolute path to current project directory
+#   - ${HOME} - User's home directory
+#
+# By default, no custom MCP servers are configured.
+
+mcp_servers: []
+
+  # Example: SQLite MCP server for this project's database
+  # - name: sqlite
+  #   command: npx
+  #   args:
+  #     - "@anthropic/mcp-server-sqlite"
+  #     - "${PROJECT_DIR}/data.db"
+  #   allowed_tools:
+  #     - read_query
+  #     - list_tables
+  #     - describe_table
+
+  # Example: Custom project-specific MCP server
+  # - name: my_project_tools
+  #   command: python
+  #   args:
+  #     - "${PROJECT_DIR}/tools/mcp_server.py"
+  #   env:
+  #     PROJECT_ROOT: "${PROJECT_DIR}"
+  #   allowed_tools:
+  #     - build_project
+  #     - run_tests
+  #     - deploy_staging
+
+
 # ==========================================
 # Notes and Best Practices
 # ==========================================