Set up the MCP server

Add Agent Vault to your MCP client and your agent gets 29 tools for checking out and signing in, with no Playwright code to write.

Overview

@agentvault/mcp is a Model Context Protocol server. It exposes the Agent Vault proxied browser as tools, so any MCP-capable agent can fill checkout and sign-in forms with mock tokens while the proxy types the real values. There are two ways to connect:

Hosted MCP server, if your deployment runs one: your MCP client connects to a remote server over streamable HTTP. You sign in once in your browser, then choose on the dashboard’s Connected apps page which cards and logins the connection may use. Nothing to install, no API key to copy. See Connect to the hosted server.
Local MCP server: your MCP client launches @agentvault/mcp on your machine, with your API key in its environment. Setup starts at Before you start.

The local server is built on the SDK: every tool maps to one @agentvault/playwright call, so it has the same proxy protocol, URL locking and tunnel behaviour. It reads the same environment variables the SDK reads, plus one optional network setting of its own (AGENTVAULT_NETWORK_FAMILY_AUTOSELECTION, below) that you rarely need.

Meta Muse, Grok Bot, OpenClaw, Claude Code, Hermes, Claude Desktop, Antigravity and Codex each have their own page with the exact steps: see Connect your agent. Cursor is not in the framework picker: use its tab below.The fastest path is the dashboard. The framework picker on Overview generates the setup for your MCP client. If your deployment runs the hosted server, the picker shows two routes for OpenClaw, Claude Code, Hermes and Codex:

Sign in: one line to paste into your agent. Manual steps are under Set it up by hand.
Use an API key: a local config block with your key, your deployment’s URLs and the install URL filled in.

The route marked (recommended) comes first. The other is under Other way to connect.In the picker, Meta Muse, Grok Bot, Claude Desktop and Antigravity have only the Sign in route. Claude Desktop has no line to paste: add the connector in its settings. To run the local server in Claude Desktop, use its tab below.If your deployment has no hosted server, the picker shows only the local block. Copy it, then skip to Verify the connection.

Connect to the hosted server

This section applies only when your dashboard’s framework picker shows a Sign in route. If it does not, your deployment has no hosted server: use the local setup below.

Paste the line into your agent

Copy the line under Sign in and paste it into your agent:

Read https://mcp.agentvault.io/skill.md and follow it to connect Agent Vault.

The agent reads the connect skill, adds the server and asks you to sign in.

Or add the server by hand

The hosted MCP server is at https://mcp.agentvault.io/mcp. Self-hosting? Use the URL under Set it up by hand in the framework picker instead.

MCP client	Add the server	Sign in
Claude Code	`claude mcp add --transport http agent-vault https://mcp.agentvault.io/mcp`	Run `/mcp` in Claude Code and choose Agent Vault, or run `claude mcp login agent-vault`
Codex	`codex mcp add agent-vault --url https://mcp.agentvault.io/mcp`	Sign-in starts on its own after the add. If it does not, run `codex mcp login agent-vault --no-browser`
Other MCP clients	Add a remote MCP server with the URL, using streamable HTTP and OAuth	Your client finds the sign-in page from the URL

The Claude Code command is the one the dashboard gives. It has no --scope flag, so Claude Code adds the server only for the project you run it in. To use it in every project, add --scope user after --transport http.Sign-in opens the Agent Vault sign-in page in your browser. Sign in with your Agent Vault account.

Make a first call

Ask your agent to call get_token_catalog. Codex keeps the MCP servers it started with, so start a new Codex session first if you added the server from inside a running one.The first call after a new sign-in is expected to fail. The call creates the connection with nothing granted yet, and the tool answers:

Choose what this app may use in Agent Vault before it can act: open the connection's page in the dashboard.

Your deployment may add a link after that sentence. Until you choose access, every tool that uses your account answers this way. Only get_checkout_recipes, which reads the public recipe registry, works before then. The refusal’s code is access_not_chosen, but the agent sees only the message.

Choose what it may use

In the dashboard sidebar, under Vault, click Connected apps. Find the new connection’s row: its Access column reads Choose what it may use. Click the Choose access button on that row.

The first connection’s dialog opens with nothing ticked. Later ones open with the settings of the connection you used most recently, all three switches included. Check every setting before you click Save access.

In the What this app may use dialog:

