Adding Your First MCP Server to MCPX: Step-by-Step Guide

Once you have MCPX up and running, the next step is to add your first MCP server. This comprehensive guide will walk you through the entire process, from understanding prerequisites to testing your newly added server tools.

What You'll Learn

• How to navigate to the servers management interface
• Adding a pre-built MCP server (calculator example)
• Understanding configuration options and formats
• Setting up OAuth authentication for HTTP servers
• Verifying server connectivity and health
• Testing server tools and capabilities
• Troubleshooting common configuration issues
• Best practices for server management

Prerequisites and Setup

Before adding an MCP server, ensure you have:

System Requirements

• MCPX platform running and accessible
• Active organization with appropriate permissions
• Workspace configured (or using the default workspace)
• Container runtime available (Docker/Podman)

User Permissions

• Organization Member or higher role
• Workspace Editor role or higher (for workspace-level servers)
• Access to the servers management interface

Network Requirements

• Outbound internet access for downloading server packages
• Container network access for server communication
• Port availability (default: 9000+ range)

Navigating to the Servers Page

From the Dashboard

1. Log into your MCPX instance
2. Select your organization from the organization selector
3. Navigate to your workspace (or use the default workspace)
4. Click on "Servers" in the main navigation menu

From the Workspace Selector

Alternatively, you can access servers directly:

1. Use the workspace dropdown: /org/{orgId}/workspace/{workspaceSlug}/servers
2. Or organization-level servers: /org/{orgId}/servers

The servers page displays:

• Currently configured servers
• Server health status
• Available tools count
• Connection diagnostics

Adding a Pre-Built Server (Calculator Example)

Let's start with a simple, reliable MCP server - the calculator server. This server provides basic mathematical operations and is perfect for testing.

Step 1: Open the Add Server Modal

1. On the servers page, click the "Add Server" button
2. The "Add MCP Server" dialog will open
3. You'll see a default calculator configuration pre-loaded

Step 2: Review the Default Configuration

The modal opens with this default calculator configuration:

{
  "calculator": {
    "command": "uvx",
    "args": [
      "mcp-server-calculator"
    ]
  }
}

Step 3: Add Server Description (Optional)

In the Description field, add a meaningful description:

Basic calculator server providing mathematical operations like addition, subtraction, multiplication, and division.

Step 4: Understand the Configuration Format

The JSON configuration follows this structure:

{
  "serverName": {
    "command": "executable_command",
    "args": ["argument1", "argument2"],
    "env": {
      "VARIABLE_NAME": "value"
    }
  }
}

Key Components:

• serverName: Unique identifier for your server
• command: Executable command or binary
• args: Array of command-line arguments
• env: Environment variables (optional)

Step 5: Submit the Configuration

1. Review the configuration for any validation errors
2. Ensure no server name conflicts exist
3. Click "Add Server"
4. Wait for the server to be created and validated

Configuration Options Explained

Command Types

Python/UV Servers

{
  "my-python-server": {
    "command": "uvx",
    "args": ["package-name"],
    "env": {
      "PYTHON_PATH": "/usr/local/bin/python3"
    }
  }
}

NPM Servers

{
  "my-node-server": {
    "command": "npx",
    "args": ["-y", "@package/mcp-server"],
    "env": {
      "NODE_ENV": "production"
    }
  }
}

Binary Servers

{
  "custom-server": {
    "command": "/path/to/binary",
    "args": ["--port", "9000", "--config", "/etc/config.json"]
  }
}

Environment Variables

Common environment variables for MCP servers:

{
  "server-with-env": {
    "command": "uvx",
    "args": ["mcp-server-example"],
    "env": {
      "API_KEY": "your-api-key",
      "DEBUG": "true",
      "TIMEOUT": "30000",
      "LOG_LEVEL": "info"
    }
  }
}

HTTP Servers Configuration

For HTTP-based MCP servers:

{
  "http-server": {
    "command": "curl",
    "args": [
      "-X", "POST",
      "https://api.example.com/mcp",
      "-H", "Content-Type: application/json"
    ],
    "env": {
      "HTTP_TIMEOUT": "30",
      "RETRY_COUNT": "3"
    }
  }
}

OAuth Authentication for HTTP Servers

Some MCP servers require OAuth authentication. MCPX handles this automatically.

Detecting OAuth Requirements

When adding a server that requires authentication, MCPX will:

1. Attempt to connect to the server
2. Detect authentication requirements (401 responses)
3. Display the authentication dialog
4. Guide you through the OAuth flow

Authentication Flow

Step 1: Authentication Detection

[Server Response: 401 Unauthorized]
↓
[MCPX detects OAuth requirement]
↓
[Authentication Dialog appears]

