Connect an AI agent

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

• Codex
• Claude
• Cursor
• GitHub Copilot in VS Code
• Gemini CLI
• MiMo Code
• Muse Code
• Grok Build
• Hermes Agent
• OpenClaw
• Other MCP clients

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, Claude Code, Cursor or another MCP client. 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. 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 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.

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 or browse the MCP tool catalog.

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 for parameters.