# Connect an AI agent

Reconstruct exposes captured interface data through an MCP server. Choose your agent for setup instructions:

- [Codex](./agents/codex.md)
- [Claude](./agents/claude.md)
- [Cursor](./agents/cursor.md)
- [GitHub Copilot in VS Code](./agents/vscode-copilot.md)
- [Gemini CLI](./agents/gemini-cli.md)
- [MiMo Code](./agents/mimo-code.md)
- [Muse Code](./agents/muse-code.md)
- [Grok Build](./agents/grok-build.md)
- [Hermes Agent](./agents/hermes.md)
- [OpenClaw](./agents/openclaw.md)
- [Other MCP clients](./agents/other-mcp-clients.md)

## Before you start

The Reconstruct MCP endpoint is **`https://reconstruct.dev/mcp`** and uses **Streamable HTTP**. You can connect with browser sign-in through OAuth or with a personal access token.

| Method | How it works | When to use it |
|---|---|---|
| **OAuth browser sign-in** | Your MCP client opens Reconstruct sign-in in a browser. Sign in and approve access, then return to the client. No token needs to be created or copied from the Platform. | Interactive agents and editors with OAuth support. |
| **Personal access token** | Create an MCP token in Platform settings and add it to the client’s credentials. | Clients without OAuth support or automated environments without browser sign-in. |

Both methods connect to the same MCP server and use your Reconstruct account’s subscription and usage allowance.

## OAuth browser sign-in

You do not need to issue a personal token on the Platform before connecting through OAuth.

1. Add `https://reconstruct.dev/mcp` as a remote HTTP MCP server in your client.
2. Select OAuth or browser sign-in. If the client asks for connection settings, use the values below.
3. Start **Sign in**, **Connect** or the client’s MCP login command. The exact action depends on your client.
4. In the browser, sign in to your Reconstruct account and approve the requested access. If registration is unavailable, contact support for account access.
5. Return to the client and refresh its tools. Ask it to call `list_products` to confirm the connection.

| Setting | Value |
|---|---|
| Server URL | `https://reconstruct.dev/mcp` |
| Transport | Streamable HTTP |
| OAuth client ID | `reconstruct-mcp` for pre-configured clients; Claude Desktop registers automatically |
| Scopes | `openid aud-mcp` |
| Client secret | Leave empty |
| OAuth issuer | `https://reconstruct.dev/sso/realms/reconstruct` |
| Authorization endpoint | `https://reconstruct.dev/sso/realms/reconstruct/protocol/openid-connect/auth` |
| Token endpoint | `https://reconstruct.dev/sso/realms/reconstruct/protocol/openid-connect/token` |

The client obtains and stores its OAuth credentials after sign-in and uses them for MCP calls. You do not need to copy a token or set `CR_RECONSTRUCT_MCP_TOKEN` for this method. Remove any manually configured `Authorization` header or bearer-token setting when switching an existing connection to OAuth.

