Installation

Complete guide to installing and setting up the vCon MCP Server.

Prerequisites

Before you begin, ensure you have the following installed:

Required

• Node.js 18.0 or higher

  • Check version: node --version

  • Download: nodejs.org

• npm 9.0 or higher (comes with Node.js)

  • Check version: npm --version

• Git (for cloning the repository)

  • Check version: git --version

  • Download: git-scm.com

• Supabase Account (free tier available)

  • Sign up: supabase.com

Optional

• OpenAI API Key (for semantic search with embeddings)

  • Sign up: platform.openai.com

• Claude Desktop (for using the server with Claude AI)

  • Download: claude.ai/download

---

Installation Methods

Choose the installation method that best fits your needs:

• Method 1: Quick Install (Recommended)

• Method 2: Development Install

• Method 3: npm Global Install

• Method 4: Docker Install

---

Method 1: Quick Install (Recommended)

Perfect for getting started quickly with the server.

Step 1: Clone the Repository

# Clone from GitHub
git clone https://github.com/vcon-dev/vcon-mcp.git
cd vcon-mcp

# Or if using a different repository
git clone YOUR_REPOSITORY_URL
cd vcon-mcp

Step 2: Install Dependencies

npm install

This will install all required dependencies:

• @modelcontextprotocol/sdk - MCP protocol implementation

• @supabase/supabase-js - Supabase client

• zod - Runtime validation

• Development tools (TypeScript, Vitest, etc.)

Step 3: Set Up Environment Variables

# Copy the example environment file
cp .env.example .env

# Edit the .env file with your credentials
nano .env  # or use your preferred editor

Configure the following required variables:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here

Getting Supabase Credentials:

1. Go to supabase.com and sign in

2. Create a new project (or select existing)

3. Go to Settings → API

4. Copy the Project URL to SUPABASE_URL

5. Copy the anon public key to SUPABASE_ANON_KEY

Step 4: Set Up Database Schema

Run the database migrations to create the required tables:

# Option A: Using Supabase CLI (recommended)
npx supabase db push

# Option B: Manual via Supabase Dashboard
# 1. Go to your Supabase project
# 2. Navigate to SQL Editor
# 3. Run the migration files from supabase/migrations/ in order

Migration files included:

• 001_initial_schema.sql - Core vCon tables

• 002_indexes.sql - Performance indexes

• 003_rls_policies.sql - Row-level security

• 004_search_functions.sql - Full-text search

• 005_vector_extension.sql - Semantic search (optional)

Step 5: Build the Project

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Step 6: Verify Installation

# Run tests to verify everything works
npm test

# Run compliance tests
npm run test:compliance

✅ Installation complete! Proceed to Basic Usage.

---

Method 2: Development Install

For developers who want to contribute or modify the code.

Step 1: Fork and Clone

# Fork the repository on GitHub first
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/vcon-mcp.git
cd vcon-mcp

# Add upstream remote
git remote add upstream https://github.com/vcon-dev/vcon-mcp.git

Step 2: Install with Dev Dependencies

npm install

Step 3: Set Up Environment

cp .env.example .env
# Edit .env with your credentials

Step 4: Set Up Database

# Install Supabase CLI
npm install -g supabase

# Link to your project
supabase link --project-ref your-project-ref

# Push migrations
supabase db push

# Generate TypeScript types from database
supabase gen types typescript --local > src/types/database.ts

Step 5: Start Development Server

npm run dev

This starts the server in watch mode - changes will reload automatically.

Step 6: Run Tests in Watch Mode

npm test -- --watch

---

Method 3: npm Global Install

Install the server globally to use from anywhere (coming soon).

# Install globally from npm
npm install -g @vcon/mcp-server

# Create a configuration file
mkdir ~/.vcon-mcp
cat > ~/.vcon-mcp/config.json <<EOF
{
  "supabaseUrl": "https://your-project.supabase.co",
  "supabaseKey": "your-anon-key"
}
EOF

# Run the server
vcon-mcp-server

---

Method 4: Docker Install

Use Docker for containerized deployment. The vCon MCP Server is available on ECR Public.

Quick Start

# Pull the image
docker pull public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main

