MCP tools

valetkey mcp runs an MCP server on stdio. Register it once and your agent signs itself in as any persona without running a shell command or seeing a credential.

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

The server resolves valetkey.config.ts from the directory the agent launched it in, which is normally your project root.

Every response is JSON, and none of them contain cookie values, tokens, or vault secrets. When something goes wrong the tool returns the error as text with vault values redacted, so a failure never leaks a secret into the transcript.

valetkey_list_personas

No arguments. Returns one entry per configured persona.

[
  {
    "name": "admin",
    "role": "admin",
    "provider": "custom",
    "sessionStatus": "active",
    "expiresAt": "2026-08-24T18:30:00.000Z"
  }
]

sessionStatus is active, expired, or none. Expired sessions are pruned when this runs.

valetkey_login_as

Argument	Type	Effect
persona	string, required	Which persona to become
target	"browser" or "storage-state"	Defaults to browser

With the default target, valetkey starts the managed Chrome profile if it is not already running, mints a session, clears whatever session the configured origins held, and injects the new one.

{
  "persona": "admin",
  "user": { "email": "admin@myapp.test", "role": "admin" },
  "expiresAt": "2026-08-24T18:30:00.000Z",
  "injectedInto": ["chrome:49808"],
  "storageStatePath": "/Users/you/.valetkey/sessions/myapp/admin.json",
  "note": "Injected into the running managed browser. Reload the page to see the session."
}

With target: "storage-state", nothing touches the browser: injectedInto is empty and the agent is told to point its browser tool at storageStatePath and restart its context. Use this when the agent drives its own isolated browser instead of the managed profile.

valetkey_whoami

No arguments. Reports which persona the managed browser currently holds, per origin, by matching the browser’s cookies against stored sessions.

[
  {
    "origin": "http://localhost:3000",
    "persona": "admin",
    "expiresAt": "2026-08-24T18:30:00.000Z"
  }
]

If the managed browser is not running, the response says so in a note rather than failing, so the agent knows to call valetkey_login_as first.

valetkey_logout

Takes an optional persona; omit it to sign out of everything. Revokes each session through the provider, deletes the local artifacts, and clears the cookies from the managed browser.

{ "revoked": ["admin"] }

Telling your agent about it

Agents use these tools far more reliably when the project file mentions them. In CLAUDE.md or AGENTS.md:

To browse the app as a signed-in user, call the valetkey MCP tools:
`valetkey_list_personas` to see who you can be, then `valetkey_login_as` with
that persona. It injects into the managed Chrome profile.