MCP Servers in Plugins

Plugins expose MCP servers to the agent by including a .mcp.json file in the plugin root.

How It Works

1. Each plugin with a .mcp.json contributes its mcpServers entries
2. Athena merges all entries into a temp file at /tmp/athena-mcp-<PID>.json
3. The temp file is passed to the agent harness at startup
4. The harness manages the MCP server processes — Athena does not start or monitor them

.mcp.json Format

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./server/index.js"],
      "env": {
        "MY_VAR": "value"
      }
    }
  }
}

Follows the standard MCP config format.

Name Uniqueness

MCP server names must be unique across all loaded plugins. A collision causes a startup error:

MCP server name collision: "my-server" is defined by multiple plugins.
Each MCP server must have a unique name across all plugins.

Skills with MCP Access

When a plugin has both skills and an MCP server, its skills run with the MCP server's tools available. This is how e2e-test-builder skills get access to agent-web-interface browser automation tools.

agent-web-interface

agent-web-interface is a browser automation MCP server built for LLM agents. Instead of exposing raw DOMs or full accessibility trees, it produces semantic page snapshots — compact, structured representations focused on user-visible intent, optimized for LLM recall and reasoning.

Key Features

• Pages reduced to semantic regions and actionable elements
• Actions resolved against stable semantic identifiers (not fragile CSS selectors)
• Snapshots are deterministic and low-entropy across layout shifts and DOM churn
• ~19% fewer tokens and ~33% faster task completion vs. Playwright MCP (benchmarks are task-dependent)

Configuration

{
  "mcpServers": {
    "agent-web-interface": {
      "command": "npx",
      "args": ["agent-web-interface@latest"],
      "env": {
        "AWI_CDP_URL": "http://localhost:9222"
      }
    }
  }
}

CLI Arguments

The server accepts transport-level arguments only. Browser configuration is per-session via the navigate tool.

Browser Session Configuration

The browser launches automatically on the first tool call. The navigate tool accepts optional parameters:

Using Your Existing Chrome Profile (Chrome 144+)

1. Navigate to chrome://inspect/#remote-debugging in Chrome
2. Enable remote debugging and allow the connection
3. Use the auto_connect parameter on the navigate tool, or set AWI_CDP_URL

Environment Variables