# Run the server
docker run -d -p 3000:3000 \
  -e SUPABASE_URL=https://your-project.supabase.co \
  -e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
  -e SUPABASE_ANON_KEY=your-anon-key \
  -e MCP_HTTP_STATELESS=true \
  public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main

Available Image Tags

Tag	Description
main	Latest stable build from main branch
main-<sha>	Specific commit (e.g., main-abc1234)
1.2.3, 1.2, 1	Semantic version releases

Running Scripts

The Docker image includes utility scripts:

# Show help and available commands
docker run --rm public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main help

# Check database status
docker run --rm \
  -e SUPABASE_URL=your-url \
  -e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
  -e SUPABASE_ANON_KEY=your-anon-key \
  public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main script check-db-status

# Run embeddings
docker run --rm \
  -e SUPABASE_URL=your-url \
  -e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
  -e SUPABASE_ANON_KEY=your-anon-key \
  -e OPENAI_API_KEY=your-openai-key \
  public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main script embed-vcons --provider=openai

Docker Compose

version: '3.8'
services:
  vcon-mcp:
    image: public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main
    ports:
      - "3000:3000"
    environment:
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_SERVICE_ROLE_KEY=${SUPABASE_SERVICE_ROLE_KEY}
      - SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
      - MCP_HTTP_STATELESS=true
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/api/v1/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Connecting to Local Services

When connecting to services running on your host machine (like local Supabase):

docker run -d -p 3000:3000 \
  -e SUPABASE_URL=http://host.docker.internal:54321 \
  -e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
  -e SUPABASE_ANON_KEY=your-anon-key \
  -e MCP_HTTP_STATELESS=true \
  public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main

Build Locally (Optional)

# Build from source
docker build -t vcon-mcp .

# Run local build
docker run -d -p 3000:3000 --env-file .env vcon-mcp

For complete Docker documentation, see the Docker Deployment Guide.

---

Configuring Claude Desktop

To use the vCon MCP Server with Claude Desktop:

Step 1: Locate Config File

The Claude Desktop configuration file location depends on your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Step 2: Edit Configuration

Add the vCon MCP Server to your configuration:

{
  "mcpServers": {
    "vcon": {
      "command": "node",
      "args": [
        "/absolute/path/to/vcon-mcp/dist/index.js"
      ],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_ANON_KEY": "your-anon-key-here"
      }
    }
  }
}

Important: Use the absolute path to your dist/index.js file.

To find the absolute path:

# In the vcon-mcp directory
pwd
# Example output: /Users/yourname/projects/vcon-mcp

# Your path will be: /Users/yourname/projects/vcon-mcp/dist/index.js

Step 3: Restart Claude Desktop

1. Quit Claude Desktop completely

2. Reopen Claude Desktop

3. Start a new conversation

4. The vCon tools should now be available

Step 4: Verify in Claude

Ask Claude:

What MCP tools do you have access to?

You should see vCon tools listed like:

• create_vcon

• get_vcon

• search_vcons

• add_analysis

• And more...

---

Optional: Semantic Search Setup

To enable AI-powered semantic search:

Step 1: Enable pgvector Extension

In your Supabase SQL Editor:

-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Verify installation
SELECT * FROM pg_extension WHERE extname = 'vector';

Step 2: Run Vector Migrations

# In Supabase SQL Editor, run:
supabase/migrations/005_vector_extension.sql
supabase/migrations/006_embeddings_table.sql

Step 3: Add OpenAI API Key

# Add to your .env file
echo "OPENAI_API_KEY=sk-your-openai-api-key" >> .env

Step 4: Generate Embeddings (Optional)

If you have existing vCons, generate embeddings:

npm run scripts/generate-embeddings-v2.ts

Now you can use semantic search tools like search_vcons_semantic and search_vcons_hybrid.

---

Troubleshooting

Error: "Cannot find module 'dotenv'"

Solution: Install dependencies

npm install

Error: "ENOENT: no such file or directory"

Solution: Make sure you built the project

npm run build

Error: "Invalid Supabase URL"

Solution: Check your .env file:

# Verify .env exists
cat .env

# Verify format (no quotes needed)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJ...

Error: "relation 'vcons' does not exist"

Solution: Run database migrations

# Using Supabase CLI
npx supabase db push

# Or manually in Supabase Dashboard SQL Editor

Error: "Permission denied" when running scripts

