Skip to content

feat(playwright-mcp): the recorder fronts the browser's MCP port, serving its card there like any MCP server's (FD-4701) - #548

Merged
earakely-scale merged 5 commits into
mainfrom
edgararakelyan/fd-4701-playwright-mcp-serves-its-card-on-its
Nov 9, 2026
Merged

earakely-scale merged 5 commits into
mainfrom
edgararakelyan/fd-4701-playwright-mcp-serves-its-card-on-its

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

What and why

FD-4701, PR 1 of 2: the Playwright MCP browser serves its env card on its MCP port, the way every MCP server serves its card at its own address. Chromium alone already does, so once both stages serve this image, PR 2 can drop the deploy code's hardcoded recorder port (18766). M8.13 puts chromium alone in the website-browser slot, and with the hardcoded port the gateway would silently leave its card out.

Decisions (FD-4701, Nov 9): 1a, two PRs, so recording never breaks, and 2a, the recorder fronts the MCP port.

On decision 1a: the deploy code reaches prod with the hub's pin before prod's browser is promoted by hand (FD-4661). So this PR changes the image alone and keeps serving the card on 18766 too.

  • The recorder is the front of the MCP port (recorder.py):
    • It serves the card and computer-recording/v1 there.
    • Every other request (MCP's POSTs, its streamed answers, its session GETs and DELETEs) goes to @playwright/mcp as it came, with the body and answer streamed and hop-by-hop headers dropped.
    • A Playwright MCP that doesn't answer gets a 502 that names it.
    • The caller's Host goes on to Playwright MCP unchanged.
    • Playwright MCP's answer is closed whenever the response ends, streamed or not, so a caller that leaves before the first chunk doesn't leave the connection open. Repeated headers such as Set-Cookie stay separate.
    • The card comes first, the MCP port second. The card on 18766 is served at once, but the MCP port opens only once Playwright MCP listens behind it. The gateway's compose health check is a connect to the MCP port, so the browser counts as healthy, and the gateway discovers its tools, only once Playwright MCP can answer, as before.
    • One recorder serves both the front and the card on 18766.
    • The Starlette and uvicorn imports are now at the top of the module.
  • entrypoint.sh:
    • @playwright/mcp moves to 127.0.0.1:18767 behind the front.
    • The MCP server starts once the card is served on 18766.
    • The recorder is still restarted within a second whenever it exits. While it's down, the MCP port is down too, and the gateway's health check on that port shows it.
  • The deploy code is unchanged (card_port=PLAYWRIGHT_MCP_RECORDER_PORT). PR 2 removes it.

Also in this PR, two follow-ups to M5.5 (FD-4934) that #541 merged without:

  • The deploy checks the forward port. It loads a site through it, as a browser alone does, keeps the result in the deploy record, and fails naming the port if the port doesn't load the site.
  • One place decides which site a request through the port names. exchange gives the port's refusal, a 403 and a log line, so a request inside a site's tunnel that names another host is refused and logged too.

Rollout after merge

  • Dev: the browser promotes into dev on the framework pin bump, through the candidate and gate-website.
  • Prod: it's promoted through FD-4661: a prod store write, with Edgar's OK.
  • Then PR 2: the deploy reads the card at the MCP port, and 18766 leaves the deploy code and the image.

How it was tested

  • ruff check: clean.
  • Unit tests:
    • test_playwright_mcp_recorder.py:
      • the front serves the card and passes MCP through, with the query, body and session header both ways;
      • a down Playwright MCP gets a 502 naming it while the card still loads;
      • the card answers while the MCP port stays shut until Playwright MCP listens;
      • Host arrives unchanged;
      • an answer is closed when its caller leaves before the first chunk, under both of Starlette's disconnect paths;
      • an event stream's first event arrives before its answer ends (real servers);
      • the entrypoint's ports match the recorder's defaults.
    • The M5.5 follow-ups' tests are in test_computer_site_proxy.py and test_computer_sites.py.
    • tst/unit/env, tst/unit/providers and tst/unit/bundle: 5223 passed. The test_disk_recipe failure fails on macOS only.
  • VM e2e, agent-environments-admin:
    • New playwright_mcp_local_test.py (amd64 and arm64). The image is built for the machine and run alone, and the test checks that:

      • the card on the MCP port matches the card on 18766;
      • inside the container, the card answers first, and the first moment the MCP port accepts, an MCP initialize through it succeeds;
      • MCP lists and calls tools through the front;
      • a recording through the card on the MCP port films the page an agent opens, in one MCP session;
      • a killed recorder comes back with its front while @playwright/mcp keeps running.

      All 4 passed on both arches, on 1f6e191.

    • gateway_test.py::test_gateway_with_single_website_env (amd64; its images build for amd64 alone), extended to check that:

      • the browser is a child of the deploy's card, read at 18766 as deploys do today;
      • the same card is served on its MCP port inside the deployment;
      • a recording through the gateway films the page the agent opens.

      It passed, on 1f6e191.

    • Earlier fixes, all in 1f6e191:

      • My review of possible regressions found that the browser could count as healthy before Playwright MCP was ready, and that Host should pass through.
      • Greptile's first round found the answer leak on a caller that leaves early.
      • The first VM run showed that the recording test needs one MCP session throughout.
    • The M5.5 follow-ups passed the forward-port, CA trust and routed-site tests on amd64 and arm64 before this branch.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge; no new actionable issues remain.

Summary

The recorder now serves the browser card and recordings on the MCP port while forwarding browser calls to Playwright MCP.

  • The recorder serves the browser card and recording on its MCP port.
  • Deploy checks whether the browser’s forward port can load a site.
  • The forward port refuses off-site hosts requested inside a tunnel.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Client[Gateway or MCP client] --> Front[Recorder on MCP port]
  Front --> Card[Card and recordings]
  Front --> Backend[Playwright MCP on loopback]
  Legacy[Old card port] --> Card
  Backend --> Ready[Backend accepts connections]
  Ready --> Open[Recorder opens MCP port]
Loading

Reviews (6) · Last reviewed commit: "fix(playwright-mcp): the front opens the..." · Reviewed by Greptile

earakely-scale and others added 4 commits November 8, 2026 16:24
…oading a site through it

The install's checks now load the first site, over HTTPS where one is, through the forward port as a browser alone
loads it, as the session user. The deploy record keeps the result, and a port that doesn't load it fails the deploy,
naming it: a forward port that couldn't start, or a Python too old for its TLS tunnel, would otherwise pass the deploy
and fail only when the browser loads a page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e forward port names

exchange takes the forward port's refusal: on the port, a request naming no site is refused with 403 and logged rather
than answered 421, and the port no longer looks the site up again before handing a request over. A CONNECT still looks
its site up first, for the certificate its tunnel needs, and each request in a tunnel is now judged as the port judges
one, so a request in a site's tunnel naming another host is refused and logged too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ving its card there like any MCP server's (FD-4701)

The Playwright MCP image's recorder now listens on the MCP port: it serves the browser's card and computer-recording
there, as every MCP server serves its card at its own address, and passes every other request, streamed, to
@playwright/mcp, which moves to loopback 18767 behind it; a Playwright MCP that doesn't answer is a 502 naming it. The
recorder still serves the card on 18766, where deploys read it until a later change reads it at the MCP port once both
stages serve this image; the deploy code is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, as an agent does

An isolated Playwright MCP browser lives as long as its MCP session, so a recording of the page an agent opens is
filmed while one session stays open from the recording's start to its end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 9, 2026 01:07
…t MCP listens, passes Host through, and closes every answer

- The gateway's compose health check is a connect to each MCP server's MCP port. The recorder now serves the card on
  18766 at once but opens the MCP port only once Playwright MCP listens on its own port behind it, so the browser is
  healthy, and the gateway discovers its tools, only once Playwright MCP can answer, as before the front.
- The front passes the caller's Host on to Playwright MCP rather than its own loopback address.
- Playwright MCP's answer is closed when the response ends, streamed or not: a caller that leaves before the first
  chunk no longer leaves the connection to Playwright MCP open (Greptile).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 4e578c9 into main Nov 9, 2026
35 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/fd-4701-playwright-mcp-serves-its-card-on-its branch November 9, 2026 01:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant