> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/playwright-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol Overview

> Understanding MCP architecture and how Playwright MCP implements it

## What is MCP?

The Model Context Protocol (MCP) is a standardized protocol that enables Large Language Models (LLMs) to interact with external systems through a structured client-server architecture. MCP provides a consistent way for AI agents to access tools, resources, and capabilities beyond their training data.

Playwright MCP is a server implementation that exposes browser automation capabilities through the MCP protocol, allowing LLMs to interact with web pages using structured data rather than visual interpretation.

## Client-Server Architecture

Playwright MCP follows the standard MCP architecture pattern:

<CardGroup cols={2}>
  <Card title="MCP Client" icon="robot">
    The AI agent or IDE that sends requests to the server. Examples include Claude Desktop, VS Code, Cursor, and other MCP-compatible tools.
  </Card>

  <Card title="MCP Server" icon="server">
    The Playwright MCP server that receives requests, executes browser automation, and returns structured responses.
  </Card>
</CardGroup>

### Communication Flow

```mermaid theme={null}
sequenceDiagram
    participant Client as MCP Client (LLM)
    participant Server as Playwright MCP Server
    participant Browser as Browser Instance
    
    Client->>Server: Connect via STDIO/SSE
    Server->>Browser: Launch browser
    Client->>Server: Execute tool (e.g., browser_navigate)
    Server->>Browser: Perform action
    Browser-->>Server: Return state
    Server-->>Client: Return snapshot/result
```

### Transport Protocols

Playwright MCP supports multiple transport mechanisms:

**STDIO Transport** (Default)

The most common mode, where the server communicates with the client through standard input/output streams:

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
```

**SSE Transport** (HTTP Mode)

For remote deployments or when running the server separately:

```bash theme={null}
npx @playwright/mcp@latest --port 8931
```

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}
```

<Info>
  SSE (Server-Sent Events) transport is useful when running headed browsers on systems without displays or when the IDE worker process can't access the display.
</Info>

## Tool Capabilities System

Playwright MCP uses a capability-based system to control which tools are available. This allows you to enable only the features you need:

### Core Capabilities

**Core** (Default)

* Page navigation and snapshots
* Element interactions (click, type, hover)
* Form handling
* Dialog handling
* Keyboard and mouse actions

**PDF**

* PDF generation from web pages
* Requires `--caps=pdf` flag

**Vision**

* Coordinate-based interactions
* XY position clicking and dragging
* Requires `--caps=vision` flag

**DevTools**

* Browser developer tools access
* Advanced debugging capabilities
* Requires `--caps=devtools` flag

### Enabling Capabilities

Capabilities can be enabled via command-line arguments:

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--caps=vision,pdf"
      ]
    }
  }
}
```

Or through configuration:

```json theme={null}
{
  "capabilities": ["core", "pdf", "vision"]
}
```

<Note>
  By default, only core capabilities are enabled. This keeps the tool list minimal and reduces context window usage.
</Note>

## Configuration Options

Playwright MCP can be configured through:

1. **Command-line arguments** - Quick configuration via `--option=value`
2. **Environment variables** - System-level settings via `PLAYWRIGHT_MCP_*`
3. **Configuration file** - Comprehensive JSON configuration via `--config`

### Configuration File

For complex setups, use a JSON configuration file:

```typescript theme={null}
{
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    launchOptions?: playwright.LaunchOptions;
    contextOptions?: playwright.BrowserContextOptions;
    cdpEndpoint?: string;
    initPage?: string[];
    initScript?: string[];
  },
  
  server?: {
    port?: number;
    host?: string;
    allowedHosts?: string[];
  },
  
  capabilities?: ToolCapability[];
  
  timeouts?: {
    action?: number;  // Default: 5000ms
    navigation?: number;  // Default: 60000ms
  };
  
  snapshot?: {
    mode?: 'incremental' | 'full' | 'none';
  };
}
```

Load your configuration:

```bash theme={null}
npx @playwright/mcp@latest --config path/to/config.json
```

## Playwright MCP vs Playwright CLI

Playwright offers two approaches for AI-driven automation:

<CardGroup cols={2}>
  <Card title="Playwright CLI + SKILLS" icon="terminal">
    **Best for:** Coding agents working with large codebases

    * More token-efficient
    * Concise, purpose-built commands
    * Avoids loading large tool schemas
    * Better for high-throughput agents
  </Card>

  <Card title="Playwright MCP" icon="plug">
    **Best for:** Exploratory automation and persistent workflows

    * Rich page introspection
    * Persistent browser state
    * Structured accessibility data
    * Long-running autonomous workflows
  </Card>
</CardGroup>

<Tip>
  Choose CLI+SKILLS for coding agents that need to balance browser automation with code editing. Choose MCP for agents focused primarily on web interaction and exploration.
</Tip>

## Key Features

### Accessibility-First Approach

Playwright MCP uses the browser's accessibility tree instead of screenshots:

* **Faster** - No image processing required
* **Smaller** - Structured text data vs large image files
* **Deterministic** - Precise element references vs coordinate guessing
* **LLM-friendly** - No vision models needed

### Session Management

The server maintains browser state across multiple tool calls:

* Cookies and local storage persist
* Login sessions remain active
* Tab state preserved between operations
* Optional session recording and trace saving

### Security Boundaries

<Warning>
  Playwright MCP is **not** a security boundary. Follow [MCP Security Best Practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices) for production deployments.
</Warning>

Security features include:

* Origin allowlists and blocklists
* File access restrictions
* Service worker blocking
* Secrets management

## Next Steps

<CardGroup cols={2}>
  <Card title="Browser Automation" href="/concepts/browser-automation" icon="browser">
    Learn how Playwright manages browser contexts and sessions
  </Card>

  <Card title="Accessibility Snapshots" href="/concepts/accessibility-snapshots" icon="sitemap">
    Understand the structured snapshot format
  </Card>
</CardGroup>