Agentic Control Framework (ACF)

# 🔌 MCP Client Configurations for ACF This guide shows how to configure different MCP clients to work with your ACF server via mcp-proxy. ## ✅ Verified Client Configurations (100% Tested) All client configurations have been thoroughly tested and verified to work with ACF: - **Claude Code**: ✅ TESTED - Full integration working, all tools functional - **Claude Desktop**: ✅ TESTED - Full integration working - **Cursor**: ✅ TESTED - All methods verified - **VS Code (Cline/Continue)**: ✅ TESTED - Extension compatibility confirmed - **Windsurf**: ✅ TESTED - Configuration validated - **Generic MCP Clients**: ✅ TESTED - Standard protocol compliance ## ✅ Prerequisites 1. **Start your ACF MCP-proxy server**: ```bash mcp-proxy --port 8080 --debug node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd) ``` 2. **Verify it's working**: ```bash curl -s http://localhost:8080/health ``` ## 🎯 Client Configurations ### 1. **Claude Code** (Anthropic's Official CLI) - RECOMMENDED **Why Claude Code is Recommended:** - Built-in MCP support with excellent tool discovery - Rich tool descriptions and parameter validation - Real-time streaming and performance optimization - Advanced debugging capabilities - Official Anthropic support and frequent updates **Configuration Method 1: Using Pre-configured File (Easiest)** ```bash # Navigate to your project directory cd /path/to/your/project # Copy ACF's ready-to-use configuration cp /path/to/agentic-control-framework/claude-mcp-config.json . # Add ACF server to Claude Code claude mcp add acf-server \ -e ACF_PATH="/path/to/agentic-control-framework" \ -e WORKSPACE_ROOT="$(pwd)" \ -e READONLY_MODE="false" \ -e BROWSER_HEADLESS="false" \ -e DEFAULT_SHELL="/bin/bash" \ -e NODE_ENV="production" \ -- node /path/to/agentic-control-framework/bin/agentic-control-framework-mcp --workspaceRoot "$(pwd)" # Start Claude Code claude ``` **Configuration Method 2: Manual Setup** Add to your Claude Code MCP settings: ```json { "mcpServers": { "agentic-control-framework": { "type": "stdio", "command": "/FULL/PATH/TO/agentic-control-framework/bin/agentic-control-framework-mcp", "env": { "ACF_PATH": "/FULL/PATH/TO/agentic-control-framework", "WORKSPACE_ROOT": "/FULL/PATH/TO/YOUR/WORKSPACE", "ALLOWED_DIRS": "/FULL/PATH/TO/YOUR/WORKSPACE:/tmp", "READONLY_MODE": "false", "BROWSER_HEADLESS": "false", "DEFAULT_SHELL": "/bin/bash", "NODE_ENV": "production" } } } } ``` **Configuration Method 3: Via MCP-Proxy (Remote)** ```json { "mcpServers": { "agentic-control-framework": { "transport": { "type": "sse", "url": "http://localhost:8080/sse" } } } } ``` **Testing Claude Code Integration:** ```bash # Verify configuration claude --test-tools # Interactive session claude ``` ### 2. **Claude Desktop** (Desktop App) **⚠️ IMPORTANT: Use ONLY the Direct Executable Method - This is the ONLY method confirmed to work reliably** **Location**: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` **Configuration (Direct STDIO - RECOMMENDED)**: ```json { "mcpServers": { "agentic-control-framework": { "command": "/FULL/PATH/TO/agentic-control-framework/bin/agentic-control-framework-mcp", "env": { "ACF_PATH": "/FULL/PATH/TO/agentic-control-framework", "WORKSPACE_ROOT": "/FULL/PATH/TO/YOUR/WORKSPACE", "ALLOWED_DIRS": "/FULL/PATH/TO/YOUR/WORKSPACE:/tmp", "READONLY_MODE": "false", "BROWSER_HEADLESS": "false", "DEFAULT_SHELL": "/bin/bash" } } } } ``` **⚠️ CRITICAL REQUIREMENTS:** - Use **FULL ABSOLUTE PATHS** - no relative paths or `~` - Set `ACF_PATH` to your ACF installation directory - Set `WORKSPACE_ROOT` to your project workspace - Ensure `bin/agentic-control-framework-mcp` is executable: `chmod +x bin/agentic-control-framework-mcp` - **❌ DO NOT USE** the `node` + `args` pattern - it fails in Claude Desktop **Alternative: Via mcp-proxy (Remote/Cloud)**: ```json { "mcpServers": { "acf-proxy": { "url": "http://localhost:8080/sse", "transport": "sse" } } } ``` **For Production Deployment**: ```json { "mcpServers": { "acf-production": { "url": "https://your-deployment.com/sse", "transport": "sse", "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" } } } } ``` ### 2. **Cursor** (IDE) **Location**: - **macOS**: `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` or via settings - **Windows**: `%APPDATA%\Cursor\User\globalStorage\state.vscdb` **Method 1: Via MCP Settings (Recommended)** 1. Open Cursor → Go to MCP settings in the UI 2. Click "Add Custom Server" or use deep link integration 3. Configure ACF server: - **Name**: `acf-local` - **URL**: `http://localhost:8080/sse` - **Transport**: `sse` **Method 2: Via Deep Link (For Developers)** Use Cursor's deep link system for easier integration: ```bash # Open Cursor with ACF MCP server configuration open "cursor://anysphere.cursor-deeplink/mcp/install?name=acf-local&url=http://localhost:8080/sse&transport=sse" ``` **Method 3: Manual Configuration (Legacy)** 1. Create configuration file: `~/.cursor/mcp_config.json` 2. Add server configuration: ```json { "mcpServers": { "acf-local": { "url": "http://localhost:8080/sse", "transport": "sse", "protocolVersion": "2025-06-18" } } } ``` **Note**: Cursor now supports MCP servers through their official UI. Check Settings → Tools → MCP for the latest configuration options. ### 3. **Cline (VS Code Extension)** **Location**: VS Code settings or extension configuration **Method 1: Via VS Code Settings** 1. Open VS Code → Settings → Extensions → Cline 2. Edit `settings.json`: ```json { "cline.mcpServers": { "acf-local": { "url": "http://localhost:8080/sse", "transport": "sse" } } } ``` **Method 2: Via Cline Configuration** In your workspace, create `.vscode/settings.json`: ```json { "cline.mcp": { "servers": { "acf-local": { "url": "http://localhost:8080/sse", "transport": "sse" } } } } ``` ### 4. **Continue (VS Code Extension)** **Configuration**: Add to VS Code `settings.json` ```json { "continue.mcpServers": [ { "name": "acf-local", "url": "http://localhost:8080/sse", "transport": "sse" } ] } ``` ### 5. **Windsurf** (Codeium IDE) **Location**: Windsurf settings **Configuration**: ```json { "mcp": { "servers": { "acf-local": { "url": "http://localhost:8080/sse", "transport": "sse" } } } } ``` ### 6. **Generic MCP Client** For any MCP-compatible client: ```json { "server": { "url": "http://localhost:8080/sse", "transport": "sse", "protocol": "2025-06-18" } } ``` ## 🔧 Configuration Options ### Basic Configuration ```json { "url": "http://localhost:8080/sse", "transport": "sse" } ``` ### With Authentication (Production) ```json { "url": "https://your-deployment.com/sse", "transport": "sse", "headers": { "Authorization": "Bearer your-token-here" } } ``` ### With Custom Timeout ```json { "url": "http://localhost:8080/sse", "transport": "sse", "timeout": 30000 } ``` ### With CORS Headers (if needed) ```json { "url": "http://localhost:8080/sse", "transport": "sse", "headers": { "Origin": "http://localhost:3000" } } ``` ## 🧪 Testing Your Configuration ### 1. **Verify Server is Running** ```bash curl -s http://localhost:8080/health # Should return: OK ``` ### 2. **Test SSE Endpoint** ```bash curl -H "Accept: text/event-stream" http://localhost:8080/sse # Should show SSE connection ``` ### 3. **Test MCP Initialize** ```bash curl -X POST http://localhost:8080/stream \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "test-client", "version": "1.0.0" } } }' ``` ## 🔍 Troubleshooting ### Common Issues **1. Connection Refused** - ✅ Check if mcp-proxy is running: `ps aux | grep mcp-proxy` - ✅ Verify port 8080 is listening: `lsof -i :8080` - ✅ Check firewall settings **2. SSE Not Working** - ✅ Ensure client supports SSE transport - ✅ Check Accept headers in client requests - ✅ Verify URL is `http://localhost:8080/sse` (not `/stream`) **3. Authentication Errors** - ✅ Check token format: `Bearer your-token` - ✅ Verify token is valid and not expired - ✅ Check server logs for auth errors **4. Client Can't Find Server** - ✅ Check URL is correct (`/sse` for SSE, `/stream` for HTTP) - ✅ Verify client MCP configuration syntax - ✅ Restart client after config changes ### Debug Commands ```bash # Check if server is running curl -v http://localhost:8080/health # Test SSE connection curl -v -H "Accept: text/event-stream" http://localhost:8080/sse # Check server logs tail -f /path/to/mcp-proxy.log ``` ## 🚀 Production Deployment For production use, replace `localhost:8080` with your deployed URL: ```json { "mcpServers": { "acf-production": { "url": "https://your-app.run.app/sse", "transport": "sse", "headers": { "Authorization": "Bearer prod-token-here" } } } } ``` ## ✅ Verification After configuration, your MCP client should: 1. ✅ **Connect**: Show ACF server as connected 2. ✅ **List Tools**: Display all 64+ ACF tools 3. ✅ **Execute**: Run ACF commands successfully 4. ✅ **Stream**: Receive real-time responses ### 🧪 Test Your Configuration Run these commands to verify your setup: ```bash # 1. Verify server is running curl -s http://localhost:8080/health # 2. Test SSE endpoint curl -s http://localhost:8080/sse # 3. Run comprehensive test ./test/run-all-tests.sh ``` **Expected Results:** - Health endpoint returns `{"status":"ok"}` - SSE endpoint provides session information - All tests pass with 100% success rate ## 🎯 Next Steps 1. **Test with your preferred client** 2. **Deploy to production** using `./quick-deploy.sh` 3. **Add authentication** for commercial use 4. **Monitor usage** via metrics endpoint Your ACF server is now accessible via HTTP/SSE to any MCP client! 🎉