# How an agent gets into Parse

> For agents: Parse's MCP server is https://agent.parse.gl/mcp. It answers from Parse's public view without a sign-in; a person signs in for their own workspace. Setup for each assistant: https://parse.gl/docs/get-started.md. Site index: https://parse.gl/llms.txt.

This page describes, as facts, how an AI agent reaches Parse and what needs its person. It follows the shape of the auth.md agent-registration protocol (https://github.com/workos/auth.md) where Parse has the same steps. Parse publishes no `agent_auth` metadata and none of that protocol's registration endpoints yet; the steps below are Parse's own.

## Hosts

- `https://agent.parse.gl/mcp`: the MCP server (Streamable HTTP). Its protected-resource metadata is `https://agent.parse.gl/.well-known/oauth-protected-resource/mcp`; it names the authorization server and the scopes. Where this page and the metadata differ, the metadata wins.
- `https://agent.parse.gl/v1/tools/<tool>`: every tool over REST, the same inputs and replies. OpenAPI: `https://agent.parse.gl/openapi.json`.

## Ways in

Assistants connect to Parse over MCP at https://agent.parse.gl/mcp (Streamable HTTP). With no sign-in it answers from Parse's public view (the numbers parse.gl's public pages show, up to 5 rows a list), starting with `check_brand`. Signed in with Parse, or sent a workspace key (`parse_mcp_…`), it works in the person's workspace, starting with `get_brief`. Scripts call the same tools over REST at `https://agent.parse.gl/v1/tools/<tool>`.

| The agent has | Way in | What it reaches |
| --- | --- | --- |
| Nothing | MCP or REST with no credentials | Parse's public view: the numbers parse.gl's public pages show, up to 5 rows a list, within daily budgets |
| An MCP client that signs in with OAuth | Sign in with Parse when the server asks (calling `get_brief` logged out answers 401 with the challenge) | The person's workspace, with the access they allow: `parse:dashboard:read`, and `parse:dashboard:write` to act and spend |
| A workspace key the person made | `Authorization: Bearer parse_mcp_…` | Its workspace, every tool |
| No person who can sign in now | `POST https://agent.parse.gl/v1/workspaces`, no credentials | An unclaimed workspace (below) |

## Start a workspace with no account

When a person is present and can sign in, signing in is the way in. With no one who can sign in now, `POST https://agent.parse.gl/v1/workspaces` with no credentials returns a key (sent as `Authorization: Bearer parse_uws_…`). An unclaimed workspace reads Parse's public view, keeps the log_work calls it is sent (list_work returns them) and buys nothing; kept calls are filed into the work record when a person claims it. With no call for 14 days it is deleted. One address may start 10 a day. Whoever holds the key can start the workspace's claim, so it is a secret from the start: it belongs in the agent's secret settings, never in a log, a commit or a message.

## The claim

To claim, the agent asks the person for the email address they use at Parse, then sends POST https://agent.parse.gl/v1/workspaces/claim with the key and {"email": "<address>"}. The reply is the claim link, a 24-hour code and a new workspace key (parse_mcp_…) to store as a secret: it works from the person's claim. The person opens the link, signs in or signs up with that address and types the code there; the code goes into the page, never back to the agent. The agent keeps its current key until it is refused, then switches to the new one. Parse sends no email.

- The reply is `{ claimUrl, code, codeExpiresAt, key }`. The `key` (`parse_mcp_…`) is shown only in that reply; it does nothing until the person claims, and then it is a workspace key, so it is stored as a secret at once.
- The code lasts 24 hours and 5 wrong tries end it. Starting again gives a new code and a new key, and the earlier ones stop counting.
- A link alone claims nothing: the claim page asks the signed-in person whose address the agent named for the code. A person signed in with another address adds the named one to their account, signs in with it, or asks the agent to start again.
- On the claim page the person chooses what the agent may do: work in the workspace as a key made on Agents does, read only, or not stay connected.
- The `parse_uws_…` key stops at the claim. A refused call's error says why in `keyState`: `claimed_connected` means switch to the new key, and `get_brief` then answers for the person's workspace; `claimed_not_connected` means the person connects an assistant themselves. The new key, sent before the claim, is refused with `pending`: keep the current key until it is refused. `attempt_ended` means its code expired or was tried too often: start the claim again for a new code and a new key.

A person claims it on Parse's claim page, signed in or signed up free with the address the agent named, by typing the code the agent showed them. The workspace key the claim start returned then works in their workspace with the access they choose, and the parse_uws_ key stops. Their workspace starts with $5 of credit (once per person), runs their brand's first check (its 20 buyer questions on ChatGPT and Google AI Mode) and then checks it free every week on a panel of 8 questions.

## Parse's claim beside the protocol's terms

| auth.md | Parse |
| --- | --- |
| `POST /agent/identity {"type": "anonymous"}` | `POST /v1/workspaces` |
| identity_assertion, exchanged for an access token | The `parse_uws_…` key, used directly |
| pre_claim_scopes | An unclaimed workspace reads Parse's public view, keeps the log_work calls it is sent (list_work returns them) and buys nothing; kept calls are filed into the work record when a person claims it. With no call for 14 days it is deleted. |
| claim_token | The `parse_uws_…` key, which also authorizes the claim start |
| `POST /agent/identity/claim {claim_token, email}` | `POST /v1/workspaces/claim {"email": "…"}`, with the key |
| user_code, verification_uri | code, claimUrl |
| Polling the claim grant for the post-claim token | None: the post-claim key comes in the claim start's reply and works from the claim |
| post_claim_scopes | The access the person chooses on the claim page |
| Pre-claim tokens revoked at the claim | The same: the `parse_uws_…` key stops at the claim |

Not supported: `service_auth` (registering with only the person's address) and `identity_assertion` (ID-JAG). Parse never emails a code, and never asks a person to give one to an agent.

## Two kinds of claim link

`/claim/workspace/…` is a workspace an agent started, claimed as above. `/claim/<token>` is a brand Parse's staff prepared; a workspace admin can redeem it in their browser or supply the full claim URL to their connected agent for preview and confirmation.

## What needs the person

- Their agreement to sign in, and the access they allow on Parse's consent screen.
- Their email address, which only they give.
- Adding credit and raising the monthly budget, which only a person does. An assistant spends within the budget a person set, and may lower it.
- A yes before their own business is tracked as the workspace's brand.
- A workspace key, made by a member on Agents (https://parse.gl/app/settings/agents). A key is never pasted into a chat.

## More

Setup for each assistant: [Get started](https://parse.gl/docs/get-started.md). Prices and limits: [Spending, tracking and stopping](https://parse.gl/docs/credits.md) and [Plans and limits](https://parse.gl/docs/limits.md).
