Add MCP server reference pages for vault tools

docs.json

@@ -383,6 +383,17 @@
               "reference/mcp-server/tools/manage-proxies",
               "reference/mcp-server/tools/manage-extensions",
               "reference/mcp-server/tools/manage-apps",
+              {
+                "group": "Vaults",
+                "pages": [
+                  "reference/mcp-server/tools/manage-vaults",
+                  "reference/mcp-server/tools/manage-vault-credentials",
+                  "reference/mcp-server/tools/manage-vault-items",
+                  "reference/mcp-server/tools/manage-vault-wallets",
+                  "reference/mcp-server/tools/manage-vault-cards",
+                  "reference/mcp-server/tools/manage-vault-provider-configs"
+                ]
+              },
               "reference/mcp-server/tools/computer-action",
               "reference/mcp-server/tools/execute-playwright-code",
               "reference/mcp-server/tools/browser-repl",

reference/mcp-server.mdx

@@ -46,6 +46,9 @@ The server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with
   <Card icon="terminal" title="browser_repl" href="/reference/mcp-server/tools/browser-repl">
     Run persistent JavaScript with browser helpers, WebMCP, CDP, and Playwright.
   </Card>
+  <Card icon="vault" title="Vaults" href="/reference/mcp-server/tools/manage-vaults">
+    Collect credentials and payment items per end user, then fill them into attached browsers.
+  </Card>
   <Card icon="database" title="Resources" href="/reference/mcp-server/resources">
     Read browsers, browser pools, profiles, and apps.
   </Card>

reference/mcp-server/examples.mdx

@@ -32,6 +32,25 @@ Assistant: I'll start a replay recording, run the automation, then stop it.
 [Uses manage_replays tool with action: "stop" to end the recording]
 ```
 
+## Fill a login from a vault
+
+```
+Human: Log in to github.com for user-123 with a password they enter themselves, not in chat.
+Assistant: I'll check user-123's vault for a GitHub credential first.
+[Uses manage_vaults tool with action: "create" and name: "user-123", which returns the vault if it already exists]
+[Uses manage_vault_items tool with action: "list" on vault "user-123"; no GitHub credential exists]
+Assistant: Is your GitHub login saved in your own 1Password, or would you rather enter it in a secure Kernel form?
+Human: The Kernel form.
+[Uses manage_vault_credentials tool with action: "create", provider: "kernel", and username/password field definitions]
+Returns: a collection URL to share privately with the user
+[Uses manage_vault_items tool with action: "get" and wait: 60 until the credential is ready]
+[Uses manage_browsers tool with action: "create" and vaults: [{ "name": "user-123" }], then navigates to the login page]
+[Uses manage_vault_items tool with action: "invoke", operation: "fill", and inputs with browser_id, page_url, and field/selector bindings]
+Returns: per-field outcomes without the values. Fill never submits, so the agent retries it if it fails, then submits the form and checks the page.
+```
+
+See [`manage_vaults`](/reference/mcp-server/tools/manage-vaults) for the full set of vault tools.
+
 ## Set up browser profiles for authentication
 
 ```

reference/mcp-server/tools/manage-browsers.mdx