Under Cards, pick All cards, or keep Only selected and tick the cards it may use.
Under Logins, pick All logins, or keep Only selected and tick the logins it may use.
Tick Let this app create and change its own logins only if the agent should sign you up for new accounts.
Tick Ask me before every purchase from this app if you want to approve each of its purchases yourself.
Tick Fill a test card instead of my card if this connection only tests checkouts.
Click Save access.

Each setting works as it does for an API key. See Connected apps.

Check it works

Ask your agent to call get_token_catalog again. It now returns mock tokens for the cards and logins you allowed.Your sign-in does not last forever. When the access token expires or is refused, the server answers HTTP 401 with error="invalid_token" before any tool runs, so the agent gets no tool error to act on. Your MCP client may refresh the token by itself. If it cannot, the server appears in your client as needing sign-in and its tools fail until you sign in again. Retrying the tool does not help. See Sign-in responses.A new sign-in can create a new connection, which again starts with nothing granted. If the agent gets the error above after you sign in again, choose access for the new row on Connected apps.The hosted server has the same tools as the local one, and each takes one more argument, session. The call that starts a session, such as open_page or get_token_catalog, returns a session handle, and your agent passes it on every later call so they reach the same browser. See On the hosted server.A hosted session closes after 13 minutes without a call to its browser, or 56 minutes after its browser opened. The hosted server waits up to 4 minutes for a tool call’s answer (12 for request_challenge_handoff, which waits for the account holder). After that wait, the server reports the outcome as unknown. The call is not cancelled and may still complete. Check the page before repeating a click or any other action. A restart of the hosted server ends every session.A connection can hold at most 50 live credentials at once. Each open session holds one. The recipe submission tools hold one while they run. A credential request that timed out keeps its credential, with no session owning it, for up to 75 minutes. So you can hit the limit with fewer than 50 open sessions, and closing sessions may not free it. See Limits.

Review, change or revoke it later

Each sign-in is listed on Connected apps with three details: what it may use, when it was last used, and a Revoked if unused by date.

To change what it may use, click Change access on its row, change the settings and click Save access. The app’s next call uses them.
To stop it for good, click Revoke on its row, then Revoke connection. This cannot be undone: to reconnect, sign in again and choose access for the new connection. After revoking, the app cannot get a new credential or fill a saved value. Any browser session it has open closes within about a minute. A call that needs a new credential is refused with connection_revoked. A call on a session that is already open may still run briefly (for example a click) and then fails because the session closed, so do not wait for connection_revoked specifically.

Only Revoke on Connected apps stops a connection (or it lapses on its Revoked if unused by date). Signing out of your MCP client does not revoke it. Removing the app’s access in your sign-in account settings does not either: the hosted server does not check with the sign-in service, so a token already issued keeps working until it expires.

See Connected apps.

Before you start

For the local server you need the items below. The hosted server needs none of them: only an MCP client that supports remote servers over streamable HTTP with OAuth.

An API key. Create one on the dashboard’s API keys page with New key. See API keys.
Node.js with npx on your PATH. Your MCP client runs the server through npx. npm 12 refuses to fetch a package from a URL unless --allow-remote=all comes before the URL, so every command below includes it. npm 11 accepts it with an “Unknown cli config” warning.
Only on a self-hosted Agent Vault: your deployment’s origin, as your dashboard’s address bar shows it, in place of https://app.agentvault.io below.

The install URL

The package is not on npm. It is a self-contained tarball (server, SDK and their dependencies) that Agent Vault hosts at:

https://app.agentvault.io/mcp/agentvault-mcp.tgz

The config blocks below point at the hosted service at app.agentvault.io. If you change only the install URL, your key is sent to the hosted proxy and API, which do not recognise it. Self-hosting? Copy the whole block from the framework picker on your dashboard’s Overview page instead. It fills in your deployment’s install URL, proxy URL and API URL.

Only use an http:// install URL for localhost or 127.0.0.1. The package runs on your machine, and anyone on the network path could replace it.

Add the server to your MCP client

Pick your MCP client. Each block uses the same server definition; only the file and its format differ.

Claude Code
Claude Desktop
Cursor
Codex
Other MCP clients

Add the server

Add the agent-vault entry to the mcpServers object in your user-level ~/.claude.json, merged with any servers already there:

~/.claude.json