See the OAuth setup examples for [Codex](./agents/codex.md#oauth-browser-sign-in), [Claude Code](./agents/claude-code.md#oauth-browser-sign-in), [Cursor](./agents/cursor.md#oauth-browser-sign-in) or [another MCP client](./agents/other-mcp-clients.md#oauth-browser-sign-in). Use the callback settings documented for your client. If the client asks you to sign in again, repeat its MCP login flow.

### Client compatibility

The browser sign-in examples cover Claude, Cursor, Claude Code, Codex, Grok Build and Muse Code with their registered callback addresses. The Gemini CLI, VS Code, MiMo Code, Hermes Agent and OpenClaw guides use personal access tokens. Claude Desktop and the web connector support automatic client registration with an approved exact HTTPS callback. Other clients use the pre-configured public client and callback settings in their guides.

OAuth endpoints come from discovery metadata. They are below the SSO realm, not `/authorize` or `/token` at the website root. If a client opens a root endpoint, reload its server configuration and repeat sign-in to refresh cached discovery.

For Claude’s cloud connector, follow the [Claude Desktop guide](./agents/claude-desktop.md). Contact support with the exact callback URI before connecting a different cloud integration. No client secret should be entered for `reconstruct-mcp`.

## Agent discovery and device sign-in

Public discovery starts at `https://reconstruct.dev/mcp/server-card`. The root
`/.well-known/api-catalog` lists public API documentation, and
`/.well-known/agent-skills/index.json` links to a skill for inspecting captured interfaces.
Published website pages and documentation accept `Accept: text/markdown`.
Workspace pages still require account access.

Clients that implement OAuth Device Authorization can read `https://reconstruct.dev/auth.md`
and POST `{"type":"anonymous"}` to `https://reconstruct.dev/agent/register`.
The response contains a pending device authorization, a user verification URL and code,
expiry, polling interval, and a private PKCE `code_verifier`.
Show the verification instructions to the user. The user must sign in and approve access.
The agent then polls the issuer's token endpoint using the device-code grant and the returned
`code_verifier`. Respect the polling interval and `slow_down` responses.
Registration itself does not issue an access token or create an account.
Existing roles, subscription limits and consent requirements remain in force.

Keep device codes, code verifiers and tokens private. Never approve access on the user's behalf.
This flow is available to clients that implement it; it does not replace an editor's existing
Authorization Code + PKCE setup.

## Personal access token

1. Sign in to the [Reconstruct Platform](https://reconstruct.dev/platform/) and open **Settings → API tokens**.
2. Create a token with the **MCP** scope (`mcp`) and copy its secret when shown.
3. Configure the client to send `Authorization: Bearer <token>`. If it reads the token from an environment variable, use `CR_RECONSTRUCT_MCP_TOKEN`.
4. Connect and ask the client to call `list_products`.

Keep the token in a local secret or client credential store. If it expires or is revoked, create a replacement in Platform settings and update the client’s credentials.

## Select captured data

Start with `list_products`, `list_platforms`, and `list_versions`. Choose platform
types and environments from `list_platforms.options.platforms[]`, using the
returned IDs. `list_platforms.platforms[]` contains pairs with actual captured data. Use the exact saved `view` key from
`list_pages.views[]` for page tools. Pass `environment` explicitly when a version
contains several environments.
Context tools require available subscription usage and consume one context read
when a call is accepted, including cached results. An accepted call still counts
if it later fails. Discovery, image tools and asset downloads do not
consume context reads. See [usage limits](./mcp-tools.md#usage-limits).

## Troubleshooting

| Symptom | Check |
|---|---|
| `401 Unauthorized` | Complete OAuth sign-in or check the personal token; replace it if expired or revoked. |
| `/authorize` returns 404 | Refresh the connection metadata and repeat sign-in; the authorization endpoint is below `https://reconstruct.dev/sso/realms/reconstruct`. |
| `invalid_scope` | Request `openid aud-mcp`; Grok Build may also request the optional `offline_access` scope. |
| Authentication required after sign-in | Refresh the server and repeat its OAuth login. Remove conflicting manually configured bearer credentials. |
| OAuth redirect mismatch | Use the callback port documented for your client. If the error persists, contact support with the callback URI shown by the client. |
| Dynamic client registration rejected | In Claude Desktop, select **Register automatically** and retry after a minute. For other clients, follow their guide’s pre-configured OAuth settings. |
| Server cannot connect | Confirm `https://reconstruct.dev/mcp` is reachable from the agent's machine. |
| Tools return access denied | Sign in with your Reconstruct account and check your subscription. Contact support if access remains unavailable. |
| Quota or usage unavailable | Check usage in account settings and the status page. Retry when access is available. |
| Several environments are captured | Supply `environment` from `list_versions`. |
| Requested platform/view unavailable | Use the captured platform/environment pairs and exact `list_pages.views[]` keys; supported options do not guarantee stored data. |
| No tools appear | Restart the agent or refresh its MCP tool list, then check server status. |

Once connected, try the [prompt examples](./prompt-examples.md) or browse the [MCP tool catalog](./mcp-tools.md).

### Request a new capture or update

The MCP server includes `get_request_options`, `create_product_request`,
`get_product_request`, `list_product_requests` and `wait_product_request`. Sign in
through OAuth or use an MCP access token. Your subscription must support requests,
and you can only view requests submitted with your account.
Ask the agent to submit a new product URL, or update a known published product key;
then have it retain `requestId` and wait for review status changes. An approved request
does not mean the capture is ready yet. See [the request tools](./mcp-tools.md#product-requests) for parameters.