Playwright MCP - the testing tools layer for AI clients

1What is MCP - the protocol

A standardised way for an AI client to ask "what tools do you have?" and then call them. Think of it as the USB-C of LLM tool use - one shape, any host, any device.

MCP has three primitives. Tools are functions the client can call (screenshot, run_spec). Resources are readable blobs the client can fetch (a trace.zip, a generated HTML report). Prompts are reusable templates the server suggests to the client (e.g. "summarise this failing trace"). On top of that the server can sample - ask the client's model a follow-up question - which is how MCP servers stay model-agnostic.

Why it matters for testing: before MCP, every AI agent needed bespoke glue to talk to Playwright. With MCP, you write the Playwright server once, and any MCP-aware client - Claude Desktop, Cursor, VS Code with Cline - can use it without changes. That's the same value proposition we got from LSP for editors, but for AI agents.

2Playwright as an MCP server

A small Node process that imports @playwright/test internally and exposes its actions as MCP tools. The AI client sends JSON-RPC, the server runs the action, returns the result.

The server boots a real Chromium / Firefox / WebKit (headless or headed), holds one or more BrowserContext instances, and routes tool calls into the Playwright API. The client doesn't see DOM directly - it asks the server for a page snapshot (usually the accessibility tree) and uses that as context for its next decision. That snapshot is also how the model selects elements - by an ARIA ref the server assigned, not by CSS.

A second class of tools wraps your existing npx playwright commands - run_spec(path), show_report(), show_trace(zip). The model kicks off a real test run as if it were the developer at the terminal, then reads the result back through a resources/read call.

// Fresh TTA snippet, not copied from upstream. Pseudo-MCP server.
server.tool('browser_click', {
  description: 'Click an element by ARIA ref returned from browser_snapshot.',
  inputSchema: { ref: { type: 'string' } },
}, async ({ ref }) => {
  const locator = page.locator(`[aria-ref="${ref}"]`);
  await locator.click();
  return { ok: true, url: page.url() };
});

3AI clients consuming MCP

Claude Desktop, Cursor, Cline (VS Code), Continue, Zed AI, Windsurf. Same client API surface - configure the server once in JSON, the model gets the new tools at next chat.

Each client has a config file - typically JSON - listing the MCP servers it should start at launch. The client reads tools/list on connect, attaches the tool schemas to its system prompt, and from then on the model can call any tool by name. The client itself handles permission UI ("Allow Playwright server to call browser_click?") and rate-limiting.

{
  "mcpServers": {
    "tta-playwright": {
      "command": "npx",
      "args": ["-y", "@your-org/tta-playwright-mcp"],
      "env": { "TTA_HEADLESS": "true" }
    }
  }
}

4MCP tools - listing, calling, reading resources

Four core methods. tools/list returns the schema. tools/call invokes one. resources/list + resources/read stream readable artefacts back.

tools/list is what the client calls on connect - the server returns an array of {name, description, inputSchema} objects. tools/call takes {name, arguments} and returns a typed result. Long-running tools (a 90-second test run, say) emit notifications/progress so the client UI can render a spinner. The client can also cancel mid-flight via notifications/cancelled.

resources/read is how you ship artefacts back. A test run produces a trace.zip + an HTML report; both are exposed as resources with URIs like tta-pw://runs/2026-05-21-181203/trace.zip. The client can render the HTML inline or offer a "save" button.

5Stdio vs SSE transport

MCP messages travel over one of two transports. Stdio is for local servers spawned by the client. Server-Sent Events (SSE) is for remote / hosted servers.

Stdio is the default. The client spawns the server as a child process, talks JSON-RPC over stdin / stdout. Zero networking, zero auth, simplest possible setup. This is what you'll use on your dev laptop 95% of the time, including for a Playwright server.

SSE matters when the server is shared - a hosted Playwright MCP that ten developers point at, or a centralised Playwright runner inside a corporate network. The client opens an HTTP connection, the server streams messages back via text/event-stream. Auth + TLS become your problem; on the upside, the heavy browser process lives on a beefy CI machine, not on the developer's laptop.

6Local vs remote MCP server - security boundaries

A local stdio server can read anything the user can read. A remote SSE server reads only what its account allows. Plan the boundary before you connect.

1. Local stdio. The server runs as you, with your credentials, on your machine. It can read ~/.aws/credentials if you let it. Treat it like a CLI tool you installed - same trust model.
2. Remote SSE. The server runs elsewhere as a service account. Bound by whatever IAM the service has. Add bearer auth, TLS, rate limits, audit logs.
3. Tool allow-list. Even local servers should let you disable specific tools per workspace. "On the production support workspace, no browser_evaluate tool" is a sensible rule.
4. Filesystem reach. If the server can read or write files, scope it to a project root and reject everything else. Path-traversal is the classic MCP attack.
5. Network reach. A Playwright server can navigate anywhere. Allow-list domains for production-impacting flows.

7STLC + MCP - wiring AI into the Software Testing Life Cycle

Design -> generate -> execute -> report. MCP gives you one consistent tool surface across the whole loop, instead of bespoke integrations at each phase.

A mature TTA team can run all four STLC phases through MCP. Design: a "test-design" MCP server reads JIRA tickets via the Atlassian MCP server and produces a markdown test plan. Generate: the Playwright MCP server uses the plan as input and emits real spec files. Execute: same server runs npx playwright test and streams progress. Report: a reporter MCP exposes the trace + HTML as resources, the AI client summarises failures and proposes fixes. Loop closes by opening a PR via the GitHub MCP server.

The win is composability. You're not picking one AI tool - you're picking one protocol and assembling tools per phase. The same tool surface our existing TTA AI Chat demo and functions/api/chat.js proxy expose can be re-wrapped as MCP tools when we ship the full STLC story.

Common MCP servers + clients

Reference table you can hand to a new joiner. Not exhaustive - the ecosystem moves fast.

Diagrams - MCP message flow and STLC pipeline

Two mermaid diagrams. First: the client-server-tool sequence for one Playwright action. Second: how MCP servers compose across the full STLC.

sequenceDiagram
  autonumber
  participant U as User
  participant C as MCP Client (Claude Desktop)
  participant M as LLM
  participant S as Playwright MCP Server
  participant B as Browser

  U->>C: "Add the highlighted SKU to the cart"
  C->>M: prompt + tools/list summary
  M-->>C: call browser_snapshot
  C->>S: tools/call browser_snapshot
  S->>B: page.accessibility.snapshot()
  B-->>S: ARIA tree with refs
  S-->>C: snapshot result
  C->>M: snapshot result attached
  M-->>C: call browser_click ref=node-2841
  C->>S: tools/call browser_click {ref:"node-2841"}
  S->>B: locator(`[aria-ref="node-2841"]`).click()
  B-->>S: ok
  S-->>C: { ok: true, url: "/cart" }
  C-->>U: "Done. Cart now has 1 item."
            

flowchart LR
  subgraph CLIENT[MCP Client]
    M[LLM]
  end

  M -- tools/call --> A[Atlassian MCP
read JIRA ticket]
  M -- tools/call --> P[Playwright MCP
generate + run spec]
  M -- tools/call --> R[Reporter MCP
read trace + HTML report]
  M -- tools/call --> G[GitHub MCP
open PR with the new spec]

  A -- ticket text --> M
  P -- run id + status --> M
  R -- summary + failures --> M
  G -- pr url --> M

  classDef srv fill:#d1fae5,stroke:#16a34a,color:#111
  classDef llm fill:#ede9fe,stroke:#8b5cf6,color:#111
  class A,P,R,G srv
  class M llm