> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up the MCP server

> Add the Agent Vault MCP server to Claude Code, Claude Desktop, Cursor or Codex: sign in to the hosted server, or add one local config block.

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](https://modelcontextprotocol.io)
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](/reference/glossary) 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](#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](#before-you-start).

The local server is built on the SDK: every tool maps to one
[`@agentvault/playwright`](/sdk/install) 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.

<Tip>
  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](/agents/overview). 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](#verify-the-connection).
</Tip>

## 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.

<Steps>
  <Step title="Paste the line into your agent">
    Copy the line under **Sign in** and paste it into your agent:

    ```text theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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:

    ```text theme={null}
    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.
  </Step>

  <Step title="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.

    <Warning>
      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**.
    </Warning>

    In the **What this app may use** dialog:

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

    Each setting works as it does for an API key. See
    [Connected apps](/dashboard/api-keys#connected-apps).
  </Step>

  <Step title="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](/sdk/error-codes#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](/mcp/tool-reference#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](/reference/limits#hosted-mcp-server).
  </Step>

  <Step title="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.

    <Warning>
      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.
    </Warning>

    See [Connected apps](/dashboard/api-keys#connected-apps).
  </Step>
</Steps>

## 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.

1. An API key. Create one on the dashboard's **API keys** page with **New key**.
   See [API keys](/dashboard/api-keys).
2. 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.
3. 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:

```text theme={null}
https://app.agentvault.io/mcp/agentvault-mcp.tgz
```

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

## 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.

<Tabs>
  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the server">
        Add the `agent-vault` entry to the `mcpServers` object in your user-level
        `~/.claude.json`, merged with any servers already there:

        ```json ~/.claude.json theme={null}
        {
          "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.

        ```bash theme={null}
        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"}}'
        ```

        <Warning>
          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.
        </Warning>
      </Step>

      <Step title="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:

        ```json ~/.claude/settings.json theme={null}
        { "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.
      </Step>

      <Step title="Restart Claude Code">
        Restart so Claude Code picks up the new server and the permission rule.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    <Steps>
      <Step title="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`
      </Step>

      <Step title="Add the server">
        Add the `agent-vault` entry to `mcpServers`, merged with any servers already
        there:

        ```json claude_desktop_config.json theme={null}
        {
          "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"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Claude Desktop">
        Quit and reopen the app. The Agent Vault tools appear in the tools menu of the
        chat input.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="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.
      </Step>

      <Step title="Add the server">
        ```json ~/.cursor/mcp.json theme={null}
        {
          "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"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Reload Cursor">
        Reload the window. Then open **Cursor Settings**, find the list of MCP servers
        and check that `agent-vault` shows as connected.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex">
    <Steps>
      <Step title="Add the server">
        Codex reads MCP servers from TOML, not JSON. Add these tables to
        `~/.codex/config.toml`:

        ```toml ~/.codex/config.toml theme={null}
        [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"
        ```
      </Step>

      <Step title="Restart Codex">
        Restart so Codex picks up the new server.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Other MCP clients">
    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](#configuration) |

    Most MCP clients accept the same `mcpServers` JSON shown in the other tabs.
  </Tab>
</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.

<ParamField path="SELF_AGENT_PAY_API_KEY" type="string" required>
  The agent's API key, from the dashboard. Used for the proxy session and the
  token catalog.
</ParamField>

<ParamField path="SELF_AGENT_PAY_PROXY_URL" type="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.
</ParamField>

<ParamField path="SELF_AGENT_PAY_API_URL" type="string" required>
  The token catalog API base, `https://api.agentvault.io` on the
  hosted service.
</ParamField>

<ParamField path="SELF_AGENT_PAY_TUNNEL" type="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](/sdk/tunnel).
</ParamField>

<ParamField path="SELF_AGENT_PAY_RESIDENTIAL_EGRESS" type="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](/sdk/tunnel#residential-egress).
</ParamField>

<ParamField path="AGENTVAULT_NETWORK_FAMILY_AUTOSELECTION" type="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.
</ParamField>

The full list, including timeouts, is on
[Environment variables](/reference/environment-variables).

## Verify the connection

<Steps>
  <Step title="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.
  </Step>

  <Step title="Run a test checkout">
    <Warning>
      The practice checkout (`/demo-checkout`) is not a payment page. Never let the
      proxy type your real card there.
    </Warning>

    On [API keys](/dashboard/api-keys#fill-a-test-card-instead), 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.
  </Step>
</Steps>

### If it fails

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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,...}`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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](/mcp/rules-of-engagement#install-the-skill).

## Next steps

<CardGroup cols={2}>
  <Card title="Tool reference" icon="wrench" href="/mcp/tool-reference">
    All 29 tools, their parameters and what they return.
  </Card>

  <Card title="Rules of engagement" icon="scale-balanced" href="/mcp/rules-of-engagement">
    The rules your agent is expected to follow.
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/sdk/error-codes">
    What each refusal means and whether to retry.
  </Card>

  <Card title="First checkout" icon="cart-shopping" href="/guides/first-checkout">
    Walk through a full checkout end to end.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.