@@ -29,6 +29,7 @@ Browser lifecycle lives here: `create` a session before running [`execute_playwr
 | `save_profile_changes` | (create) Save session changes back to the profile on close. |
 | `proxy_id` | (create) Proxy ID for traffic routing. |
 | `extension_id` / `extension_name` | (create) Extension to load. |
+| `vaults` | (create) Up to 20 [vaults](/reference/mcp-server/tools/manage-vaults) to attach, each as `{ "id": ... }` or `{ "name": ... }`. Attachments can't be added or changed after creation. |
 | `viewport_width` / `viewport_height` | (create) Window size in pixels. Must be set together. |
 | `viewport_refresh_rate` | (create) Display refresh rate in Hz. |
 | `timeout_seconds` | (create) Inactivity timeout in seconds (max 259200 = 72h). Default 60. |

reference/mcp-server/tools/manage-vault-cards.mdx

@@ -0,0 +1,82 @@
+---
+title: "manage_vault_cards"
+description: "Create and update payment card requests in a vault"
+---
+
+**status:** <Badge color="yellow">preview</Badge>
+
+Configure card requests against a connected [Link by Stripe or AgentCard wallet](/reference/mcp-server/tools/manage-vault-wallets). A card request sets the merchant and spending limit for a purchase; it doesn't submit a merchant payment.
+
+Mode comes from the wallet's provider credentials; there's no per-item test flag. Assume real payment effects.
+
+## Actions
+
+| Action | Description |
+|--------|-------------|
+| `create` | Create a card request, or return the identical existing request with the same key. |
+| `update` | Replace a requested card's spec, when the API allows the edit. |
+
+Neither action authorizes a Link card. Read `available_operations` with [`manage_vault_items`](/reference/mcp-server/tools/manage-vault-items) and get explicit user approval before invoking `authorize`.
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `action` | Operation to perform: `create` or `update`. Required. |
+| `vault` | Vault ID or name. Required. |
+| `key` | Immutable card key within the vault. Required. |
+| `provider` | `link` or `agentcard`. Required. |
+| `spec` | Full provider-specific specification object. Required. No defaults or normalization are applied. |
+| `project` | Optional project name or ID. |
+
+Amounts are integers in minor currency units, such as cents.
+
+### Link spec
+
+| Field | Description |
+|-------|-------------|
+| `wallet` | Key of the Link wallet in the same vault. |
+| `payment_method_id` | Payment method the user selected from the wallet's `payment_methods`. |
+| `amount` | Spending limit, from 1 to 50000. |
+| `currency` | Three-letter currency code, such as `usd`. |
+| `merchant_name` | Merchant display name. |
+| `merchant_url` | Merchant URL. Fill only works on a page at this origin. |
+| `context` | Description of the purchase, at least 100 characters. |
+| `line_items`, `totals`, `metadata`, `expires_at` | Optional purchase details. |
+
+### AgentCard spec
+
+| Field | Description |
+|-------|-------------|
+| `wallet` | Key of the AgentCard wallet in the same vault. |
+| `merchant` | Merchant name, up to 120 characters. |
+| `amount` | Spending limit. |
+| `currency` | Three-letter currency code. |
+| `checkout_origin` | Optional canonical HTTPS origin, such as `https://shop.example`, forwarded for autopilot rule matching. KERNEL doesn't compare it with the browser page, and it doesn't enable autopilot. |
+| `card_id` | Optional funding card (`vc_...`). Omit to let the cardholder choose at approval. |
+
+## Example
+
+```json
+{
+  "action": "create",
+  "vault": "user-123",
+  "key": "order-1042",
+  "provider": "link",
+  "spec": {
+    "wallet": "link-wallet",
+    "payment_method_id": "pm_123",
+    "amount": 4599,
+    "currency": "usd",
+    "merchant_name": "Example Shop",
+    "merchant_url": "https://shop.example",
+    "context": "Buy one pair of trail running shoes in size 10 from Example Shop for the order the user approved, with a total limit of 45.99 USD."
+  }
+}
+```
+
+After authorization, fill a Link card into the merchant checkout with `manage_vault_items` `fill`. AgentCard cards don't use `fill`. The browser enters the card's `state.aliases` and KERNEL holds the checkout for the user's approval, or, for supported processors, you invoke the card's advertised checkout-preparation operation first. See [Link by Stripe](/integrations/wallets/stripe-link) and [AgentCard](/integrations/wallets/agentcard) for the full checkout flows.
+
+<Warning>
+Never reconfigure a card to retry a failed, timed-out, rejected, or indeterminate payment. Inspect state and events instead. An uncertain update moves the card to `recovery_required`; stop and reconcile with the provider or support.
+</Warning>

reference/mcp-server/tools/manage-vault-credentials.mdx

@@ -0,0 +1,131 @@
+---
+title: "manage_vault_credentials"
+description: "Create and update vault credentials, and connect 1Password accounts"
+---
+
+**status:** <Badge color="yellow">preview</Badge>
+
+Create or update login credentials in a per-end-user [vault](/reference/mcp-server/tools/manage-vaults). Credentials follow one of two paths, and the user chooses which:
+
+- **KERNEL-hosted collection** (`provider: "kernel"`): the user enters values in a KERNEL-hosted form, and the agent fills them into the browser with value-free bindings. See [Credentials](/vaults/credentials).
+- **1Password brokered approval** (`provider: "1password"`): the user connects their 1Password account once and approves each login request in the 1Password app. See [1Password](/vaults/1password).
+
+Before creating a credential, list the vault with [`manage_vault_items`](/reference/mcp-server/tools/manage-vault-items) and reuse an existing one for the site. If none fits, ask the user where their login lives and set `provider` to match; the tool rejects a create without `provider`.
+
+## Actions
+
+| Action | Description |
+|--------|-------------|
+| `create` | Create a credential, or return the identical existing credential with the same key. |
+| `update` | Update the description or values of a KERNEL-hosted credential. 1Password credentials can't be updated. |
+| `connect_account` | Connect a 1Password account to the vault. Returns an authorization URL for the account owner. |
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `action` | Operation to perform: `create`, `update`, or `connect_account`. Required. |
+| `vault` | Vault ID or name. Required. |
+| `key` | Immutable item key within the vault, not the item ID. Required. |
+| `provider` | (create, connect_account) `kernel` or `1password`. `connect_account` only supports `1password`. |
+| `spec` | (create, update) Credential specification. Shape depends on the provider and action; see below. |
+| `version` | (update) Current item version. Required for update. |
+| `expected_item_id` | (update) Optional item ID from an earlier read. The update fails if the key now refers to a different item. |
+| `project` | Optional project name or ID. |
+
+### KERNEL-hosted create spec
+
+| Field | Description |
+|-------|-------------|
+| `description` | Recognizable site or service name only, such as `GitHub`. Display text, not a destination policy. |
+| `fields` | 1–32 field definitions, in the website's top-to-bottom order. The collection form renders them in this order. |
+
+Each field definition takes:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Stable field name used for updates and fills. Starts with a letter; letters, numbers, and underscores; up to 64 characters. Must be unique. |
+| `label` | Optional non-secret display text shown on the collection form. |
+| `type` | `text`, `email`, `password`, or `totp`. |
+| `required` | Whether the user must supply a value. |
+| `sensitive` | Defaults to `true`. Set `false` explicitly for ordinary usernames and emails so they're readable. `password` and `totp` must stay sensitive. |
+| `value` | Optional initial value. Omit secrets so the user enters them privately. A `totp` value is a seed, not a current code. |
+
+Definitions are immutable after create.
+
+### KERNEL-hosted update spec
+
+| Field | Description |
+|-------|-------------|
+| `description` | Replacement display name. An empty string clears it. |
+| `fields` | Values keyed by field name, such as `{ "username": { "value": "new-name" } }`. Omitted fields are preserved; `null` or `""` clears a supported value. |
+
+Never ask for passwords or TOTP seeds in chat. To let the user edit values, reopen the collection form with `manage_vault_items` (`action: "invoke"`, `operation: "collect"`).
+
+### 1Password create spec
+
+| Field | Description |
+|-------|-------------|
+| `account` | Key of a connected `credential_account` item in the same vault. Each end user's vault connects its own account. |
+| `logins` | 1–5 logins the owner approves together, each with an `https://` `website` and optional `reason` (up to 100 characters) and `keywords` (up to 5). |
+| `goal` | Optional short goal (up to 140 characters) shown to the account owner. |
+
+1Password supports logins in the owner's own non-shared vault, not shared-vault items or passkeys. Use KERNEL-hosted collection for those, or if the user declines 1Password.
+
+## Collect a login
+
+Create the credential without values:
+
+```json
+{
+  "action": "create",
+  "provider": "kernel",
+  "vault": "user-123",
+  "key": "github-login",
+  "spec": {
+    "description": "GitHub",
+    "fields": [
+      { "name": "username", "type": "text", "required": true, "sensitive": false },
+      { "name": "password", "type": "password", "required": true, "sensitive": true }
+    ]
+  }
+}
+```
+
+The response includes a bearer collection URL in `item.action.url`. Give it only to the intended user, outside the agent-controlled browser. Then wait for readiness with `manage_vault_items` (`action: "get"`, `wait: 60`) before invoking `fill`.
+
+## Use 1Password
+
+Connect the account once per vault:
+
+```json
+{
+  "action": "connect_account",
+  "provider": "1password",
+  "vault": "user-123",
+  "key": "onepassword"
+}
+```
+
+Give the returned authorization URL only to the account owner. Once `manage_vault_items` `get` reports the account `connected`, create the credential:
+
+```json
+{
+  "action": "create",
+  "provider": "1password",
+  "vault": "user-123",
+  "key": "github-login",
+  "spec": {
+    "account": "onepassword",
+    "logins": [{ "website": "https://github.com/login" }]
+  }
+}
+```
+
+Next, invoke `1pw_create_access_request` through `manage_vault_items`; it doesn't need a browser. The owner approves the request in the 1Password app. Once the credential is ready, create a browser with the vault attached and invoke `1pw_fill`. See [`manage_vault_items`](/reference/mcp-server/tools/manage-vault-items#1password-operations).
+
+<Note>
+1Password credentials backed by a customer-supplied access token and integration key are created and rotated through the KERNEL API, not MCP. The MCP server never accepts those secrets.
+</Note>
+
+Writes aren't automatically retried. Reconcile conflicts or uncertain outcomes before writing again.