Connect Your Coding Agent to Safari and Verify Browser Access

Safari MCP server setup uses the native safaridriver --mcp command: enable Safari’s developer permissions, register the driver with your MCP client, then verify that the agent can inspect a test page. Safari 27.0 includes the server, and WebKit also documents support in Safari Technology Preview 247. You do not need a separate third-party MCP package for this integration. The driver path must match the browser whose permissions you enabled. (WebKit’s setup guide)

For a publishing site, the useful result is an agent that can inspect the rendered article, screenshots, console output and recorded network requests—not merely read source files. That helps investigate broken layouts, failed resources and newsletter-form states. Establish that access on a nonsensitive test page before asking the agent to change code or interact with a live publishing workflow.

Choose your Safari edition and MCP client; use the matching registration command.

Enable Permissions in the Browser You Will Connect

On the Mac where your agent will run, install Safari 27 or a supported Safari Technology Preview release. Open the browser you intend to connect, then follow this settings sequence:

1. Open Safari → Settings → Advanced.
2. Enable Show features for web developers.
3. Open the Developer settings pane.
4. Enable Allow remote automation and external agents.

The Safari 27 release notes confirm both the permission and the prerequisite for making the Developer pane visible. If you cannot find Developer settings, return to Advanced rather than looking for an MCP-specific extension or package. (Safari 27.0 instructions)

For Technology Preview, make these changes in Technology Preview’s own settings. Enabling access in regular Safari while configuring the Technology Preview driver leaves the setup targeting a different browser from the one you prepared.

Keep the browser choice consistent throughout the setup: settings, executable path and verification page should all refer to the intended edition. The MCP server name is only a client-side label; naming a server safari-mcp-stp does not itself select Technology Preview.

Register the Matching Driver With Your Client

Registration tells the MCP client which executable to run and which argument starts its MCP server. It does not demonstrate that browser inspection works. Treat command registration and the later smoke test as separate checks.

Claude Code and Codex Use the Same Driver Argument

For Claude Code with Safari 27, run:

claude mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp

For Codex with Safari 27, run:

codex mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp

The client command differs, but the executable and --mcp argument are identical. Copy the whole command, including the separator before the executable and the MCP argument after it. A configuration that points at safaridriver without --mcp is not the configuration documented for this server.

WebKit supplies these registration commands and a configuration example for other MCP-compatible clients. Use the syntax your installed client supports; do not assume that every MCP client accepts the Claude Code or Codex command-line interface. (Official commands and configuration)

Other Clients Need the Executable and Argument in Their Configuration

WebKit’s JSON configuration example is:

{"mcpServers":{"safari-mcp":{"command":"/usr/bin/safaridriver","args":["--mcp"]}}}

WebKit describes this as an entry for mcp.json or config.json. Use your client’s configuration location and supported schema rather than treating either filename as universal. The draft provides no single configuration directory that applies to every client.

Merge the Safari entry into an existing configuration instead of replacing unrelated servers. In the example, safari-mcp identifies the server entry, command selects the executable, and args passes --mcp to it. Preserve any surrounding structure your client requires.

If you use the command-line registration method, do not also edit a configuration blindly just to repeat the same setup. First inspect the client’s MCP status and determine whether the intended server is already registered. The verification target is a working Safari tool connection, not multiple copies of the same server entry.

Technology Preview Requires Its Bundled Driver

For Claude Code with Safari Technology Preview, run:

claude mcp add safari-mcp-stp -- "/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver" --mcp

For Codex with Safari Technology Preview, run:

codex mcp add safari-mcp-stp -- "/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver" --mcp

For a JSON-based client, use the same configuration structure, change the server name to safari-mcp-stp, and set command to /Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver. Keep args as ["--mcp"].

The quotes around the command-line path keep the application name’s spaces within a single executable path. In JSON, the complete path belongs inside the command string; the MCP flag remains a separate argument. WebKit notes that the server name is arbitrary: the executable path selects the browser installation.

Verify Browser Access Before Requesting Fixes

Start with a public test page or a local preview containing no sensitive data. Give the agent an explicit URL so the test has an identifiable target. Do not begin with an authenticated editorial dashboard, unpublished article or page containing credentials.

Use this bounded smoke-test prompt:

Use Safari MCP to open the test article URL I provide. Report its URL, title and loading state, capture a screenshot, and list recorded console errors and failed network requests. Say if no logs or requests were recorded rather than assuming the page is error-free. Do not submit forms or modify files.

