Connect via MCP

Onlook exposes a hosted MCP server at https://mcp.onlook.com/mcp. Once connected, your AI agent can list your projects, read the canvas, write code in the sandbox, capture screenshots, and more — no local server to run.

Authentication uses OAuth. The first time you connect, a browser window will open so you can authorize the client with your Onlook account.

Recommended: the Onlook CLI

The fastest way to connect is the first-party onlook CLI. It detects your installed agents (Cursor and Claude Code today) and wires the hosted server into each one's config for you — idempotently, leaving any other MCP servers you've configured untouched. No file editing, no scripts to trust.

You don't need a global install — run it straight through npx:

npx onlook@latest mcp add

This registers the onlook server (https://mcp.onlook.com/mcp) for every detected agent. To wire a specific agent, pass --agent:

# Wire just Cursor, or just Claude Code
npx onlook@latest mcp add --agent cursor
npx onlook@latest mcp add --agent claude-code

# Wire every supported agent without prompting
npx onlook@latest mcp add --agent '*' --yes

By default it writes project-scoped config; pass --global to wire your user-level config instead. Re-running is safe — it overwrites only the onlook entry and preserves everything else.

If you're setting up Onlook for the first time, onlook setup bundles sign-in, the Onlook skill, and MCP wiring into one guided flow:

npx onlook@latest setup

Restart your agent when it finishes. On first use, a browser window opens for OAuth consent.

Prefer to wire things by hand, or using an agent the CLI doesn't cover yet (Claude Desktop, Codex)? The per-client recipes below set up the exact same server manually.

Cursor

Cursor supports Streamable HTTP with native OAuth — just paste the URL.

Option A — Onlook CLI (recommended)

Let the CLI configure Cursor's mcp.json for you:

npx onlook@latest mcp add --agent cursor

Restart Cursor when it finishes.

Option B — Manual config

Open Cursor Settings → MCP → Add new MCP server and set:

Or add it directly to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "onlook": {
      "type": "http",
      "url": "https://mcp.onlook.com/mcp"
    }
  }
}

Restart Cursor. On first use, a browser window will open for OAuth consent.

Claude Desktop

Claude Desktop also supports Streamable HTTP with native OAuth.

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "onlook": {
      "type": "http",
      "url": "https://mcp.onlook.com/mcp"
    }
  }
}

Restart Claude Desktop. A browser window will open for OAuth consent on first use.

Codex Desktop

Codex Desktop's HTTP transport does not support OAuth natively. The workaround is the mcp-remote stdio adapter, which handles OAuth via a browser popup.

1. Find your npx path

If you installed Node via Homebrew, npx is already on the GUI PATH:

# Homebrew (Intel)
/usr/local/bin/npx

# Homebrew (Apple Silicon)
/opt/homebrew/bin/npx

If you installed Node via nvm, fnm, volta, or asdf, GUI apps like Codex Desktop cannot see npx because they don't inherit your shell PATH. Run this to find the absolute path:

which npx

Use the full path (e.g. /Users/you/.nvm/versions/node/v22.0.0/bin/npx) in the Command field below.

2. Add the server

Open Codex Desktop → Settings → MCP Servers → Add Server and fill in:

Why onlook-app instead of onlook? If a project-level .mcp.json already has an onlook entry with type: "http", Codex Desktop's parser may conflict with your global config and reject the entry. Using onlook-app avoids the collision.

3. Known issues

• Save button may not persist. If your entry disappears after saving, edit ~/.codex/config.toml directly (see the Codex CLI section below for the TOML format). This is a known Codex Desktop bug.
• npx not found. Double-check that you're using the absolute path from which npx, not just npx.

Codex CLI

Add the following to ~/.codex/config.toml:

[mcp_servers.onlook-app]
type = "stdio"
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.onlook.com/mcp"]

If you use nvm/fnm/volta/asdf and npx is not on your default PATH, use the absolute path:

[mcp_servers.onlook-app]
type = "stdio"
command = "/Users/you/.nvm/versions/node/v22.0.0/bin/npx"
args = ["-y", "mcp-remote", "https://mcp.onlook.com/mcp"]

ChatGPT Mobile / Claude Mobile

Not yet tested. These clients are a follow-up — check back soon or let us know if you get them working.

After connecting

Once your client is connected, your agent has access to all Onlook MCP tools. A typical first session looks like:

1. list_projects — see your projects and sandbox status.
2. connect — attach to a running project (auto-selects if only one is active).
3. get_context — pull a full snapshot of the canvas, design system, components, and errors.

From there you can build components, capture screenshots, update the canvas, and more. See the full tools reference for details.