Skip to main content

📶 Streamable HTTP Mode

Streamable HTTP allows the server to run behind gateways and lets clients download generated artifacts through signed URLs.

Enabling​

npx @aakashh242/playwright-mcp-server --http --port 8000 --path /mcp --host-name your.host

Or Docker:

docker run --rm -p 8000:8000 ghcr.io/aakashh242/mcp-playwright:latest \
  node dist/index.js --http --listen 0.0.0.0 --host-name your.host

Or with Docker Compose (recommended for production HTTP):

docker compose up -d

The provided docker-compose.yml exposes http://localhost:8000/mcp, binds to 0.0.0.0:8000, persists data to ./data → /app/data, and runs streamable HTTP mode by default.

docker-compose.yml
# Recommended production deployment (Streamable HTTP mode)
services:
  playwright-mcp:
    build:
      context: .
      dockerfile: Dockerfile
    image: ghcr.io/aakashh242/mcp-playwright:latest
    container_name: playwright-mcp-server
    stdin_open: true
    tty: true
    command: ["--http", "--listen", "0.0.0.0", "--port", "8000", "--path", "/mcp", "--host-name", "<your-dockerhost-host-name>"]
    ports:
      - "8000:8000"
    environment:
      - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
    volumes:
      - ./data/app-data:/app/data
      - ./data/resource-data:/data

Remote resources​

When HTTP mode is enabled, tools that create files register session-scoped resources and return download URLs:

  • playwright_screenshot
  • playwright_save_as_pdf
  • Codegen outputs (end_codegen_session)
  • playwright_console_logs

Resources live under /resources/{sessionId}/{resourceId}/{filename} and expire after the configured TTL (default 600 seconds).

File uploads​

  1. Call construct_upload_url to get a session-specific HTTP endpoint (e.g. http://host:8000/mcp/uploads/{sessionId}).
  2. The MCP client uploads the file via multipart/form-data (field file). CLI permissions are required (curl or Invoke-WebRequest).
  3. The server responds with resourceUri such as mcp-uploads://{sessionId}/{id}.
  4. Call playwright_upload_file with uploadResourceUri. If no URI/path is provided the tool returns an error instructing the agent to upload first.

This loop prevents large base64 payloads in tool arguments and keeps uploads isolated per session.