Configuring Playwright MCP Like a Pro: Custom Headers, Cookies, and Smarter Agents

#devtools #webdev #softwaretesting #testautomation

How can you use Playwright MCP more effectively? How can you handle login scenarios? And how can you run Playwright MCP using your own browser profile? I hope this article helps answer questions like these :) Enjoy reading!

We use Playwright MCP, but are we really using it efficiently? Does it cover all our cases? After finding myself thinking things like “It doesn’t support this” or “I don’t think it can do that,” I realized the real issue was that I wasn’t configuring it correctly. With proper configuration, I discovered that it can actually solve all of my problems. In this article, we’ll look at how to use MCP more effectively through the configurations we can provide. (You can find even more details in the link.)

1. Config

With a config.json file you create, you can provide most of the settings you normally define inside playwright.config.ts.

Browser Args
Extra Http Header
ViewPort Size
Permissions
bypassing CSP, and similar configurations can all be added through this JSON file.

With these settings, MCP can also help you handle cases where the page behaves differently based on specific headers you pass. This allows the agents to analyze the page with those headers applied. An example config file would look like this:

{
  "browser": {
    "launchOptions": {
      "args": [
        "--ignore-certificate-errors"
      ]
    },
    "contextOptions": {
      "extraHTTPHeaders": {
        "test-header": "true"
      },
      "permissions": ["geolocation"],
      "bypassCSP": true
    }
  }
}

You also need to provide the location of this file inside your mcp.json, under the args section of the Playwright MCP configuration.

    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--config=path/to/playwright-mcp.config.json"
      ]
    }

2. Storage State

If you need cookies for a full and accurate page analysis, this part is exactly what you need. Anyone using Playwright is familiar with the concept of storage state, which saves your session’s cookie values and lets your tests run with them. The same applies to MCP by creating a JSON file and providing your cookie values there, you can run MCP with the session you want.

In my opinion, the biggest advantage is eliminating the login step. By supplying token-based cookies, you prevent MCP from wasting time on login flows and let it directly analyze authenticated pages. An example storage state JSON file might look like this:

{
  "cookies": [
    {
      "name": "testCookie",
      "value": "testValue123",
      "domain": ".testDomain.com",
      "path": "/",
      "expires": -1,
      "httpOnly": false,
      "secure": true,
      "sameSite": "Lax"
    },
    {
      "name": "token",
      "value": "testToken123.",
      "domain": ".testDomain.com",
      "path": "/",
      "expires": -1,
      "httpOnly": false,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "origins": []
}

You’ll need to provide this file in the same place inside your mcp.json as well, just like the previous configuration. It should look something like this:

    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--storage-state=path/to/storage-state.json"
      ]
    }

3. Init Script

If you want MCP to run certain actions at the very beginning, or if you want to show specific logs, alerts, or messages on the DOM under certain conditions, the init script will do exactly what you need. You can take the curl of a request and have it executed at the start of the MCP run or whenever the conditions you define are met. You can even customize it to display error messages directly on the UI, as shown in the example 😄

To use this, simply create an init-script.js file and provide its path in your mcp.json as shown below.

    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--init-script=path/to/init-script.js"
      ]
    }

4. Extension

If you want MCP to run with your own browser settings using your personal browser profile this part is exactly what you need. After downloading and installing the extension (as shown in the link), you can run your MCP tests on your own browser profile by adding the following configuration to your mcp.json.

    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--extension"
      ]
    }

After completing the setup, when you run MCP, it will launch a browser using your profile and ask for permission to access it. Once you approve that prompt, it will continue running with your own browser settings.

Debbie O'Brien also has a great video about this extension on YouTube. I definitely recommend watching it.

https://youtu.be/uE0r51pneSA?si=opgO-bCizppC7uxK

5. Other Settings

In addition to the features mentioned above, there are a few more settings that can be useful:

Isolated: Ensures that each test session starts in an isolated browser profile. Use --isolated.
Device: If you want your MCP to emulate different devices while running tests and analyzing pages, you can set this option. Example: --device=iPhone 15.
Headless: If you don’t want to see a browser launching while MCP does its work in the background, add this option to your mcp.json --headless.

Finally, you can also configure agents to perform the actions you want. Playwright MCP server allows you to run JavaScript evaluate commands. For example, you can add a step like the following to the Planner agent’s MD file: