Overview

Debugg.AI MCP Server implements the Model Context Protocol (MCP) as a lightweight, self-hosted service that coordinates AI-managed end-to-end tests using remote browsing test agents. It sits between control logic (for example, an LLM-based test director) and distributed test runners (headless browsers, remote drivers), mediating sessions, state, and message routing so you can orchestrate multi-step scenarios without building a bespoke coordination layer.

The server is useful when you need reproducible, repeatable end-to-end tests driven by code generation or LLM workflows. Instead of wiring low-level browser automation and inter-process messaging yourself, MCP provides session management, agent registration, simple APIs/WebSocket streams, and a small configuration surface to plug remote browsing agents into a zero-config testing pipeline.

Features

Zero-config session orchestration for AI-managed tests.
Remote agent registration and health monitoring (headless Chrome and other browser agents).
WebSocket and HTTP APIs for session messaging and streaming updates.
Simple configuration via environment variables or a JSON file.
Lightweight, self-hosted; integrates easily into CI/CD and local development.
Designed to work with code-generation platforms that produce step-by-step test plans.

Installation / Configuration

You can run the MCP server from source or inside Docker. The examples below show common workflows.

Clone the repository:

git clone https://github.com/debugg-ai/debugg-ai-mcp.git
cd debugg-ai-mcp

Run locally (example with Node.js):

# install dependencies (if Node-based)
npm install

# start the server (example script)
npm run start

Run with Docker:

# build
docker build -t debuggai/mcp .

# run with environment variables
docker run -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e MCP_LOG_LEVEL=info \
  -e MCP_AGENT_AUTH_TOKEN=secret-token \
  debuggai/mcp:latest

Example docker-compose:

version: "3.8"
services:
  mcp:
    image: debuggai/mcp:latest
    ports:
      - "8080:8080"
    environment:
      MCP_PORT: "8080"
      MCP_LOG_LEVEL: "info"
      MCP_AGENT_AUTH_TOKEN: "secret-token"
  # optional: sample agent service can be added here

Configuration via JSON file (mcp.config.json):

{
  "port": 8080,
  "logLevel": "info",
  "agentAuthToken": "secret-token",
  "allowedOrigins": ["http://localhost:3000"],
  "sessionIdleTimeout": 300000
}

Environment variables (common keys):

MCP_PORT — HTTP/WebSocket port (default 8080)
MCP_LOG_LEVEL — log verbosity (info, debug, warn)
MCP_AGENT_AUTH_TOKEN — shared token for agent registration
MCP_CONFIG_FILE — path to JSON config file

Available Resources

The MCP server exposes a small HTTP/WS surface to manage sessions and agents. Exact paths may vary by release; common endpoints include:

GET /health — health check
POST /agents/register — register a remote browsing agent
GET /agents — list known agents and status
POST /sessions — create a new MCP session
GET /sessions/{id} — session metadata
WS /sessions/{id}/stream — WebSocket for streaming session events and messages

Example agent registration payload:

{
  "agentId": "agent-01",
  "capabilities": ["chrome-headless", "screenshots"],
  "baseUrl": "https://agent.example.com",
  "authToken": "agent-specific-token"
}

API usage example (create a session):

curl -X POST http://localhost:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{"sessionName":"example-test","modelContext":{"type":"mcp","meta":{}}}'

WebSocket example (connect to a session stream):

# using wscat
wscat -c "ws://localhost:8080/sessions/<SESSION_ID>/stream"

Use Cases

AI-directed end-to-end testing for code-generation platforms:
- Use an LLM to translate a spec into a sequence of browser actions. The LLM interacts with MCP sessions to send instructions and verify results using remote browser agents.
Cross-browser regression testing:
- Register multiple agents (Chrome, Firefox, headless) and let a test director assign scenarios to each agent to validate UI behavior across environments.
CI integration with zero configuration:
- Start the MCP server as a short-lived service in CI, spin up ephemeral agents, run LLM-driven tests, and collect logs/screenshots without modifying test authoring.
Developer sandboxing:
- Developers can run a local MCP instance and connect a headless browser agent to reproduce end-to-end flows that a code-generation tool or QA assistant has produced.

Example Flow

Start MCP server (Docker or local).
Register a remote browsing agent (agent posts its metadata and a callback URL).
Create a session via POST /sessions.
Connect to session stream with a WebSocket to receive progress and agent messages.
The test director (LLM or orchestrator) sends step messages to the session; MCP routes them to the appropriate agent(s).
Agents report results, screenshots, and structured logs back to MCP for collection and analysis.

Where to find the project

Source code, issues, and releases are on GitHub: https://github.com/debugg-ai/debugg-ai-mcp

For platform-specific examples, agent implementations, and API reference consult the repository README and examples directory.

Debugg.AI MCP Server: AI-Managed End-to-End Testing