<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# MCP tools

An agent works in a Space through the Agent Vault MCP server. The server speaks MCP over Streamable HTTP at `https://mcp.workos.com/agent-vault/mcp`.

## Authentication

Send a [grant](https://workos.com/docs/reference/agent-vault/grant/create) as a bearer token in the `Authorization` header. The server checks the grant, the user, and the Space again on every tool call, so a call fails as soon as the grant expires, the user leaves the organization, or the Space is closed.

A request without a valid grant responds with `401 Unauthorized`. Requests are rate limited per user. A `429 Too Many Requests` response carries a `Retry-After` header.

## Saved logins and sign-in

| Tool                        | Arguments                                                       | Result                                                                    |
| --------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `browser_credentials`       | None                                                            | The user's saved logins: `id`, `label`, `website_url`, and `setup_state`. |
| `browser_login`             | `browser_space_id`, `credential_id`, `fresh_session` (optional) | A sign-in result. See [sign-in results](#sign-in-results).                |
| `browser_verification_code` | `browser_space_id`, `credential_id`, `code`                     | `status: "submitted"`. Call `browser_login` again to see the outcome.     |
| `browser_sign_in_link`      | `browser_space_id`, `credential_id`, `parent_origin` (optional) | `url` and `expires_at` of a page where the person finishes the sign-in.   |

`browser_login` signs the Space in with a saved login. The first time a login is connected to a Space, set `fresh_session` to `true` to sign in again instead of restoring the session WorkOS saved.

`browser_verification_code` submits a code of 4 to 32 letters and digits that the website sent the person. It only works while a sign-in is waiting for one.

`browser_sign_in_link` returns a short-lived link to the live browser of the sign-in. With `parent_origin`, which must be one of the environment's allowed web origins, the result also has a `preview_url` that only a page on that origin can frame.

### Sign-in results

`browser_login` responds with a `status`:

| Status            | Other fields           | Meaning                                                                                                                                |
| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `connected`       | `credential_id`        | The Space is signed in.                                                                                                                |
| `pending`         | `attempt_id`, `action` | The sign-in is running. Call `browser_login` again. An `action` of `verification_code` or `sign_in` means it is waiting on the person. |
| `needs_attention` | `reason`               | The sign-in failed. `reason` is one of the [failure reasons](https://workos.com/docs/reference/agent-vault/credential#failure-reasons).                       |

## Pages

| Tool                 | Arguments                              | Result                                               |
| -------------------- | -------------------------------------- | ---------------------------------------------------- |
| `browser_navigate`   | `browser_space_id`, `url`              | `status: "ok"`, `url`, `elements`, `page`, and optional `nextPage`. |
| `browser_snapshot`   | `browser_space_id`, `page` (optional)  | `status: "ok"`, `url`, `elements`, `page`, and optional `nextPage`. |
| `browser_screenshot` | `browser_space_id`, `focus` (optional) | A JPEG with passwords, one-time codes, and credential-like fields masked. Other fields may be visible. |
| `browser_click`      | `browser_space_id`, `ref`              | The page after the click.                            |
| `browser_type`       | `browser_space_id`, `ref`, `text`      | The page after the text was typed.                   |

`browser_navigate` opens pages of the website the Space is signed in to. A URL on another origin is refused.

`browser_snapshot` lists the page's visible text, links, buttons, and fields as `elements`. Each element has a `ref`, a `role`, and a `name`. Text entries have `role: "text"` and an empty `ref` and are for reading only. Pass only nonempty refs from actionable controls to `browser_click` or `browser_type`. A new snapshot, or a move to another page, replaces every earlier `ref`. A long page comes in parts: when the result has `nextPage`, call the tool again with that number as `page`.

`browser_screenshot` shows what the page looks like without giving the agent anything to act on. Pass `focus` to scroll to the first text that contains it before the capture.

`browser_type` types up to 1,000 characters into a field. Password and one-time code fields are never listed, so an agent can't type into them.

When a page changes or does not respond in time, a tool responds with an error and the Space stays open. Take a new snapshot and try again.

## Spaces

| Tool                | Arguments                           | Result                                                        |
| ------------------- | ----------------------------------- | ------------------------------------------------------------- |
| `browser_create`    | `name`, `cdp_url` (optional)        | The new [Space](https://workos.com/docs/reference/agent-vault/space).                |
| `browser_status`    | `browser_space_id`                  | The [Space](https://workos.com/docs/reference/agent-vault/space).                    |
| `browser_live_view` | `browser_space_id`, `parent_origin` | `url` and `expires_at` of a live view of the Space's browser. |
| `browser_close`     | `browser_space_id`                  | The closed [Space](https://workos.com/docs/reference/agent-vault/space).             |

`browser_create` needs a grant that is not bound to a Space. With `cdp_url`, the Space runs in a [self-hosted browser you operate](https://workos.com/docs/agent-vault/self-hosted-browser).

`browser_live_view` returns a short-lived link for the person to watch what the agent does. Only a page on `parent_origin` can frame it, and the origin must be one of the environment's allowed web origins, the same list widgets use for CORS, set in the Sessions tab of your application in the [WorkOS Dashboard](https://dashboard.workos.com/environment/applications). Ask for a new link after `browser_login`, because connecting a login opens a new page.

`browser_close` ends the Space for good. Every grant bound to it stops working.