Connect your agent

There are two ways to get a session in front of your agent. Pick based on which browser the agent drives.

The managed browser. valetkey owns a Chrome profile and injects sessions into it live. Persona switching is instant, and it works with Claude in Chrome, Chrome DevTools MCP, and Playwright MCP in attach mode. Start here if your agent can attach to a running Chrome.

Storage-state files. valetkey writes a Playwright storage-state file and the agent’s own browser loads it at startup. Works everywhere, including CI, but picking up a new session means restarting the browser context.

Recommended: the MCP server

{
  "mcpServers": {
    "valetkey": { "command": "npx", "args": ["valetkey", "mcp"] }
  }
}

That file is .mcp.json for Claude Code and .cursor/mcp.json for Cursor. For Codex, in ~/.codex/config.toml:

[mcp_servers.valetkey]
command = "npx"
args = ["valetkey", "mcp"]

The agent then calls valetkey_list_personas and valetkey_login_as, which starts the managed browser if needed and injects the session. The MCP reference covers all four tools.

Add a line to CLAUDE.md or AGENTS.md so the agent knows the tools exist:

To browse the app signed in, call `valetkey_login_as` with a persona from
`valetkey_list_personas`, then use the browser tools as usual.

Claude Code with Claude in Chrome

Claude in Chrome attaches to a real Chrome profile, so valetkey meets it there.

valetkey browser

In that window, install and connect the Claude in Chrome extension. This is a one-time step per profile. From then on Claude browses a profile whose session valetkey controls, and it stays signed in as whichever persona you last picked.

Since this profile holds only your dev app’s sessions, it also satisfies the usual advice to keep browser-using agents away from a profile with your real logins.

Chrome DevTools MCP

Point it at the managed browser instead of letting it launch its own:

valetkey browser --print-devtools-config

That prints the config with the current port filled in:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:49808"]
    }
  }
}

Both servers coexist on one browser: DevTools MCP drives pages, valetkey decides who is signed in. The port changes on each launch, so re-print it after restarting Chrome.

Playwright MCP

Attach mode shares the managed browser, so live persona switching works:

npx @playwright/mcp@latest --cdp-endpoint http://127.0.0.1:49808

Isolated mode loads a file instead, which is the right choice when you want the agent in its own clean browser:

valetkey login admin --export playwright/.auth/admin.json
npx @playwright/mcp@latest --storage-state playwright/.auth/admin.json

In isolated mode the state is read when the context is created, so after re-exporting, have the agent close and reopen its browser.

Codex

Codex’s built-in browser does not support signed-in pages, so use the valetkey MCP server together with Playwright MCP, or the storage-state path above.

Multiple personas at once

For testing authorization differences side by side, export each persona to its own file and register one Playwright MCP server per file:

valetkey login admin --export playwright/.auth/admin.json
valetkey login free-user --export playwright/.auth/free-user.json

In the managed browser only one persona is signed in at a time, by design: it is one browser profile, and two conflicting sessions for the same origin would be worse than useless.

CI and Playwright tests

The same artifact drives your test suite, so the agent’s dev loop and CI stay on one mechanism.

npx valetkey login admin --export playwright/.auth/admin.json

use: {
  storageState: "playwright/.auth/admin.json",
},

Pass --no-browser in CI to be explicit that nothing should try to start Chrome. On machines without a keychain, valetkey falls back to a file identity: create one with valetkey identity create, add its public key as a recipient with valetkey team add "ci" age1..., and set VALETKEY_HOME to a writable directory.