Quick Start

This guide gets the entire MCP Hub Platform running on your local machine. By the end, you will have all four components operational: the Hub dashboard, the Registry, the Scanner worker, and the supporting infrastructure.

Prerequisites

Before you begin, make sure you have the following installed:

Step 1: Clone the Repository

git clone https://github.com/your-org/mcp-hub-platform.git
cd mcp-hub-platform

Step 2: Start Infrastructure Services

Launch all backing services (PostgreSQL, Redis, MinIO, LavinMQ) with a single command:

make up

This starts the full Docker Compose stack. Wait for all containers to reach a healthy state:

make ps

You should see output similar to:

NAME                STATUS              PORTS
postgres            running (healthy)   0.0.0.0:15432->5432/tcp
redis               running (healthy)   0.0.0.0:6390->6379/tcp
minio               running (healthy)   0.0.0.0:9000->9000/tcp, 0.0.0.0:9001->9001/tcp
lavinmq             running (healthy)   0.0.0.0:5672->5672/tcp, 0.0.0.0:15672->15672/tcp

Step 3: Configure Environment Variables

Copy the example environment file and edit it with your settings:

cp mcp-hub/.env.example mcp-hub/.env

Open mcp-hub/.env and configure the required values:

# Auth0 configuration
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

# Stripe (optional for local dev)
STRIPE_API_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# GitHub token for repository ingestion
GITHUB_TOKEN=ghp_...

For a basic local setup, the Auth0 and GitHub token values are the most important. Stripe configuration can be deferred until you need billing features.

Step 4: Start the Hub Web Server

In your first terminal, start the main Hub dashboard:

make dev

This runs database migrations, compiles CSS assets, and starts the web server on port 8080. Open http://localhost:8080 to access the dashboard.

Step 5: Start the Analysis Worker

Open a second terminal and start the hub worker that orchestrates the certification pipeline:

make dev-worker

The worker connects to LavinMQ and listens for analysis jobs. When you submit an MCP server for certification, the worker coordinates with the scan-worker to perform security analysis.

Step 6: Start the Registry

Open a third terminal and start the registry service:

make dev-registry

The registry starts on port 8081 and handles artifact storage and distribution.

Verify the Setup

Confirm all services are running correctly:

# Check infrastructure status
make ps

# Build health check for all components
make status

Service Endpoints

Once everything is running, you can access these services:

Quick Health Checks

# Hub web server
curl -s http://localhost:8080/health | jq .

# Registry
curl -s http://localhost:8081/health | jq .

# PostgreSQL
psql -h localhost -p 15432 -U postgres -c "SELECT 1"

# Redis (note: port 6390, NOT 6379)
redis-cli -p 6390 ping

Common Issues

minio-init Has Not Completed

If artifact uploads fail or you see S3 connection errors, check that the minio-init container has finished:

docker compose ps minio-init

It should show Exited (0). If it is still running, wait for it to complete.

Worker Not Processing Jobs

Ensure all three Hub services are running simultaneously in separate terminals:

1. make dev (web server)
2. make dev-worker (analysis worker)
3. The scan-worker container from Docker Compose

Missing any one of these will cause parts of the certification pipeline to stall.

Database Connection Errors

The PostgreSQL init scripts create two databases: mcphub and mcp_registry. If you reset Docker volumes, both databases are recreated automatically on next startup:

make down
make clean-volumes   # Warning: destroys all data
make up

Next Steps

Now that your platform is running:

• Your First Certification – Walk through the complete certification pipeline
• Architecture Overview – Understand how the components connect
• Publish from GitHub – Publish an MCP server directly from a Git repository