Velt Installation MCP

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.

GitHub Repository

velt-js/velt-mcp-installer

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

For a non-interactive, terminal-based workflow, see the CLI page instead.

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
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.

npx skills add velt-js/agent-skills

See Agent 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:

npm install -g @velt-js/mcp-installer

Claude Code
Cursor
Windsurf
Claude Desktop
Other

Run this command in your terminal:

claude mcp add velt-installer -- npx -y @velt-js/mcp-installer

Add to .cursor/mcp.json in your project (or global config):

{
  "mcpServers": {
    "velt-installer": {
      "command": "npx",
      "args": ["-y", "@velt-js/mcp-installer"]
    }
  }
}

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "velt-installer": {
      "command": "npx",
      "args": ["-y", "@velt-js/mcp-installer"]
    }
  }
}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "velt-installer": {
      "command": "npx",
      "args": ["-y", "@velt-js/mcp-installer"]
    }
  }
}

The server runs over stdio. Use this command to start it:

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"].

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:

Confirm your project directory
Provide your Velt API key and auth token
Select features (or type SKIP for CLI-only mode)
Choose where to install VeltProvider (app/page.tsx recommended)
Choose corner position for Velt UI components
Review the implementation plan
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:

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

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.

CLI-Only Mode (SKIP)

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

At the feature selection step, type SKIP
The Velt CLI runs with core-only flags
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:

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: Install skills to improve AI-generated Velt code
CLI: Terminal-based Velt setup without an AI agent
Quickstart: Manual step-by-step Velt setup
Comments Overview: Learn about commenting features
Key Concepts: Understand documents, locations, users, and access control

Get Started

Agentic Setup

Key Concepts

Async Collaboration

Realtime Collaboration

AI

Self-Host Data

Backend SDKs

Model Context Protocol

Webhooks

Security

Miscellaneous

Velt Installation MCP

GitHub Repository

When to Use the MCP Installer

Prerequisites

Recommended: Install Agent Skills

Quickstart

Step 1: Add the MCP Server

Step 2: Start the Installation

Installation Modes

Guided Mode (Default)

CLI-Only Mode (SKIP)

Available Features

Codebase Discovery

Framework Support

Generated Code Structure

MCP Tools

Troubleshooting

MCP server not loading

AI not detecting the installer

Discovery scan returns low confidence

Validation errors after installation

Next Steps

GitHub Repository

​When to Use the MCP Installer

​Prerequisites

​Recommended: Install Agent Skills

​Quickstart

​Step 1: Add the MCP Server

​Step 2: Start the Installation

​Installation Modes

​Guided Mode (Default)

​CLI-Only Mode (SKIP)

​Available Features

​Codebase Discovery

​Framework Support

​Generated Code Structure

​MCP Tools

​Troubleshooting

​MCP server not loading

​AI not detecting the installer

​Discovery scan returns low confidence

​Validation errors after installation

​Next Steps

When to Use the MCP Installer

Prerequisites

Recommended: Install Agent Skills

Quickstart

Step 1: Add the MCP Server

Step 2: Start the Installation

Installation Modes

Guided Mode (Default)

CLI-Only Mode (SKIP)

Available Features

Codebase Discovery

Framework Support

Generated Code Structure

MCP Tools

Troubleshooting

MCP server not loading

AI not detecting the installer

Discovery scan returns low confidence

Validation errors after installation

Next Steps