{
  "mcpServers": {
    "agent-vault": {
      "command": "npx",
      "args": ["-y", "--allow-remote=all", "https://app.agentvault.io/mcp/agentvault-mcp.tgz"],
      "env": {
        "SELF_AGENT_PAY_API_KEY": "av_...",
        "SELF_AGENT_PAY_PROXY_URL": "wss://proxy.agentvault.io/v1",
        "SELF_AGENT_PAY_API_URL": "https://api.agentvault.io"
      }
    }
  }
}

Or use the CLI. claude mcp add-json takes only the inner server object, not the whole mcpServers document. Keep --scope user: without it, Claude Code adds the server only for the project you run the command in. The dashboard’s command has no --scope flag, so add it yourself.

claude mcp add-json --scope user agent-vault '{"command":"npx","args":["-y","--allow-remote=all","https://app.agentvault.io/mcp/agentvault-mcp.tgz"],"env":{"SELF_AGENT_PAY_API_KEY":"av_...","SELF_AGENT_PAY_PROXY_URL":"wss://proxy.agentvault.io/v1","SELF_AGENT_PAY_API_URL":"https://api.agentvault.io"}}'

This block carries your live API key. Keep it in the user-level ~/.claude.json. Do not paste it into a project .mcp.json that is committed to a repository.

Allow the tools

Claude Code asks before each MCP tool call unless a permission rule allows it. If a call is refused mid-run, the agent can leave a form half filled or a session open. Allow the server once in ~/.claude/settings.json (or an uncommitted .claude/settings.local.json), merged with any rules already there:

~/.claude/settings.json

{ "permissions": { "allow": ["mcp__agent-vault"] } }

mcp__agent-vault matches only this server’s tools. It does not loosen anything for other servers or for shell commands.

Restart Claude Code

Restart so Claude Code picks up the new server and the permission rule.

Open the config file

In Claude Desktop, open Settings, then Developer, then Edit Config. This opens claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server

Add the agent-vault entry to mcpServers, merged with any servers already there:

claude_desktop_config.json

{
  "mcpServers": {
    "agent-vault": {
      "command": "npx",
      "args": ["-y", "--allow-remote=all", "https://app.agentvault.io/mcp/agentvault-mcp.tgz"],
      "env": {
        "SELF_AGENT_PAY_API_KEY": "av_...",
        "SELF_AGENT_PAY_PROXY_URL": "wss://proxy.agentvault.io/v1",
        "SELF_AGENT_PAY_API_URL": "https://api.agentvault.io"
      }
    }
  }
}

Restart Claude Desktop

Quit and reopen the app. The Agent Vault tools appear in the tools menu of the chat input.

Open the MCP config

Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json in one project. Prefer the global file: the block carries your API key.

Add the server

~/.cursor/mcp.json

{
  "mcpServers": {
    "agent-vault": {
      "command": "npx",
      "args": ["-y", "--allow-remote=all", "https://app.agentvault.io/mcp/agentvault-mcp.tgz"],
      "env": {
        "SELF_AGENT_PAY_API_KEY": "av_...",
        "SELF_AGENT_PAY_PROXY_URL": "wss://proxy.agentvault.io/v1",
        "SELF_AGENT_PAY_API_URL": "https://api.agentvault.io"
      }
    }
  }
}

Reload Cursor

Reload the window. Then open Cursor Settings, find the list of MCP servers and check that agent-vault shows as connected.

Add the server

Codex reads MCP servers from TOML, not JSON. Add these tables to ~/.codex/config.toml:

~/.codex/config.toml

[mcp_servers.agent-vault]
command = "npx"
args = ["-y", "--allow-remote=all", "https://app.agentvault.io/mcp/agentvault-mcp.tgz"]

[mcp_servers.agent-vault.env]
SELF_AGENT_PAY_API_KEY = "av_..."
SELF_AGENT_PAY_PROXY_URL = "wss://proxy.agentvault.io/v1"
SELF_AGENT_PAY_API_URL = "https://api.agentvault.io"

Restart Codex

Restart so Codex picks up the new server.

Any MCP client that launches stdio servers works. Give it:

Setting	Value
Command	`npx`
Arguments	`-y`, `--allow-remote=all`, `https://app.agentvault.io/mcp/agentvault-mcp.tgz`
Environment	The variables in Configuration

Most MCP clients accept the same mcpServers JSON shown in the other tabs.

Configuration

The server reads the same environment variables as the SDK, plus AGENTVAULT_NETWORK_FAMILY_AUTOSELECTION, which only the MCP server reads. Set them in the env block of your MCP client’s config.

