Skip to main content

​
Database Configuration for MCPHub

​
Overview

MCPHub supports storing configuration data in a PostgreSQL database as an alternative to the mcp_settings.json file. Database mode provides enhanced persistence and scalability for production environments and enterprise deployments.

​
Why Use Database Configuration?

Core Benefits:
  • ✅ Better Persistence - Configuration stored in a professional database with transaction support and data integrity
  • ✅ High Availability - Leverage database replication and failover capabilities
  • ✅ Enterprise Ready - Meets enterprise data management and compliance requirements
  • ✅ Backup & Recovery - Use mature database backup tools and strategies

​
Environment Variables

​
Required for Database Mode

# Database connection URL (PostgreSQL)
# Simply setting DB_URL will automatically enable database mode
DB_URL=postgresql://user:password@localhost:5432/mcphub

# Or explicitly control with USE_DB (overrides auto-detection)
# USE_DB=true
Simplified Configuration: You only need to set DB_URL to enable database mode. MCPHub will automatically detect and enable database mode when DB_URL is present. Use USE_DB=false to explicitly disable database mode even when DB_URL is set.

​
Setup Instructions

​
1. Using Docker

​
Option A: Using External Database

If you already have a PostgreSQL database: 
docker run -d \
  -p 3000:3000 \
  -v ./mcp_settings.json:/app/mcp_settings.json \
  -e DB_URL="postgresql://user:password@your-db-host:5432/mcphub" \
  samanhappy/mcphub

​
Option B: Using PostgreSQL as a separate service

Create a docker-compose.yml: 
version: '3.8'

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: mcphub
      POSTGRES_USER: mcphub
      POSTGRES_PASSWORD: your_secure_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  mcphub:
    image: samanhappy/mcphub:latest
    environment:
      USE_DB: "true"
      DB_URL: "postgresql://mcphub:your_secure_password@postgres:5432/mcphub"
      PORT: 3000
    ports:
      - "3000:3000"
    depends_on:
      - postgres

volumes:
  pgdata:
Run with: 
docker-compose up -d

​
2. Manual Setup

​
Step 1: Setup PostgreSQL Database

# Install PostgreSQL (if not already installed)
sudo apt-get install postgresql postgresql-contrib

# Create database and user
sudo -u postgres psql <<EOF
CREATE DATABASE mcphub;
CREATE USER mcphub WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE mcphub TO mcphub;
EOF

​
Step 2: Install MCPHub

npm install -g @samanhappy/mcphub

​
Step 3: Set Environment Variables

Create a .env file: 
# Simply set DB_URL to enable database mode (USE_DB is auto-detected)
DB_URL=postgresql://mcphub:your_password@localhost:5432/mcphub
PORT=3000

​
Step 4: Run Migration (Optional)

If you have an existing mcp_settings.json file, migrate it: 
# Run migration script
npx tsx src/scripts/migrate-to-database.ts
Or let MCPHub auto-migrate on first startup.

​
Step 5: Start MCPHub

mcphub

​
Migration from File-Based to Database

MCPHub provides automatic migration on first startup when database mode is enabled. However, you can also run the migration manually.

​
Automatic Migration

When you start MCPHub with USE_DB=true for the first time:
  1. MCPHub connects to the database
  2. Checks if any users exist in the database
  3. If no users found, automatically migrates from mcp_settings.json
  4. Creates all tables and imports all data

​
Manual Migration

Run the migration script: 
# Using npx
npx tsx src/scripts/migrate-to-database.ts

# Or using Node
node dist/scripts/migrate-to-database.js
The migration will:
  • ✅ Create database tables if they don’t exist
  • ✅ Import all users with hashed passwords
  • ✅ Import all MCP server configurations
  • ✅ Import all groups
  • ✅ Import system configuration
  • ✅ Import user-specific configurations
  • ✅ Skip existing records (safe to run multiple times)

​
Configuration After Migration

Once running in database mode, all configuration changes are stored in the database:
  • User management via /api/users
  • Server management via /api/servers
  • Group management via /api/groups
  • System settings via /api/system/config
The web dashboard works exactly the same way, but now stores changes in the database instead of the file.

​
Database Schema

MCPHub creates the following tables:
  • users - User accounts and authentication
  • servers - MCP server configurations
  • groups - Server groups
  • system_config - System-wide settings
  • user_configs - User-specific settings
  • vector_embeddings - Vector search data (for smart routing)

​
Backup and Restore

​
Backup

# PostgreSQL backup
pg_dump -U mcphub mcphub > mcphub_backup.sql

# Or using Docker
docker exec postgres pg_dump -U mcphub mcphub > mcphub_backup.sql

​
Restore

# PostgreSQL restore
psql -U mcphub mcphub < mcphub_backup.sql

# Or using Docker
docker exec -i postgres psql -U mcphub mcphub < mcphub_backup.sql

​
Switching Back to File-Based Config

If you need to switch back to file-based configuration:
  1. Set USE_DB=false or remove DB_URL and USE_DB environment variables
  2. Restart MCPHub
  3. MCPHub will use mcp_settings.json again
Note: Changes made in database mode won’t be reflected in the file unless you manually export them.

​
Troubleshooting

​
Connection Refused

Error: connect ECONNREFUSED 127.0.0.1:5432
Solution: Check that PostgreSQL is running and accessible: 
# Check PostgreSQL status
sudo systemctl status postgresql

# Or for Docker
docker ps | grep postgres

​
Authentication Failed

Error: password authentication failed for user "mcphub"
Solution: Verify database credentials in DB_URL environment variable.

​
Migration Failed

❌ Migration failed: ...
Solution:
  1. Check that mcp_settings.json exists and is valid JSON
  2. Verify database connection
  3. Check logs for specific error messages
  4. Ensure database user has CREATE TABLE permissions

​
Tables Already Exist

Database tables are automatically created if they don’t exist. If you get errors about existing tables, check:
  1. Whether a previous migration partially completed
  2. Manual table creation conflicts
  3. Run with synchronize: false in database config if needed

​
Environment Variables Reference

VariableRequiredDefaultDescription
DB_URLYes*-Full PostgreSQL connection URL. Setting this automatically enables database mode
USE_DBNoautoExplicitly enable/disable database mode. If not set, auto-detected based on DB_URL presence
MCPHUB_SETTING_PATHNo-Path to mcp_settings.json (for migration)
*Required for database mode. Simply setting DB_URL enables database mode automatically

​
Security Considerations

  1. Database Credentials: Store database credentials securely, use environment variables or secrets management
  2. Network Access: Restrict database access to MCPHub instances only
  3. Encryption: Use SSL/TLS for database connections in production: 
    DB_URL=postgresql://user:password@host:5432/mcphub?sslmode=require
  4. Backup: Regularly backup your database
  5. Access Control: Use strong database passwords and limit user permissions

​
Performance

Database mode offers better performance for:
  • Multiple concurrent users
  • Frequent configuration changes
  • Large number of servers/groups
File mode may be faster for:
  • Single user setups
  • Read-heavy workloads with infrequent changes
  • Development/testing environments