> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velt.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Velt Installation MCP

> Use the Velt MCP server to install collaboration features into React and Next.js projects through your AI coding agent.

Install Velt collaboration features into your React or Next.js project through an AI coding agent. The Velt MCP (Model Context Protocol) server connects to editors like Claude Code, Cursor, and Windsurf, enabling guided installation with plan generation, codebase scanning, and user approval, all through natural conversation.

<Card title="GitHub Repository" icon="github" href="https://github.com/velt-js/velt-mcp-installer">
  velt-js/velt-mcp-installer
</Card>

## When to Use the MCP Installer

* You are using an AI coding agent (Claude Code, Cursor, Windsurf, or Claude Desktop)
* You want an interactive, guided setup with automatic codebase analysis
* You want the AI to generate an implementation plan before making changes
* You need help wiring Velt into an existing authentication system or document structure

<Info>
  For a non-interactive, terminal-based workflow, see the
  [CLI](/get-started/cli) page instead.
</Info>

## Prerequisites

* **Node.js** 18+
* An existing **React** or **Next.js** project (Next.js App Router, Pages Router, Vite + React, or Create React App)
* A [Velt API key and auth token](https://console.velt.dev)
* An MCP-compatible AI coding editor

### Recommended: Install Agent Skills

For the best results, install Velt Agent Skills before using the MCP installer. Skills give your AI agent access to verified Velt implementation patterns.

```bash theme={null}
npx skills add velt-js/agent-skills
```

See [Agent Skills](/get-started/skills) for details.

## Quickstart

### Step 1: Add the MCP Server

Add the Velt MCP server to your editor. The commands below use `npx` to automatically download and run `@velt-js/mcp-installer`. You can also install it globally with:

```bash theme={null}
npm install -g @velt-js/mcp-installer
```

<Tabs>
  <Tab title="Claude Code">
    Run this command in your terminal:

    ```bash theme={null}
    claude mcp add velt-installer -- npx -y @velt-js/mcp-installer
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project (or global config):

    ```json theme={null}
    {
      "mcpServers": {
        "velt-installer": {
          "command": "npx",
          "args": ["-y", "@velt-js/mcp-installer"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to your Windsurf MCP config:

    ```json theme={null}
    {
      "mcpServers": {
        "velt-installer": {
          "command": "npx",
          "args": ["-y", "@velt-js/mcp-installer"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    ```json theme={null}
    {
      "mcpServers": {
        "velt-installer": {
          "command": "npx",
          "args": ["-y", "@velt-js/mcp-installer"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other">
    The server runs over stdio. Use this command to start it:

    ```bash theme={null}
    npx -y @velt-js/mcp-installer
    ```

    Add it to your editor's MCP server configuration with `command: "npx"` and `args: ["-y", "@velt-js/mcp-installer"]`.
  </Tab>
</Tabs>

Restart your editor after adding the config.

### Step 2: Start the Installation

In your AI chat, say:

```
install velt
```

The AI will walk you through each step one at a time:

1. Confirm your project directory
2. Provide your Velt API key and auth token
3. Select features (or type **SKIP** for CLI-only mode)
4. Choose where to install `VeltProvider` (`app/page.tsx` recommended)
5. Choose corner position for Velt UI components
6. Review the implementation plan
7. Approve and apply changes

## Installation Modes

### Guided Mode (Default)

The guided mode generates a full implementation plan with codebase analysis before making any changes.

**Workflow:**

1. **Collect info**: the AI asks setup questions one at a time (project path, API key, auth token, features, provider location, corner position)
2. **Discovery consent**: the AI asks whether to scan your codebase for integration points (document ID sources, authentication patterns, JWT wiring)
3. **Verification**: if scanning is approved, the AI shows findings for you to confirm, edit, or override
4. **Plan generation**: a detailed implementation plan is generated based on your project structure and wiring data
5. **Apply**: after you approve the plan, the AI applies changes step by step
6. **Validation**: full QA validation runs automatically after installation

<Warning>
  The installer recommends placing `VeltProvider` in `app/page.tsx`, not
  `app/layout.tsx`. Follow this recommendation unless you have a specific reason
  to do otherwise.
</Warning>

### CLI-Only Mode (SKIP)

For experienced Velt developers who want the scaffold files without full integration:

1. At the feature selection step, type **SKIP**
2. The Velt CLI runs with core-only flags
3. You receive a TODO checklist for manual setup

Use this mode when you want to wire features yourself or just need the base files.

## Available Features

| Feature            | Description                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------- |
| Comments           | Inline comments with 8 types: freestyle, popover, page, text, inline, tiptap, lexical, slate |
| Presence           | Real-time user avatars and online status                                                     |
| Cursors            | Live cursor position tracking                                                                |
| Notifications      | Async collaboration notifications                                                            |
| Recorder           | Audio, video, and screen recording with playback                                             |
| CRDT               | Collaborative editing with Tiptap, CodeMirror, BlockNote, or ReactFlow                       |
| Single Editor Mode | Exclusive editing access: one user edits at a time, others view with live sync               |
| Self-Hosting Data  | Store comments, attachments, reactions, and user PII on your own database (PostgreSQL)       |
| Activity Logs      | Real-time activity feed showing comments, reactions, priority changes, recordings            |
| Huddle             | Audio, video, and screen sharing with ephemeral chat and flock mode                          |

## Codebase Discovery

In guided mode, the installer can automatically scan your project for integration points:

| Discovery Target        | What It Detects                                                                |
| ----------------------- | ------------------------------------------------------------------------------ |
| **Document ID**         | Dynamic route params (`[id]`), query params, state variables, database fetches |
| **User Authentication** | Next-Auth, Clerk, Auth0, Auth, Supabase Auth, custom auth                      |
| **JWT Authentication**  | Token generation endpoints, bearer auth patterns                               |
| **Setup Location**      | Root layout, specific pages, custom providers                                  |

Each finding includes a confidence level (HIGH, MEDIUM, LOW, NONE). For uncertain findings, the installer asks you to verify rather than guessing.

If you decline the codebase scan, the AI asks a manual questionnaire covering document ID source, user authentication, JWT setup, and component insertion location.

## Framework Support

| Framework              | Support | `"use client"` Directives |
| ---------------------- | ------- | ------------------------- |
| Next.js (App Router)   | Full    | Auto-applied              |
| Next.js (Pages Router) | Full    | N/A                       |
| Vite + React           | Full    | Not needed                |
| Create React App       | Full    | Not needed                |

## Generated Code Structure

After installation, the generated files follow this pattern:

```
app/
├── layout.tsx              # Wraps with AppUserProvider
├── page.tsx                # Contains VeltProvider with authProvider hook
└── userAuth/
    ├── AppUserContext.tsx   # User context provider
    └── useAppUser.tsx       # User data hook

components/velt/
├── VeltInitializeUser.tsx      # Exports useVeltAuthProvider hook
├── VeltInitializeDocument.tsx  # Exports useCurrentDocument hook
└── VeltCollaboration.tsx       # All Velt feature components

app/api/velt/token/
└── route.ts                # JWT token generation API (if JWT is configured)
```

## MCP Tools

The MCP server exposes these tools to your AI agent:

| Tool                       | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| `install_velt_interactive` | Unified installer with guided or CLI-only mode                    |
| `install_velt_freestyle`   | Legacy installer for basic freestyle comments                     |
| `take_project_screenshot`  | Capture a screenshot of your running app via Playwright           |
| `detect_comment_placement` | Analyze project structure to find the best locations for comments |

## Troubleshooting

### MCP server not loading

After adding the configuration, restart your editor. The MCP server runs over stdio and must be started by the editor process.

### AI not detecting the installer

Verify the MCP config is valid JSON and that `npx -y @velt-js/mcp-installer` runs successfully in your terminal. You can test with:

```bash theme={null}
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx -y @velt-js/mcp-installer
```

### Discovery scan returns low confidence

If the codebase scan cannot determine your document ID or auth setup with confidence, the AI will ask explicit follow-up questions. You can also choose the manual questionnaire path by declining the scan.

### Validation errors after installation

The installer runs QA validation automatically. Check the browser console for Velt-specific errors after starting your dev server. Common issues include missing API keys or incorrect document IDs.

## Next Steps

* **[Agent Skills](/get-started/skills)**: Install skills to improve AI-generated Velt code
* **[CLI](/get-started/cli)**: Terminal-based Velt setup without an AI agent
* **[Quickstart](/get-started/quickstart)**: Manual step-by-step Velt setup
* **[Comments Overview](/async-collaboration/comments/overview)**: Learn about commenting features
* **[Key Concepts](/key-concepts/overview)**: Understand documents, locations, users, and access control