MCP setup

Register a client

Use macOS with Node.js 22.23 or later. Install the global executable:

npm install -g previewhost

Choose your client below. These registrations work across projects without a repository list. --allow-exec permits trusted commands, managed databases, and private secret setup with your user permissions. It provides no sandbox.

Codex

Run in your terminal:

codex mcp add previewhost -- previewhost mcp --allow-exec

Cursor

Add this server to ~/.cursor/mcp.json. Preserve any other servers in the file:

{
  "mcpServers": {
    "previewhost": {
      "command": "previewhost",
      "args": ["mcp", "--allow-exec"]
    }
  }
}

Enable Previewhost in Cursor's MCP settings.

Claude Code

Run in your terminal:

claude mcp add --scope user previewhost -- previewhost mcp --allow-exec

Client approval behavior varies. Integrations lists tested versions and limits. If the client cannot find the executable, check its PATH.

Preview an application

In your project chat, ask:

Preview this application with Previewhost. Read its instructions and start commands,
reuse the project configuration if present, and verify the returned URL in a browser.

The agent supplies the actual project path on each call. preview_access asks you to approve that project and any additional source directories. Your client can also require approval for individual tools.

The agent can reuse root preview.yaml, fall back to preview.yml, or supply a spec directly. If both files exist, the agent must report the conflict instead of choosing silently. You do not need to write a file first. An invalid existing file is an error. To keep a working spec for later use, ask the agent to save it as preview.yaml.

For stored secrets or managed databases, use private setup to approve references and create or unlock the owner’s keystore session. Enter the password and missing values only in that form. Dashboard unlock does not unlock the project owner. If the agent turn ended before you saved, tell it to continue after the save. See Secrets.

Understand what stays running

The MCP adapter connects to a persistent owner for each project. An agent pause or MCP disconnection does not stop the previews. Reconnection needs project approval again. An existing owner's secret approvals last until that owner shuts down.

After startup, check the application at the returned URL. If a request fails, ask the agent to read logs. Run previewhost dashboard in another terminal to inspect previews across projects. To finish, ask the agent to stop the preview. Owner shutdown stops every preview in that project.

Add databases

Managed PostgreSQL and Redis need a local Docker Engine and downloaded images. Follow Databases, including the socket override for other local Engines.

Optional agent skill

The optional Previewhost agent skill provides recipe and recovery guidance. It ships under dist/skills/previewhost in the npm package. Install it through your client's skill mechanism. MCP registration does not install the skill, and the tools work without it.

For tool parameters and restricted roots, use the MCP reference.