Solution: Make scripts executable

chmod +x scripts/*.sh

Claude Desktop doesn't show vCon tools

Checklist:

1. ✅ Built the project (npm run build)

2. ✅ Used absolute path in config

3. ✅ Restarted Claude Desktop completely

4. ✅ .env file in project root

5. ✅ Valid Supabase credentials

Debug:

# Test server directly
node dist/index.js

# Should output MCP initialization messages
# Press Ctrl+C to stop

Tests failing

# Clean and rebuild
rm -rf node_modules dist
npm install
npm run build

# Run tests with verbose output
npm test -- --reporter=verbose

Database connection issues

# Test Supabase connection
curl "https://your-project.supabase.co/rest/v1/" \
  -H "apikey: your-anon-key"

# Should return 200 OK

---

Environment Variables Reference

Complete list of supported environment variables:

Variable	Required	Description	Default
SUPABASE_URL	✅ Yes	Your Supabase project URL	-
SUPABASE_ANON_KEY	✅ Yes	Supabase anon public key	-
SUPABASE_SERVICE_ROLE_KEY	❌ No	Service role key (admin operations)	-
OPENAI_API_KEY	❌ No	OpenAI API key for embeddings	-
AZURE_OPENAI_EMBEDDING_ENDPOINT	❌ No	Azure OpenAI base endpoint (e.g., https://your-resource.openai.azure.com)	-
AZURE_OPENAI_EMBEDDING_API_KEY	❌ No	Azure OpenAI API key	-
VCON_PLUGINS_PATH	❌ No	Comma-separated plugin paths	-
VCON_LICENSE_KEY	❌ No	Enterprise license key	-
MCP_SERVER_NAME	❌ No	Server name for MCP	vcon-mcp-server
LOG_LEVEL	❌ No	Logging level (debug/info/warn/error)	info

---

Verifying Your Installation

Quick Verification Script

# Create a test script
cat > test-installation.sh <<'EOF'
#!/bin/bash

echo "=== vCon MCP Server Installation Check ==="
echo ""

# Check Node.js
echo "✓ Checking Node.js..."
node --version

# Check npm
echo "✓ Checking npm..."
npm --version

# Check if built
echo "✓ Checking build..."
if [ -f "dist/index.js" ]; then
  echo "  Build found: dist/index.js"
else
  echo "  ❌ Build not found. Run: npm run build"
fi

# Check .env
echo "✓ Checking environment..."
if [ -f ".env" ]; then
  echo "  .env file found"
else
  echo "  ❌ .env file missing. Run: cp .env.example .env"
fi

# Run tests
echo "✓ Running tests..."
npm test -- --run

echo ""
echo "=== Installation check complete ==="
EOF

chmod +x test-installation.sh
./test-installation.sh

Manual Verification

# 1. Check Node.js version (18+)
node --version

# 2. Check npm version (9+)
npm --version

# 3. Check dependencies installed
npm list --depth=0

# 4. Check build exists
ls -la dist/index.js

# 5. Check environment file
cat .env

# 6. Run compliance tests
npm run test:compliance

# 7. Test server startup
node dist/index.js
# Press Ctrl+C to stop after seeing initialization messages

---

Updating

To update to the latest version:

# Pull latest changes
git pull origin main

# Install any new dependencies
npm install

# Rebuild
npm run build

# Run migrations (if any)
npx supabase db push

# Test
npm test

---

Uninstalling

To completely remove the vCon MCP Server:

# 1. Remove Claude Desktop configuration
# Edit ~/Library/Application Support/Claude/claude_desktop_config.json
# Remove the "vcon" entry from mcpServers

# 2. Remove project directory
cd ..
rm -rf vcon-mcp

# 3. (Optional) Remove database in Supabase
# Go to Supabase Dashboard → Settings → General → Delete Project

---

Next Steps

Once installation is complete:

1. Basic Usage Guide - Learn to use the server

2. Search Guide - Master search capabilities

3. Tag Management - Organize your vCons

4. API Reference - Detailed tool documentation

---

Getting Help

If you encounter issues:

1. Check Troubleshooting section above

2. Search GitHub Issues

3. Ask in GitHub Discussions

4. Report bugs with detailed error messages

---

Installation successful? Continue to Basic Usage →