string

required

The agent’s API key, from the dashboard. Used for the proxy session and the token catalog.

string

required

The proxy WebSocket URL. Use wss://proxy.agentvault.io/v1 for the hosted service, or your deployment’s proxy URL. If unset, the server tries a local development proxy at ws://localhost:4000/v1 and fails with Failed to connect to proxy when none is running.

string

required

The token catalog API base, https://api.agentvault.io on the hosted service.

string

Controls whether the browser’s traffic leaves from your own IP address through a tunnel.

Unset (default): use the tunnel if available; otherwise leave from the deployment’s own egress (the proxy’s address, or its residential egress where configured).
1: require the tunnel. The browser refuses to launch without it.
0: never use the tunnel.

See Egress and tunnelling.

string

Set to 1 to require residential egress without a tunnel through your machine. The first open_page then fails with egress_unavailable when the deployment has none or its provider is not answering, instead of leaving from the proxy’s address. A residential egress session is HTTPS only. See Residential egress.

string

MCP server only. Set to 1 to let Node pick between IPv4 and IPv6 by racing both (Node’s default). Leave unset to connect to one address per hostname, which avoids silent fetch failed errors on networks with a broken IPv6 path.

The full list, including timeouts, is on Environment variables.

Verify the connection

Fetch the token catalog

Ask your agent to call get_token_catalog. It needs no browser and no open page. A successful call returns your mock tokens: identity, addresses, cards and logins.

Run a test checkout

The practice checkout (/demo-checkout) is not a payment page. Never let the proxy type your real card there.

On API keys, tick Fill a test card instead of my card on the key in your config, or create a separate key with it ticked. A change to an existing key applies from the agent’s next session.Then ask your agent to check out at https://app.agentvault.io/demo-checkout, or your own origin plus /demo-checkout if self-hosted. It should call open_page, fill the card with a mock token through fill_checkout, submit, and confirm with get_session_outcome. The fill_checkout reply carries a card_fields_verified note when the test card went in. If it does not, stop before submitting.

If it fails

The server did not start

The install URL is almost always the cause. Look in your MCP client’s server log for a 404 or a DNS failure. In Claude Code, claude mcp list shows each server’s status.

unauthorized or invalid_api_key

The key is missing, mistyped or revoked. A revoked key gets the same error as a wrong one, so check the key’s status on the dashboard’s API keys page.

Failed to connect to proxy

SELF_AGENT_PAY_PROXY_URL is unset, wrong, or the proxy is unreachable. Check that the proxy is reachable: open https://proxy.agentvault.io/health (on a self-hosted deployment, use your proxy’s hostname, with https:// in place of wss://). It returns {"ok":true,...}.

Every request fails with fetch failed

The server already avoids the most common cause, an IPv6 path that neither connects nor refuses. If you set AGENTVAULT_NETWORK_FAMILY_AUTOSELECTION=1, unset it and restart your MCP client.

rate_limited on the catalog

The catalog is rate-limited per key and per account (all keys of an account share the account limit). The limits depend on the plan. The response includes Retry-After in seconds. Wait that long: the window is fixed, so retrying early is refused again.

A page tool says to call open_page first

Page tools need a browser. Call open_page with a URL before click, fill_checkout or any other page tool.

Add the agent skill

The tools give your agent the capability. The skill gives it the judgement: when to hand a step to the account holder, why it must never invent a password, and what order to fill card fields in. Install both. See Rules of engagement.

Next steps

Tool reference

All 29 tools, their parameters and what they return.

Rules of engagement

The rules your agent is expected to follow.

Error codes

What each refusal means and whether to retry.

First checkout

Walk through a full checkout end to end.

MCP server

Playwright SDK

Checkout recipe registry

Set up the MCP server

Overview

Connect to the hosted server

Before you start

The install URL

Add the server to your MCP client

Configuration

Verify the connection

If it fails

Add the agent skill

Next steps

Tool reference

Rules of engagement

Error codes

First checkout

​Overview

​Connect to the hosted server

​Before you start

​The install URL

​Add the server to your MCP client

​Configuration

​Verify the connection

​If it fails

​Add the agent skill

​Next steps

Tool reference

Rules of engagement

Error codes

First checkout

Overview

Connect to the hosted server

Before you start

The install URL

Add the server to your MCP client

Configuration

Verify the connection

If it fails

Add the agent skill

Next steps