Getting Started with MCPX: Complete Setup Guide

Welcome to MCPX! This guide will walk you through installing and setting up MCPX, the comprehensive platform for managing Model Context Protocol (MCP) servers. By the end of this tutorial, you'll have MCPX running locally with your first workspace configured.

What You'll Learn

• How to install MCPX and its dependencies
• Setting up your development environment
• Creating your first organization and workspace
• Understanding the MCPX architecture
• Running your first MCP server

Prerequisites

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

• Node.js (v18 or higher)
• PNPM (v8 or higher) - npm install -g pnpm
• Docker (for running MCP servers in containers)
• Git (for cloning the repository)

Step 1: Clone and Install MCPX

First, let's get the MCPX codebase and install dependencies:

# Clone the repository
git clone https://github.com/your-org/mcpx.git
cd mcpx

# Install dependencies using PNPM
pnpm install

# Copy environment variables
cp .env.example .env.local

Step 2: Configure Environment Variables

Open .env.local and configure the essential variables:

# Database Configuration
DATABASE_URL="postgresql://user:password@localhost:5432/mcpx"

# API Configuration
API_GATEWAY_URL="http://localhost:8080"
T3_API_SECRET="your-secret-key-here"

# Application URL
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Docker Configuration (for MCP containers)
DOCKER_HOST="unix:///var/run/docker.sock"

Step 3: Set Up the Database

MCPX uses Prisma for database management. Let's set up the database schema:

# Generate Prisma client
pnpm nx run @mcpx/database:generate

# Push schema to database
pnpm nx run @mcpx/database:db-push

# (Optional) Seed with sample data
pnpm nx run @mcpx/database:seed

Step 4: Start MCPX Services

MCPX consists of multiple services that work together. Let's start them:

# Start the main development environment (app + API gateway)
pnpm dev:main

# This starts:
# - Next.js app on http://localhost:3000
# - API Gateway on http://localhost:8080

You should see output like:

> nx run-many -t serve -p app,api-gateway

✔ app:serve
  ▲ Ready on http://localhost:3000

✔ api-gateway:serve
  🚀 API Gateway running on http://localhost:8080

Step 5: Access MCPX Dashboard

Open your browser and navigate to http://localhost:3000. You'll see the MCPX dashboard.

Create Your First Organization

1. Click "Get Started" or "Create Organization"
2. Enter your organization details:
   • Organization Name: "My Team"
   • Organization Slug: "my-team" (URL-friendly identifier)
3. Click "Create Organization"

Understanding Workspaces

In MCPX, workspaces provide isolated environments for MCP servers:

• Each workspace runs in its own Docker container
• Servers in one workspace cannot access servers in another
• Perfect for separating development, staging, and production environments

Your organization comes with a default workspace automatically created.

Step 6: Understanding the Architecture

MCPX uses a microservices architecture:

┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│  Next.js    │────▶│  API Gateway │────▶│   Docker     │
│  Dashboard  │     │   (Express)  │     │  Containers  │
└─────────────┘     └──────────────┘     └──────────────┘
       │                    │                     │
       └────────────────────┴─────────────────────┘
                            │
                     ┌──────────────┐
                     │   PostgreSQL │
                     │   Database   │
                     └──────────────┘

Key Components:

1. Next.js App (/apps/app): The web dashboard for managing MCP servers
2. API Gateway (/apps/api-gateway): Orchestrates MCP server operations
3. Docker Containers: Each workspace runs in an isolated container
4. PostgreSQL Database: Stores configuration and metadata

Step 7: Verify Your Installation

Let's verify everything is working correctly:

Check API Gateway Health

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2025-01-02T10:00:00.000Z"
}

Check Database Connection

pnpm nx run @mcpx/database:studio

This opens Prisma Studio where you can browse your database tables.

Common Development Commands

Here are essential commands for working with MCPX:

# Run specific services
nx serve app                    # Just the Next.js app
nx serve api-gateway            # Just the API gateway

# Build for production
nx build app
nx build api-gateway

# Run tests
nx test app
nx test api-gateway

# Lint code
nx lint app

# Database migrations
nx run @mcpx/database:migrate

Troubleshooting

Docker Permission Issues

If you encounter Docker permission errors:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in, or run:
newgrp docker

Port Already in Use

If ports 3000 or 8080 are already in use:

# Find process using port
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use different ports in .env.local
PORT=3001
API_GATEWAY_PORT=8081

Database Connection Failed

Ensure PostgreSQL is running:

# Check PostgreSQL status
systemctl status postgresql

# Start PostgreSQL
systemctl start postgresql

Project Structure

Understanding the MCPX project structure helps with development:

mcpx/
├── apps/
│   ├── app/              # Next.js dashboard
│   ├── api-gateway/       # Express API gateway
│   └── marketing/         # Marketing website
├── packages/
│   ├── @mcpx/database/    # Prisma schemas
│   ├── @mcpx/mcpx-server/ # Core MCP implementation
│   └── @mcpx/shared/      # Shared utilities
└── nx.json               # Nx workspace configuration

Next Steps

Congratulations! You now have MCPX running locally. Here's what to explore next:

1. Add Your First MCP Server - Learn how to add and configure MCP servers
2. Understanding Workspaces - Deep dive into workspace isolation
3. Building Custom MCP Servers - Create your own MCP servers

Getting Help

• Documentation: Check our docs
• GitHub Issues: Report bugs or request features
• Discord Community: Join our Discord server
• Email Support: support@mcpx.dev

Summary

You've successfully:

• ✅ Installed MCPX and its dependencies
• ✅ Configured your environment
• ✅ Set up the database
• ✅ Started all MCPX services
• ✅ Created your first organization
• ✅ Understood the architecture

MCPX is now ready for you to start adding and managing MCP servers. Happy building!