← Back to Documentation

Running Multiple AI Assistants with Kapture

Kapture enables multiple AI assistants to control browser tabs simultaneously through a single server instance. This guide explains how to set up and manage multi-assistant workflows effectively.

Understanding the Architecture

Kapture uses a hybrid architecture that supports both stdio and WebSocket connections:

Key Concepts

1. Single Server Instance: Only one Kapture server runs at a time on port 61822
2. Bridge Mode: Translates between stdio (used by Claude Desktop) and WebSocket
3. Direct WebSocket: Other MCP clients connect directly via WebSocket
4. Shared Browser Access: All connected clients can control any connected browser tab

Setup Guide

Step 1: Install the Chrome Extension

1. Download the Kapture extension from the releases page
2. Open Chrome and navigate to chrome://extensions/
3. Enable "Developer mode"
4. Click "Load unpacked" and select the extension folder

Step 2: Configure Your Primary AI Client (Claude Desktop)

Claude Desktop will automatically start and manage the server:

1. Open Claude Desktop's 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
2. Add the Kapture configuration:

   {
     "mcpServers": {
       "kapture": {
         "command": "npx",
         "args": ["kapture-mcp-server", "bridge"]
       }
     }
   }

3. Restart Claude Desktop - the server will start automatically

Step 3: Add Additional AI Clients

Once the server is running (started by Claude Desktop), other clients can connect:

Cline (VS Code Extension)

Add to your VS Code settings:

{
  "cline.mcpServers": {
    "kapture": {
      "transport": "websocket",
      "url": "ws://localhost:61822/mcp"
    }
  }
}

Other MCP-Compatible Clients

Any MCP client that supports WebSocket can connect to:

ws://localhost:61822/mcp

Step 4: Connect Browser Tabs

1. Open Chrome/Brave and navigate to any website
2. Open DevTools (F12 or Cmd+Option+I)
3. Click on the "Kapture" panel
4. The extension automatically connects to the server

Each tab shows:

• A unique Tab ID (e.g., tab_1234567890)
• Connection status (green = connected)
• Current URL

Verification and Monitoring

Check Server Status

Open in your browser:

http://localhost:61822/

You'll see:

{
  "mcpClients": ["Claude Desktop", "Cline"],
  "connectionCount": 2,
  "browserTabs": 3
}

Monitor in DevTools

The Kapture panel shows:

• Server connection status
• Command history
• Response details

View Server Logs

Server logs appear in the terminal where Claude Desktop was launched, showing:

• Client connections/disconnections
• Command execution
• Errors and warnings

Common Scenarios

Scenario 1: Research and Development

Setup: Claude Desktop + Cline

1. Claude Desktop researches API documentation:

   "Navigate to https://docs.api.com and find the authentication section"

2. Simultaneously, Cline implements the code:

   "Create an authentication module based on the research"

3. Both work independently without interference

Scenario 2: Automated Testing

Setup: Multiple Claude Desktop instances

1. Instance 1 writes test scenarios
2. Instance 2 executes tests in the browser
3. Instance 3 monitors console logs for errors

Scenario 3: Multi-Site Management

Setup: Claude Desktop + Custom MCP Client

1. Claude manages social media posts
2. Custom client handles form submissions
3. Each operates on different browser tabs

Important Considerations

Server Lifecycle

1. Automatic Start: When Claude Desktop launches with the bridge config
2. Smart Detection: If you run npx kapture-mcp-server manually and a server is already running, it will show the existing server info and exit
3. Graceful Shutdown: Server stops when all clients disconnect

Tab Management

• Tab Persistence: Tab IDs remain constant even if the page reloads
• Automatic Reconnection: Extensions reconnect automatically if the server restarts
• Independent Control: Each AI can control any tab, but commands are queued to prevent conflicts

Resource Limits

• Concurrent Clients: No hard limit, but performance may degrade with many clients
• Browser Tabs: Limited by Chrome's memory constraints
• Command Queue: Each tab processes commands sequentially

Troubleshooting

"Server already running" Error

WebSocket Connection Failed

1. Verify the server is running: http://localhost:61822/
2. Check firewall settings for port 61822
3. Ensure the WebSocket URL is exactly: ws://localhost:61822/mcp

Commands Not Working

1. Check the Kapture panel is active in DevTools
2. Verify the tab shows as connected (green status)
3. Look for errors in the DevTools console

Performance Issues

1. Close unused browser tabs
2. Limit concurrent automation operations
3. Add delays between rapid commands:

   await new Promise(resolve => setTimeout(resolve, 500));

Best Practices

1. Coordinate AI Tasks

• Assign specific responsibilities to each AI
• Use tab naming conventions (e.g., "research-1", "test-2")
• Implement handoff mechanisms between AIs

2. Handle Errors Gracefully

• Check command responses for success/failure
• Implement retry logic for failed operations
• Use try-catch blocks in your AI prompts

3. Optimize Performance

• Batch related operations
• Use CSS selectors efficiently
• Close tabs when done

4. Maintain Security

• Only run on localhost
• Don't expose port 61822 externally
• Monitor connected clients regularly

Advanced Usage

Custom Integration

Create your own MCP client:

import { WebSocketClientTransport } from '@modelcontextprotocol/sdk';

const transport = new WebSocketClientTransport(
  new URL('ws://localhost:61822/mcp')
);
await transport.connect();

Monitoring All Activity

Subscribe to notifications:

• kapture/tabs_changed - Tab connections/disconnections
• kapture/console_log - Real-time browser console output

Programmatic Control

Use the HTTP API for debugging:

# List all tabs
curl http://localhost:61822/tabs

# Get tab details
curl http://localhost:61822/tab/{tabId}

# View screenshot
curl http://localhost:61822/tab/{tabId}/screenshot/view > screenshot.png

Summary

Running multiple AI assistants with Kapture enables powerful automation workflows. The key is understanding that:

1. Claude Desktop manages the server lifecycle via the bridge command
2. Additional clients connect via WebSocket
3. All clients share access to browser tabs
4. Commands are queued per tab to prevent conflicts

Start simple with two clients, then expand as you become comfortable with the coordination patterns.