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.
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
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
command: "npx" and args: ["-y", "@velt-js/mcp-installer"]. Step 2: Start the Installation
In your AI chat, say:
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 | Session recording and playback |
| CRDT | Collaborative editing with Tiptap, CodeMirror, BlockNote, or ReactFlow |
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, Firebase Auth, Supabase Auth, custom auth |
| JWT Authentication | Token generation endpoints, bearer auth patterns |
| Setup Location | Root layout, specific pages, custom providers |
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)
| 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
