[Docs] Standalone MCP example port 8931 conflicts with other common local services

[steve02081504]

Summary

The standalone server examples use port 8931 throughout the docs:

npx @playwright/mcp@latest --port 8931

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

--port has no default (omitting it uses stdio), so 8931 is only a documentation example. The problem is that the examples are copied verbatim: users end up binding 8931, and that port is already a long-standing default for local services in some developer communities, where changing it is effectively not an option. When the MCP server and such a service run on the same machine, one of them fails to bind (EADDRINUSE), which is a confusing first-run experience caused purely by the doc example.

Suggestion

Make it clear that the port is arbitrary, for example by any of:

• using a placeholder such as --port <port> / http://localhost:<port>/mcp,
• choosing a less contended example port, and/or
• adding a sentence that any free port works and the value shown is only an example.

Affected locations

• docs/src/getting-started-mcp.md (and the localized getting-started pages)
• the published docs: https://playwright.dev/docs/getting-started-mcp and the MCP configuration pages
• microsoft/playwright-mcp README, including the Docker example (-p 8931:8931 ... --port 8931)

[dcrousso]

where changing it is effectively not an option

wow really? can you please share more info about the local services that do not allow changing their port?

[steve02081504]

can you please share more info about the local services that do not allow changing their port?

I'd rather not link the project, since I don't want this to come off as advertising. But let me correct my wording: the service can be moved to another port. The real issue is that the other programs/pages that integrate with it assume 8931, and some of them don't expose any configuration for that — so changing the port makes the whole setup painful to use in practice, effectively pinning it.

[dcrousso]

i think no matter what port we pick we'll potentially run into this same problem with some other service