Installation

CLI Install (Fastest)

The quickest way to set up DeepSyte for a new agent is with the CLI. Use the one-command onboarding flow:

npx deepsyte setup --client codex     # or: cursor, vscode, windsurf, claude, claude-code

This will:

1. Open your browser to authenticate via OAuth if needed
2. Configure the MCP server in your chosen client
3. Install or repair the managed core DeepSyte skill in ~/.agents/skills/deepsyte, including workflows/sitewide-performance-audit/WORKFLOW.md

DeepSyte's canonical MCP endpoint is https://api.deepsyte.com/mcp. OAuth discovery should stay on https://api.deepsyte.com; the valid Railway service domain is https://screenshotsmcp-api-production.up.railway.app, and the old https://deepsyte-api-production.up.railway.app host must not be used.

Use this path when you want the fastest way to get browser truth into a fresh IDE, CLI, or MCP workflow.

If you prefer to do onboarding in two steps, you can still run:

npx deepsyte login
npx deepsyte install codex     # or: cursor, vscode, windsurf, claude, claude-code

That two-step path reaches the same result as setup --client <client> for most clients. The main nuances are that install codex writes ~/.codex/config.toml and asks you to run codex mcp login deepsyte, install vscode writes a workspace-local .vscode/mcp.json, while install claude-code prints the claude mcp add ... command for you to run manually.

The first packaged workflow is ~/.agents/skills/deepsyte/workflows/sitewide-performance-audit/WORKFLOW.md for repeatable multi-page performance audits.

deepsyte skills ... only manages that local core DeepSyte skill. To discover or install community skills from the wider agent ecosystem, use the find-skills workflow or npx skills find ... / npx skills add ....

You can also install it globally for ongoing use:

npm install -g deepsyte
deepsyte --help
deepsyte balance

For public sites, the CLI now mirrors the MCP remote browser workflow directly. Start a remote session, keep the returned sessionId, and continue with browse:* commands:

deepsyte browse https://example.com
deepsyte browse:click <sessionId> "Sign in"
deepsyte browse:console <sessionId> --level error
deepsyte browse:network-errors <sessionId>
deepsyte browse:a11y <sessionId>
deepsyte browse:perf <sessionId>
deepsyte browse:seo <sessionId>
deepsyte browse:close <sessionId>
deepsyte auth:test https://example.com
deepsyte auth:find-login https://example.com
deepsyte auth:smart-login https://example.com/sign-in --username user@example.com --password secret

For a simple localhost or private-page screenshot, authenticate first and use the normal screenshot command. DeepSyte automatically routes local-only URLs through an isolated managed local Chrome profile, uploads the evidence screenshot to R2, records the run in the dashboard, prints Run status: completed, and closes the one-shot browser cleanly. Agents should treat process exit code 0 plus Run status: completed as the completion signal:

deepsyte login
deepsyte screenshot http://localhost:3000 --no-full-page

If the CLI is not authenticated, it will tell agents to run npx deepsyte login and retry the exact command. Screenshot-derived commands such as screenshot, fullpage, responsive, mobile, tablet, element, batch, share, save, and baseline create/promote support local/private routing where implemented. Cloud-only workflows such as hosted reports, PDF rendering, and cloud UX review require public URLs or will print an authenticated local-browser instruction instead of trying to fetch localhost from the cloud.

For multi-step extension-free local browser workflows, authenticate first, then launch an installed browser in a dedicated DeepSyte profile:

deepsyte login
deepsyte whoami
deepsyte balance
deepsyte browser open http://localhost:3000 --yes
deepsyte browser open http://localhost:3000 --record-video --yes
deepsyte browser status
deepsyte browser goto https://example.org
deepsyte browser back
deepsyte browser forward
deepsyte browser screenshot --grid
deepsyte browser move-to 320 480
deepsyte browser click-at 320 480
deepsyte browser double-click-at 320 480
deepsyte browser right-click-at 320 480
deepsyte browser drag 320 480 520 620 --steps 16
deepsyte browser wheel --x 320 --y 480 --delta-y 600
deepsyte browser type "hello@example.com"
deepsyte browser hover ".menu-trigger"
deepsyte browser wait-for ".results-loaded" --timeout 8000
deepsyte browser select "select[name=country]" "Australia"
deepsyte browser viewport 393 852
deepsyte browser screenshot
deepsyte browser console --level error
deepsyte browser network-errors
deepsyte browser network-requests --resource-type fetch --min-duration 200
deepsyte browser evidence --label checkout-bug
deepsyte browser close --evidence --label checkout-bug
deepsyte browser cookies get
deepsyte browser storage getAll --type localStorage
deepsyte browser eval "document.title"
deepsyte browser a11y --max-depth 6
deepsyte browser perf
deepsyte browser seo
deepsyte browser close

The CLI explains why local access is needed, asks for explicit approval before it opens the browser, continuously captures console logs and network activity while that managed browser stays open, and then reconnects to that tracked session for follow-up local actions including history navigation, viewport-coordinate mouse control, hover states, wait conditions, dropdown selection, viewport changes, cookies/storage inspection, script evaluation, accessibility inspection, performance metrics, SEO auditing, and timestamped evidence bundle export. In deepsyte@1.21.7+, browser open returns immediately after the detached browser daemon and session are registered; it does not wait for an initial screenshot unless --initial-screenshot is passed. Agents should call browser screenshot --grid as the next command when they need visual coordinate proof, then use commands like move-to, click-at, drag, wheel, and focused type. browser open and intermediate browser ... commands leave the dashboard run active; browser close is the finalizer and prints Run status: completed. Use browser evidence for a live proof snapshot, or browser close --evidence when you want the finalized local .webm included in the same bundle after recording finishes.