Step 2: OAuth Dialog Actions

Option 1: Complete Authentication

1. Click "Authorize with OAuth"
2. New window opens to OAuth provider
3. Complete authentication flow
4. Window closes automatically
5. Server creation retries with credentials

Option 2: Skip Authentication

1. Click "Skip for Now"
2. Server is saved with pending-auth status
3. Authentication can be completed later
4. Tools remain unavailable until authenticated

OAuth Configuration Example

{
  "github-server": {
    "command": "uvx",
    "args": ["mcp-server-github"],
    "env": {
      "GITHUB_CLIENT_ID": "your-client-id",
      "REDIRECT_URI": "https://your-mcpx.com/oauth/callback"
    }
  }
}

Verifying Server Connection

Automatic Verification

After clicking "Add Server", MCPX performs several checks:

1. Configuration Validation: JSON syntax and schema validation
2. Container Creation: Spins up isolated container for the server
3. Health Check: Verifies server responds to MCP protocol
4. Tool Discovery: Enumerates available tools and capabilities
5. Security Scan: Basic security validation

Verification Status Indicators

Manual Verification Steps

1. Check Server Status

# View server logs (if you have container access)
docker logs mcpx-server-calculator

# Check container health
docker ps | grep mcpx-server

2. Test Connectivity

Navigate to: Servers → [Your Server] → Health Check

3. Review Server Logs

In the MCPX interface:

1. Click on your server name
2. Select the "Logs" tab
3. Review startup and connection logs

Testing Server Tools

Using the Success Dialog

When a server is successfully added, MCPX shows available tools:

1. Tool List: All discovered tools with descriptions
2. Execute Button: Test tools directly from the success dialog
3. View All Tools: Navigate to the tools page

Tool Execution Example

For the calculator server, you'll see tools like:

• calculator__add: Addition operation
• calculator__subtract: Subtraction operation
• calculator__multiply: Multiplication operation
• calculator__divide: Division operation

Testing Addition Tool

1. Click "Execute" next to calculator__add
2. Fill in the parameters:

   {
     "a": 15,
     "b": 25
   }
   

3. Click "Execute Tool"
4. Verify the result: {"result": 40}

Tools Page Testing

Navigate to Tools page to see all available tools:

1. Filter by Server: Use the server filter dropdown
2. Search Tools: Use the search bar to find specific tools
3. Tool Categories: Browse by tool functionality
4. Execution History: View past tool executions

Testing Different Tool Types

Mathematical Operations

// Addition
{"a": 10, "b": 5} → {"result": 15}

// Division with decimals
{"a": 22, "b": 7} → {"result": 3.142857142857143}

// Error handling
{"a": 10, "b": 0} → {"error": "Division by zero"}

String Operations (if available)

// String concatenation
{"strings": ["Hello", " ", "World"]} → {"result": "Hello World"}

Troubleshooting Common Issues

1. Server Name Already Exists

Error: A server named 'calculator' already exists in this organization

Solution:

{
  "calculator-v2": {
    "command": "uvx",
    "args": ["mcp-server-calculator"]
  }
}

2. Invalid JSON Configuration

Error: Configuration validation failed: Invalid JSON syntax

Common Issues:

• Missing commas between elements
• Unmatched brackets or braces
• Invalid string escaping

Solution: Use the "Format JSON" button to auto-format and validate.

3. Command Not Found

Error: Server failed to start: command 'uvx' not found

Solutions:

• Verify the command is available in the container
• Check package installation requirements
• Use full path to executables

Example Fix:

{
  "calculator": {
    "command": "/usr/local/bin/uvx",
    "args": ["mcp-server-calculator"]
  }
}

4. Port Conflicts

Error: Port 9000 already in use

Solution: MCPX automatically assigns available ports, but you can specify:

{
  "custom-port-server": {
    "command": "uvx",
    "args": ["mcp-server-example", "--port", "9001"]
  }
}

5. Authentication Failures

Error: 401 Unauthorized - Authentication required

Debugging Steps:

1. Check if server requires OAuth
2. Verify environment variables are set
3. Test authentication flow manually
4. Review server documentation

6. Timeout Issues

Error: Server health check timeout

Solutions:

• Increase timeout values in server configuration
• Check network connectivity
• Verify server startup time requirements

{
  "slow-server": {
    "command": "uvx",
    "args": ["slow-mcp-server"],
    "env": {
      "STARTUP_TIMEOUT": "60000"
    }
  }
}

7. Container Resource Issues

Error: Container failed to start - insufficient resources

Solutions:

