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.
Send a grant 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.
| 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. |
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.
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. |
| 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.
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.
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. 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.