MCP Server

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools. By running the PreviewDrop MCP server, you give any compatible AI agent (Claude, Cursor, etc.) the ability to manage your preview environments directly from the chat — no context-switching, no copy-pasting URLs.

Quick start

1. Install the CLI

bash
npm i -g previewdrop
# or use without installing:
npx previewdrop mcp

2. Authenticate

bash
previewdrop login
# or set the env var directly:
export PREVIEWDROP_API_KEY=pd_live_xxx

3. Add to Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add:

json
{
  "mcpServers": {
    "previewdrop": {
      "command": "npx",
      "args": ["previewdrop", "mcp"],
      "env": {
        "PREVIEWDROP_API_KEY": "pd_live_xxx"
      }
    }
  }
}

Restart Claude Desktop. The PreviewDrop tools will appear in the tool list.

4. Add to VS Code (one-click)

Install the PreviewDrop extension from the VS Code Marketplace — or search previewdrop in the MCP Servers panel inside VS Code. The extension registers the MCP server automatically; no config file editing needed.

5. Add to Cursor

Open Cursor → Settings → MCP and add a new server:

json
{
  "previewdrop": {
    "command": "npx previewdrop mcp",
    "env": { "PREVIEWDROP_API_KEY": "pd_live_xxx" }
  }
}

Available tools

Once connected, the AI can use these tools:

• get_account — Returns your account email, plan, and tenant name.
• list_projects — Lists all projects in your workspace.
• list_deployments — Lists deployments, filterable by project, branch, or status.
• get_deployment — Gets full details of a specific deployment by ID.
• deploy — Triggers a new preview for a project + branch. Pass wait: true to block until it's ready (up to 5 min).
• redeploy — Redeploys an existing deployment (same project + branch).
• destroy_deployment — Stops and removes a deployment by ID.
• get_build_logs — Fetches nixpacks/Dockerfile build output for a deployment. Supports tail to limit lines.
• get_runtime_logs — Fetches container stdout/stderr. Supports tail.
• create_project — Adds a new GitHub repository as a PreviewDrop project. Requires the GitHub App to be installed on the repo's owner account first.
• get_github_app_install_url — Returns the GitHub URL to install the PreviewDrop GitHub App. The AI calls this automatically when create_project returns a 403.
• deploy_repo — Single-shot tool. Give it an owner/repo and optional branch — it finds or creates the project automatically, deploys, waits, and returns the live URL. Use this when the user says "preview my project".

Natural language workflow (“preview my project”)

The deploy_repo tool is designed for exactly this. The AI reads the git remote from your workspace, then handles everything in one call:

text
You:  Preview the Quick Invoice project on the current branch.

AI:   [reads .git/config — remote origin = acme/quick-invoice]
      [calls deploy_repo — githubRepo: acme/quick-invoice, branch: feature/stripe-v2]

      (First time: project didn't exist — created it automatically.)

      Status: ready
      Preview URL: https://prv-7c1a3f2.previews.previewdrop.dev
      Built in 52s

If the GitHub App is not installed yet, deploy_repo surfaces the install URL automatically — no extra steps needed from you.

First-time setup with a new repo

If you haven't added your project to PreviewDrop yet, the AI agent can do it for you in one step. The only prerequisite is that the PreviewDrop GitHub App is installed on your GitHub account or organisation.

The typical flow looks like this:

text
You:  I want to preview my repo acme/payments-api on the current branch.

AI:   [calls create_project — githubRepo: acme/payments-api]
      Project created! ID: proj_f4e2a1c
      [calls deploy — projectId: proj_f4e2a1c, branch: feature/stripe, wait: true]
      Preview is live:
      https://prv-9a3c7f1.previews.previewdrop.dev

If the GitHub App is not yet installed, the AI will automatically call get_github_app_install_url and give you the direct link:

text
AI:   The GitHub App isn't installed yet. Install it here:
      https://github.com/apps/previewdrop/installations/new
      Grant access to acme/payments-api, then tell me and I'll create the project.

Example conversation

text
You:  Deploy the feature/payments branch of my checkout project
      and wait for it to be ready.

AI:   [calls deploy — projectId: proj_abc, branch: feature/payments, wait: true]

      Your preview is live:
      https://prv-d94f2c1.previews.previewdrop.dev
      Status: ready · Built in 47s

You:  Show me the last 30 lines of the build log.

AI:   [calls get_build_logs — id: dep_d94f2c1, tail: 30]

      … nixpacks output …
      ✓ Build complete in 47s

Configuration options

• PREVIEWDROP_API_KEY — API key for authentication. Takes precedence over the saved config from previewdrop login.
• --host <url> — Override the API host (default: https://previewdrop.dev). Useful for self-hosted deployments.

bash
# Custom host example
npx previewdrop mcp --host https://your.previewdrop.instance

Publishing your own MCP server

The PreviewDrop MCP server is distributed as part of the previewdrop npm package — no separate package needed. This means:

• Users install once (npm i -g previewdrop) and get both the CLI and the MCP server.
• The MCP server is always in sync with the CLI version.
• No separate npm publish step is required for the MCP server itself.

Troubleshooting

Claude says "no tools available"

Restart Claude Desktop after editing the config file. The MCP server connection is established at startup.

Authentication errors

Run previewdrop login to refresh your token, or check that PREVIEWDROP_API_KEY is set correctly in the MCP server env block.

Server won't start

Test the server directly in your terminal:

bash
PREVIEWDROP_API_KEY=pd_live_xxx npx previewdrop mcp
# Should hang waiting for stdin — that means it started correctly.
# Ctrl+C to exit.