• Check available system resources
• Reduce concurrent server count
• Optimize server configurations
• Consider workspace-level vs organization-level servers

Debugging Tools

1. Server Logs

• Real-time log viewing in MCPX interface
• Container log access via Docker CLI
• Error aggregation and filtering

2. Health Monitoring

• Automatic health checks every 30 seconds
• Connection status indicators
• Performance metrics tracking

3. Tool Validation

• Parameter validation before execution
• Response format verification
• Error message standardization

Next Steps and Advanced Configuration

1. Adding Multiple Servers

Once comfortable with basic servers, explore adding multiple servers:

{
  "calculator": {
    "command": "uvx",
    "args": ["mcp-server-calculator"]
  },
  "filesystem": {
    "command": "uvx",
    "args": ["mcp-server-filesystem"],
    "env": {
      "ALLOWED_PATHS": "/tmp,/var/data"
    }
  },
  "database": {
    "command": "npx",
    "args": ["-y", "@mcp/server-database"],
    "env": {
      "DB_CONNECTION": "postgresql://..."
    }
  }
}

2. Server Categories and Organization

Organize servers by functionality:

• Utility Servers: calculator, filesystem, text-processing
• Integration Servers: github, slack, email
• Data Servers: database, analytics, reporting
• AI/ML Servers: model-inference, data-processing

3. Workspace vs Organization Servers

Organization-Level Servers:

• Available to all workspaces
• Managed by organization admins
• Shared configuration and resources

Workspace-Level Servers:

• Isolated to specific workspace
• Independent configurations
• Workspace admin control

4. Security Best Practices

Environment Variables

• Store sensitive data in environment variables
• Use MCPX's secret management features
• Rotate API keys regularly

Network Security

• Review server network requirements
• Implement proper access controls
• Monitor server communications

Container Security

• Keep server images updated
• Review server code and dependencies
• Monitor for security vulnerabilities

5. Performance Optimization

Resource Management

{
  "optimized-server": {
    "command": "uvx",
    "args": ["mcp-server-example"],
    "env": {
      "MAX_MEMORY": "512M",
      "MAX_CPU": "0.5",
      "TIMEOUT": "15000"
    }
  }
}

Caching Configuration

{
  "cached-server": {
    "command": "uvx",
    "args": ["mcp-server-cache"],
    "env": {
      "CACHE_TTL": "3600",
      "CACHE_SIZE": "100MB",
      "ENABLE_CACHING": "true"
    }
  }
}

6. Monitoring and Observability

• Set up server health monitoring
• Configure alerting for server failures
• Track tool execution metrics
• Monitor resource usage patterns

7. Custom Server Development

For advanced users, consider developing custom MCP servers:

• Follow MCP protocol specifications
• Implement standard tool interfaces
• Add comprehensive error handling
• Include proper documentation

Advanced Server Examples

GitHub Integration Server

{
  "github": {
    "command": "uvx",
    "args": ["mcp-server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}",
      "GITHUB_API_URL": "https://api.github.com",
      "DEFAULT_OWNER": "your-org",
      "CACHE_ENABLED": "true"
    }
  }
}

Database Server

{
  "postgres-db": {
    "command": "uvx",
    "args": ["mcp-server-postgres"],
    "env": {
      "DATABASE_URL": "${POSTGRES_CONNECTION}",
      "QUERY_TIMEOUT": "30000",
      "MAX_CONNECTIONS": "10",
      "SSL_MODE": "require"
    }
  }
}

Web Scraping Server

{
  "web-scraper": {
    "command": "npx",
    "args": ["-y", "@mcp/server-puppeteer"],
    "env": {
      "BROWSER_TIMEOUT": "30000",
      "USER_AGENT": "MCPX-WebScraper/1.0",
      "ALLOWED_DOMAINS": "example.com,api.service.com"
    }
  }
}

Conclusion

You've now successfully added your first MCP server to MCPX! This opens up a world of possibilities for extending your AI workflows with powerful, standardized tools.

Key Takeaways

1. Start Simple: Begin with reliable servers like calculator
2. Test Thoroughly: Always verify server health and tool functionality
3. Security First: Properly handle authentication and sensitive data
4. Monitor Continuously: Keep track of server health and performance
5. Scale Gradually: Add complexity as you gain experience

What's Next?

• Explore the MCP Server Directory for more pre-built servers
• Learn about creating custom workspaces for different projects
• Set up automated monitoring for your server infrastructure
• Dive into custom server development for specialized needs

Getting Help

• Documentation: Visit our comprehensive documentation portal
• Community: Join the MCPX Discord community
• Support: Create issues on our GitHub repository
• Examples: Browse the server examples repository

Happy server management with MCPX! 🚀