Installation

Detailed installation guide for MCP Hub Platform components, from source or Docker.

4 min read

This guide covers installing MCP Hub Platform components individually or as a full stack. Choose the approach that fits your workflow: Docker-based for quick evaluation, or from-source for active development.

Prerequisites

System Requirements

Resource	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Disk	10 GB free	20+ GB free
OS	Linux, macOS, Windows (WSL2)	Linux or macOS

Required Software

Software	Minimum Version	Installation
Go	1.24+	go.dev/dl
Docker	24.0+	docs.docker.com/get-docker
Docker Compose	2.20+	Included with Docker Desktop
Make	Any	Pre-installed on macOS/Linux; `choco install make` on Windows
Git	2.30+	git-scm.com

Optional Software

Software	Purpose
golangci-lint	Code linting (`make lint-all`)
gosec	Security scanning (`make security-all`)
psql	Direct PostgreSQL access
redis-cli	Direct Redis access
jq	JSON formatting for API responses

Verify your Go version before proceeding – this is the most common source of build failures:

go version
# Expected: go version go1.24.x ...

Docker-Based Installation (Recommended)

The fastest path to a running platform. This starts all infrastructure services and the application containers.

Step 1: Clone and Start Infrastructure

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

Step 2: Verify Infrastructure Health

make ps

Wait until all services report as healthy. Pay special attention to:

minio-init must exit with code 0 (it creates required S3 buckets)
postgres must be healthy (init scripts create both mcphub and mcp_registry databases)

Step 3: Configure Environment

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

Edit mcp-hub/.env with your configuration. See the Environment Variables section below for a complete reference.

Step 4: Start Application Services

# Terminal 1: Hub web dashboard
make dev

# Terminal 2: Analysis worker
make dev-worker

# Terminal 3: Registry
make dev-registry

Building from Source

Build individual components or the entire platform from source.

Build All Components

make build-all

This compiles all four projects and produces binaries in each component’s directory.

Build Individual Components

Command	Component	Output
`make build-hub`	MCP Hub	`mcp-hub/bin/mcp-hub`
`make build-client`	MCP Client	`mcp-client/bin/mcp-client`
`make build-registry`	MCP Registry	`mcp-registry/bin/mcp-registry`
`make build-scan`	MCP Scanner	`mcp-scan/bin/mcp-scan`

Install the MCP Client

The MCP Client is the component most users install locally. After building:

# Build the client
make build-client

# Copy to your PATH
cp mcp-client/bin/mcp-client /usr/local/bin/

# Verify installation
mcp-client version

Alternatively, install directly with Go:

go install github.com/your-org/mcp-hub-platform/mcp-client@latest

Environment Variables

The Hub is the most configuration-intensive component. Below is a reference of key environment variables.

Required Variables

Variable	Description	Example
`AUTH0_DOMAIN`	Auth0 tenant domain	`your-tenant.auth0.com`
`AUTH0_CLIENT_ID`	Auth0 application client ID	`abc123def456`
`AUTH0_CLIENT_SECRET`	Auth0 application client secret	`secret_...`
`GITHUB_TOKEN`	GitHub personal access token for repo ingestion	`ghp_...`
`DATABASE_URL`	PostgreSQL connection string	`postgres://postgres:postgres@localhost:15432/mcphub?sslmode=disable`
`REDIS_URL`	Redis connection string	`redis://localhost:6390/0`

Optional Variables

Variable	Description	Default
`STRIPE_API_KEY`	Stripe API key for billing	(none – billing disabled)
`STRIPE_WEBHOOK_SECRET`	Stripe webhook signing secret	(none)
`MINIO_ENDPOINT`	S3-compatible storage endpoint	`localhost:9000`
`MINIO_ACCESS_KEY`	S3 access key	`minioadmin`
`MINIO_SECRET_KEY`	S3 secret key	`minioadmin`
`AMQP_URL`	AMQP broker connection string	`amqp://guest:guest@localhost:5672/`
`HUB_PORT`	Hub web server port	`8080`
`REGISTRY_PORT`	Registry server port	`8081`

No Secrets in Logs

MCP Hub Platform never logs secret values. If you see tokens or keys appearing in log output, please report it as a security issue.

Infrastructure Services Reference

The Docker Compose stack provides these services:

Service	Internal Port	External Port	Purpose
postgres	5432	15432	PostgreSQL 16 with two databases
redis	6379	6390	Cache and rate limiting
minio	9000 / 9001	9000 / 9001	S3-compatible object storage
lavinmq	5672 / 15672	5672 / 15672	AMQP message broker

Non-Standard Ports

PostgreSQL uses port 15432 and Redis uses port 6390 to avoid conflicts with any locally installed instances. Adjust your connection strings accordingly.

Verifying Your Installation

Check Build Artifacts

make status

This runs a health check across all four components and reports build status.

Run the Test Suite

# All tests
make test-all

# Per component
make test-hub
make test-client
make test-registry
make test-scan

Run Linters and Security Scans

make lint-all
make security-all

Verify Service Connectivity

# Hub dashboard
curl -sf http://localhost:8080/health && echo "Hub OK"

# Registry
curl -sf http://localhost:8081/health && echo "Registry OK"

# PostgreSQL
psql -h localhost -p 15432 -U postgres -c "SELECT version();"

# Redis
redis-cli -p 6390 ping

# MinIO
curl -sf http://localhost:9000/minio/health/live && echo "MinIO OK"

# LavinMQ
curl -sf http://localhost:15672/api/overview && echo "LavinMQ OK"

Uninstalling

To completely remove the platform and all data:

# Stop all containers
make down

# Remove all data volumes (irreversible)
make clean-volumes

# Remove build artifacts
make clean-all

Next Steps

Quick Start – Get the full platform running in 5 minutes
Your First Certification – Walk through the certification pipeline
Architecture – Understand how the components connect