Configuration

Complete configuration guide for vMCP.

Environment Variables

Backend Configuration

Create a .env file in the backend/ directory:

# Database
DATABASE_URL=postgresql://vmcp:vmcp@localhost:5432/vmcp

# Server
HOST=0.0.0.0
PORT=8000

# Logging
LOG_LEVEL=INFO

# Frontend
FRONTEND_DIR=../frontend/dist

# CORS (Optional)
CORS_ORIGINS=http://localhost:3000,http://localhost:8000

Database Configuration

PostgreSQL Connection String Format

postgresql://[user]:[password]@[host]:[port]/[database]

Examples:

Local development:

DATABASE_URL=postgresql://vmcp:vmcp@localhost:5432/vmcp

Docker container:

DATABASE_URL=postgresql://vmcp:vmcp@postgres:5432/vmcp

Cloud hosted (with SSL):

DATABASE_URL=postgresql://user:pass@host.com:5432/db?sslmode=require

Connection Pool Settings

For high-traffic deployments, configure the connection pool in backend/vmcp/database.py:

engine = create_async_engine(
    DATABASE_URL,
    echo=False,
    pool_size=20,        # Number of persistent connections
    max_overflow=10,     # Max additional connections
    pool_timeout=30,     # Seconds to wait for connection
    pool_recycle=3600,   # Recycle connections after 1 hour
)

Logging Configuration

Log Levels

LOG_LEVEL=DEBUG   # Verbose, shows all operations
LOG_LEVEL=INFO    # Standard operational info (recommended)
LOG_LEVEL=WARNING # Only warnings and errors
LOG_LEVEL=ERROR   # Only errors

Structured Logging

vMCP uses structured logging. Configure in backend/vmcp/logging_config.py:

LOGGING_CONFIG = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "default": {
            "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
        },
        "json": {
            "()": "pythonjsonlogger.jsonlogger.JsonFormatter",
            "format": "%(asctime)s %(name)s %(levelname)s %(message)s"
        }
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "default",
            "stream": "ext://sys.stdout"
        },
        "file": {
            "class": "logging.handlers.RotatingFileHandler",
            "formatter": "json",
            "filename": "logs/vmcp.log",
            "maxBytes": 10485760,  # 10MB
            "backupCount": 5
        }
    },
    "root": {
        "level": "INFO",
        "handlers": ["console", "file"]
    }
}

CORS Configuration

For frontend development or custom domains:

CORS_ORIGINS=http://localhost:3000,http://localhost:8000,https://vmcp.yourdomain.com

In production, restrict to your domain:

CORS_ORIGINS=https://vmcp.yourdomain.com

Docker Configuration

docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: vmcp
      POSTGRES_PASSWORD: vmcp
      POSTGRES_DB: vmcp
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-LABEL", "pg_isready", "-U", "vmcp"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      DATABASE_URL: postgresql://vmcp:vmcp@postgres:5432/vmcp
      LOG_LEVEL: INFO
      HOST: 0.0.0.0
      PORT: 8000
    ports:
      - "8000:8000"
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      # Mount for development
      - ./backend:/app/backend
      - ./frontend/dist:/app/frontend/dist

volumes:
  postgres_data:

Environment Overrides

Override environment variables:

# Single variable
DATABASE_URL=postgresql://custom@localhost/db docker compose up

# Environment file
docker compose --env-file .env.production up

Frontend Configuration

Vite Configuration

The frontend build configuration is in frontend/vite.config.ts:

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true,
      },
    },
  },
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
    sourcemap: false,
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom'],
          'ui-vendor': ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
        },
      },
    },
  },
})

API Configuration

Update API base URL in frontend/src/lib/api.ts:

const API_BASE_URL = import.meta.env.VITE_API_URL || '/api'

// For development with separate backend:
// VITE_API_URL=http://localhost:8000/api

MCP Server Configuration

Server Transport Types

Stdio (Command-line)

{
  "transport_type": "stdio",
  "config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
    "env": {
      "VAR_NAME": "value"
    },
    "cwd": "/working/directory"
  }
}

HTTP

{
  "transport_type": "http",
  "config": {
    "url": "https://api.example.com/mcp",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer token",
      "Content-Type": "application/json"
    },
    "timeout": 30
  }
}

SSE (Server-Sent Events)

{
  "transport_type": "sse",
  "config": {
    "url": "https://sse.example.com/events",
    "headers": {
      "Authorization": "Bearer token"
    },
    "reconnect": true,
    "reconnect_interval": 5
  }
}

OAuth Configuration

For MCP servers requiring OAuth:

{
  "oauth": {
    "provider": "github",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scopes": ["repo", "user"],
    "redirect_uri": "http://localhost:8000/oauth/callback"
  }
}

Production Deployment

Recommended Settings

# Production .env
DATABASE_URL=postgresql://vmcp:secure_password@db.internal:5432/vmcp?sslmode=require
LOG_LEVEL=WARNING
HOST=0.0.0.0
PORT=8000
CORS_ORIGINS=https://vmcp.yourdomain.com

Security Considerations

1. Use strong database passwords
2. Enable SSL for database connections (?sslmode=require)
3. Restrict CORS origins to your domain only
4. Use environment variables for secrets (never commit .env)
5. Enable HTTPS with reverse proxy (nginx, Caddy)

Reverse Proxy (nginx)

server {
    listen 80;
    server_name vmcp.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name vmcp.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /api {
        proxy_pass http://localhost:8000/api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Performance Tuning

Database Indexes

Add indexes for frequently queried fields:

CREATE INDEX idx_vmcp_user_id ON vmcps(user_id);
CREATE INDEX idx_mcp_server_user_id ON mcp_servers(user_id);
CREATE INDEX idx_logs_timestamp ON logs(timestamp);
CREATE INDEX idx_logs_vmcp_id ON logs(vmcp_id);

Cache Configuration

Configure Redis for caching (optional):

REDIS_URL = os.getenv("REDIS_URL", "redis://localhost:6379/0")

# Cache tool results for 5 minutes
TOOL_CACHE_TTL = 300

# Cache resource reads for 10 minutes
RESOURCE_CACHE_TTL = 600

Worker Configuration

For high concurrency:

# Run with multiple workers
uvicorn vmcp.main:app --workers 4 --host 0.0.0.0 --port 8000

Monitoring

Health Check Endpoint

GET /health

Returns:

{
  "status": "healthy",
  "database": "connected",
  "version": "1.0.0"
}

Metrics (Prometheus)

Enable Prometheus metrics:

from prometheus_fastapi_instrumentator import Instrumentator

Instrumentator().instrument(app).expose(app)

Access metrics at:

GET /metrics

Backup and Recovery

Database Backup

# Backup
pg_dump -h localhost -U vmcp -d vmcp > backup.sql

# Restore
psql -h localhost -U vmcp -d vmcp < backup.sql

Automated Backups

#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
pg_dump -h localhost -U vmcp -d vmcp | gzip > backups/vmcp_$DATE.sql.gz

# Keep only last 7 days
find backups/ -name "vmcp_*.sql.gz" -mtime +7 -delete

Run daily with cron:

0 2 * * * /path/to/backup.sh

Next Steps

• API Reference
• Deployment Guide
• Troubleshooting