Use remote browser workflows for public sites. Escalate to the managed local browser when the work requires localhost, intranet access, VPN-only apps, stronger realism, or explicit human approval. Managed local browser commands still require a valid DeepSyte website OAuth session.

For public interactive work, deepsyte browse <url> returns a CLI-safe run_... session ID and a dashboard Run URL. Always close it with deepsyte browse:close <sessionId>. In deepsyte@1.21.12+, navigation failures such as expired SSL certificates exit non-zero with a clear Browse failed: Error navigating: ... message instead of incomplete success output. Use one-shot screenshot or REST capture when no follow-up interaction is needed.

VS Code Extension Preview

A native DeepSyte VS Code extension is now being developed in the monorepo for a dedicated Activity Bar sidebar, automatic browser OAuth sign-in, automatic editor MCP setup, automatic managed core skill sync, command palette actions, output logs, a live activity timeline panel, and native MCP registration.

Current preview commands include:

• DeepSyte: Sign In
• DeepSyte: Check Status
• DeepSyte: Take Screenshot
• DeepSyte: Open Timeline
• DeepSyte: Configure Editor Integration
• DeepSyte: Sync Core Skill

The sidebar also surfaces quick actions and recent activity directly inside VS Code, and the extension opens the browser sign-in flow automatically when no credentials are stored. After sign-in, the extension also configures the matching MCP integration automatically when needed and repairs the managed core skill in ~/.agents/skills/deepsyte.

Until the Marketplace release is ready, install the preview VSIX and sign in once to let the extension configure the editor automatically. If you need to repair the setup later, use DeepSyte: Configure Editor Integration for the MCP connection or DeepSyte: Sync Core Skill for the managed local skill.

Manual Configuration

DeepSyte works with any client that supports the Model Context Protocol (MCP). Here's how to configure each one manually.

If you are setting up a new agent and want the managed core skill plus packaged workflows installed automatically, prefer npx deepsyte setup --client <client> before falling back to the manual snippets below.

Codex

Add native HTTP MCP config to ~/.codex/config.toml:

[mcp_servers.deepsyte]
url = "https://api.deepsyte.com/mcp"
scopes = ["mcp:tools"]
oauth_resource = "https://api.deepsyte.com/mcp"

Then trigger the website OAuth flow:

codex mcp login deepsyte

If OAuth opens a Railway 404 page, the MCP client has cached or generated a stale API URL. Replace it with https://api.deepsyte.com/mcp, then run codex mcp login deepsyte again.

When an agent tries a natural request such as "run an SEO test on example.com" before DeepSyte is connected, the MCP endpoint returns a 401 that includes mcp_url, login_url, setup_url, codex_login_command, and a public tool_catalog. The catalog is only for cold discovery; tool execution still requires website OAuth and a dso_... Bearer token. The useful recovery is to add the config above and run codex mcp login deepsyte; do not use a Railway URL.

If a future Codex agent has no DeepSyte memory, it should discover common post-auth tools from the skill or metadata, including screenshot_fullpage, take_screenshot, browser_navigate, browser_screenshot, browser_seo_audit, responsive_audit, ux_review, and extract_text_from_image. If OAuth succeeds but the running thread still does not expose mcp__deepsyte__* tools, start a fresh Codex thread or a narrow codex exec run because tool namespaces may not hot-reload mid-thread.

Restart Codex Desktop or reload MCP servers, then ask:

Use DeepSyte to take a full-page screenshot of https://clerk.com

If OAuth completes but mcp__deepsyte tools do not mount in a fresh Codex thread, use this temporary bridge while keeping website OAuth mandatory:

[mcp_servers.deepsyte]
command = "npx"
args = ["-y", "mcp-remote@0.1.38", "https://api.deepsyte.com/mcp"]

Cursor

Open Cursor Settings → MCP Servers, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "deepsyte": {
      "url": "https://api.deepsyte.com/mcp"
    }
  }
}

Windsurf

Open Windsurf Settings → MCP, or edit the config file:

{
  "mcpServers": {
    "deepsyte": {
      "serverUrl": "https://api.deepsyte.com/mcp"
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (found in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "deepsyte": {
      "url": "https://api.deepsyte.com/mcp"
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings (.vscode/mcp.json):

{
  "mcpServers": {
    "deepsyte": {
      "url": "https://api.deepsyte.com/mcp"
    }
  }
}

This file is workspace-local, so repeat this step for each workspace that should have DeepSyte enabled.

Any MCP Client

The server endpoint is:

https://api.deepsyte.com/mcp

It supports Streamable HTTP transport — compatible with all MCP clients that support HTTP-based servers.

If an older MCP client rejects HTTP transport with an error such as "this server does not support HTTP transport, try SSE", use the legacy fallback endpoint instead:

https://api.deepsyte.com/sse

The SSE endpoint is still website-OAuth gated and should only be used when the client cannot use https://api.deepsyte.com/mcp.

Verify Installation

After configuring, ask your AI assistant:

Open https://example.com, inspect the page, and tell me what you see

Then try a verification-oriented task:

Test my sign-in flow and capture proof if anything fails

If you get browser output and evidence-rich results back, you're all set.

Available Tools

Once connected, your AI assistant has access to 87 registered core MCP tools. Common tools include:

The full DeepSyte ecosystem has 157 distinct MCP tool names: 79 web/API tools plus 78 native mobile tools. The core API MCP also exposes 8 mobile setup bridge helpers, so its registration count is 87.