The server exposes list_tabs, page_info, screenshot, browser_console_messages and list_network_requests. These provide concrete evidence to inspect instead of relying on the agent’s statement that it is connected. The server also offers JavaScript evaluation and DOM interactions, so its capabilities extend beyond passive observation. (Documented tools)

Use the returned URL and title to confirm that the agent inspected the intended page. Then compare the screenshot with that target. A response about a different tab, a previous page or an unspecified URL does not establish that the requested article was checked.

Separate connection success from page quality. A screenshot and page information can demonstrate useful browser access even when no console messages or network requests are returned. They do not establish that the page has no errors.

Console output is buffered, and the network tools report recorded requests. Ask the agent to distinguish “no recorded requests” from “recorded requests with no failures.” If the evidence is absent, the report should say so rather than convert absence into a passing result.

Troubleshoot the Dependency That Failed

Check the setup in the order that matches the failure. Changing the registration command will not reveal a hidden Developer pane, and changing a server label will not switch the configured executable.

Symptom	First Check	Correction
No Developer pane	Advanced settings	Enable developer features
Wrong browser targeted	Driver path	Select the intended edition
No Safari tools	Client MCP status	Confirm registration and --mcp
Automation unavailable	Browser permissions	Enable external-agent access

When tools are missing, inspect the client’s MCP status before interpreting the page itself. The immediate question is whether the client has made the Safari server available, not whether the website is healthy.

When the wrong browser is targeted, compare the full configured path with the two documented paths above. Regular Safari uses /usr/bin/safaridriver; Technology Preview uses its application-bundled driver. Check permissions in the same browser after correcting the path.

When tools are available but the report contains no captured evidence, repeat the bounded test and require the agent to identify what it actually observed. Do not escalate straight to code changes on the assumption that an empty console response identifies or rules out a website defect.

The draft does not provide a universal client status command, restart sequence or error-code map. Use your client’s own status interface rather than borrowing instructions from a different client and presenting them as interchangeable.

Keep the First Publishing Check to One Template

After the smoke test succeeds, choose one article template and two specified viewport widths. Supply the exact page and widths in the request; “check mobile and desktop” leaves the intended rendering conditions unclear.

Ask the agent to inspect headline wrapping, image dimensions, embed overflow, console errors and failed resources. Require observations with selectors or screenshots before approving changes. This turns a vague request to “fix the page” into a reviewable account of where the rendered output differs from your intended layout.

For an overflowing embed, the useful evidence is the affected element and a screenshot showing the overflow at the requested width. For headline wrapping, it is the rendering at that width—not a judgment made from the stylesheet alone. For failed resources, require the recorded request evidence rather than an inference from an empty image area.

Newsletter-form states can be inspected within this boundary, but submitting the form is a separate action. Keep the initial task to observation. If testing a submission becomes necessary, approve that action explicitly rather than letting it follow automatically from a layout investigation.

Separate findings from proposed edits in the agent’s response. Review the evidence first, then decide whether to authorize a change. If a change is made, repeat the original page and viewport checks and follow a post-remediation verification workflow. Keeping the original conditions makes the before-and-after comparison meaningful.

Treat Browser Findings as Evidence, Not Certification

WebKit describes checks for common accessibility issues and access to navigation and resource timing. Those capabilities can support an investigation, but the agent’s findings still need review. A bounded Safari check is not proof of accessibility compliance or real-user performance. (Supported use cases)

Keep the report tied to its actual scope: the page inspected, the viewport conditions supplied, the screenshot captured and the logs or requests recorded. Do not let a successful check of one article template become a claim that every page on the publishing site passes.

The setup instructions provide no universal performance threshold, accessibility score or completion time. Do not add one to the acceptance criteria as though it came from the Safari MCP documentation. Define any broader publishing acceptance criteria separately from this connection test.

Keep Sensitive Data Out of the Initial Session

Local server execution does not mean all captured data stays local. WebKit says the server makes no network calls of its own and does not access personal Safari information such as AutoFill. However, page content, screenshots and console logs go to your agent, whose model and data policies determine what happens next. (WebKit’s data-handling explanation)

Use a trusted agent and keep credentials and unpublished material out of initial tests. A public article or nonsensitive preview is enough to establish the browser connection without exposing an editorial workspace. Review the proposed target before giving the agent access to a page whose content should not leave that environment.

Require approval before form submissions or publishing actions, using client-side tool approval controls where available. The smoke-test prompt’s restriction is an instruction to the agent, not a technical permission boundary. Keep broader interaction privileges separate from the evidence-gathering task, and expand the task only after the browser connection and first report are verified.