MCP Server Setup Guide

This comprehensive guide walks you through the complete process of installing, configuring, and using the Emuluxe MCP Server. The MCP Server is the ultimate Model Context Protocol (MCP) server for mobile web simulation, allowing AI agents (like those in Cursor, VS Code, and Antigravity) to instantly launch mobile environments to test and verify web applications.

Prerequisites

Before beginning the installation process, ensure you have:

• Node.js: Version 18 or higher installed on your system
• npm: Node Package Manager (comes with Node.js)
• Active Internet Connection: Required for authentication and simulation API access
• Emuluxe Account: Sign up at app.emuluxe.com
• Pro or Enterprise Subscription: MCP Server features require paid subscription
• IDE with MCP Support: Cursor, VS Code (with Roo Code/Cline), or Antigravity
• API Token: Generated from your Emuluxe dashboard

MCP Server Overview

The Emuluxe MCP Server provides:

• Zero-Install Execution: Run instantly with npx without cloning or local installation
• Multi-IDE Compatibility: Native support for Cursor, VS Code, and Antigravity
• Instant Launch: Deep-link integration triggers simulation panels automatically
• Production-Grade API: Built on the official Emuluxe Simulation API
• AI Agent Integration: Allows AI agents to programmatically control mobile simulations
• Automated Testing: Enable AI agents to verify code changes across multiple devices

Installation Overview

The installation process follows these key stages:

1. Account Setup - Create Emuluxe account and generate API token
2. IDE Configuration - Configure MCP settings in your preferred IDE
3. Server Installation - Install MCP Server via npx
4. Authentication - Configure API token and IDE identifier
5. Testing - Verify the integration works correctly

Detailed Installation Steps

Step 1: Create Your Emuluxe Account

1. Navigate to app.emuluxe.com
2. Click the "Sign Up" button in the top-right corner
3. Complete the registration form:
   • Email Address: For notifications and account management
   • Password: Minimum 12 characters with mixed case, numbers, and symbols
   • Organization Name: For team accounts and billing
4. Click "Create Account" to proceed
5. Verify your email address by clicking the link in the confirmation email
6. Log in to your account

Step 2: Upgrade to Pro or Enterprise Plan

The MCP Server requires a Pro or Enterprise subscription:

1. After logging in, navigate to Settings → Billing
2. Click "Upgrade Plan"
3. Choose your preferred tier:
   • Pro ($9/month): MCP Server access, 30+ devices, unlimited AI, sessions
   • Enterprise ($99/month): All Pro features plus team features, SSO, audit logs
4. Enter payment information
5. Confirm your subscription

Step 3: Generate Your API Token

1. Navigate to Settings → API Tokens
2. Click "Generate New Token"
3. Enter a descriptive name for the token (e.g., "MCP Server - Cursor")
4. Set token permissions:
   • Read: Access simulation results and device information
   • Write: Create simulations and run analyses
   • Delete: Remove simulations and sessions (optional)
5. Click "Generate Token"
6. Important: Copy the token immediately—it won't be shown again
7. Store the token securely (use a password manager or environment variable)

Step 4: Install Node.js (if not already installed)

1. Open your terminal or command prompt
2. Check if Node.js is installed:

   node --version
   

3. If Node.js is not installed or version is below 18:
   • Visit nodejs.org
   • Download the LTS (Long Term Support) version
   • Run the installer for your operating system
   • Follow the installation prompts
   • Restart your terminal after installation
4. Verify the installation:

   node --version
   npm --version
   

Step 5: Configure MCP Server for Cursor

Cursor has native MCP support with a user-friendly configuration interface:

1. Open Cursor

2. Access Settings by pressing Cmd + Shift + J (macOS) or Ctrl + Shift + J (Windows/Linux)

3. Navigate to Features → MCP Servers

4. Click "+ Add New MCP Server"

5. Configure the server with the following settings:

   Basic Configuration:

   • Name: Emuluxe
   • Type: command

   Command Configuration:

   • Command: npx
   • Arguments: -y @emuluxe/mcp-server

   Environment Variables:

   • EMULUXE_TOKEN: Paste your API token from Step 3
   • EMULUXE_IDE: cursor

6. Click "Save" to add the server

7. Cursor will automatically start the MCP server when needed

8. The server appears in the MCP servers list with a status indicator

Step 6: Configure MCP Server for VS Code

VS Code requires manual configuration via MCP config files. The exact location depends on which MCP client you're using:

For Roo Code

1. Locate your Roo Code configuration file:

   • macOS: ~/.roo-code/mcp_config.json
   • Windows: %USERPROFILE%\.roo-code\mcp_config.json
   • Linux: ~/.roo-code/mcp_config.json

2. Open the file in a text editor

3. Add the following configuration:

   {
     "emuluxe": {
       "command": "npx",
       "args": ["-y", "@emuluxe/mcp-server"],
       "env": {
         "EMULUXE_TOKEN": "your_token_here",
         "EMULUXE_IDE": "vscode"
       }
     }
   }
   

4. Replace your_token_here with your actual API token

5. Save the file

6. Restart VS Code to load the new configuration

For Cline

1. Locate your Cline configuration file:

   • macOS: ~/.cline/mcp_config.json
   • Windows: %USERPROFILE%\.cline\mcp_config.json
   • Linux: ~/.cline\mcp_config.json

2. Open the file in a text editor

3. Add the same configuration as above for Roo Code

4. Save the file

5. Restart VS Code

Step 7: Configure MCP Server for Antigravity

Antigravity uses a dedicated configuration directory:

1. Locate your Antigravity MCP configuration:

   • macOS: ~/.gemini/antigravity/mcp_config.json
   • Windows: %USERPROFILE%\.gemini\antigravity\mcp_config.json
   • Linux: ~/.gemini\antigravity/mcp_config.json

2. Open the file in a text editor

3. Add the following configuration:

   {
     "emuluxe": {
       "command": "npx",
       "args": ["-y", "@emuluxe/mcp-server"],
       "env": {
         "EMULUXE_TOKEN": "your_token_here",
         "EMULUXE_IDE": "antigravity"
       }
     }
   }
   

4. Replace your_token_here with your actual API token

5. Save the file

6. Restart Antigravity

Step 8: Verify Installation

Test that the MCP Server is correctly configured:

In Cursor

1. Open a new chat with the Cursor AI assistant
2. Type a test message like: "Can you use the Emuluxe MCP server to simulate my current project?"
3. Cursor should recognize the Emuluxe MCP server
4. The AI agent should be able to access Emuluxe tools

In VS Code (Roo Code/Cline)

1. Open the Roo Code or Cline panel
2. Start a new conversation
3. Ask: "List available Emuluxe MCP tools"
4. The AI should list the available Emuluxe tools
5. Check the VS Code output panel for any MCP server errors

In Antigravity

1. Open the Antigravity AI panel
2. Start a new conversation
3. Ask: "What Emuluxe tools are available?"
4. The AI should respond with available tools
5. Check the Antigravity logs for MCP server status

Using the MCP Server

Step 9: Understanding Available Tools

The Emuluxe MCP Server provides the following tools:

simulate

Launches a mobile simulation of a URL on a specific device.

Parameters:

• url (string, required): The URL to simulate (e.g., https://google.com)
• device (string, optional): The device ID (e.g., iphone-15-pro-max, pixel-8-pro)
  • Default: iphone-15-pro-max
• orientation (string, optional): Device orientation (portrait or landscape)
  • Default: portrait
• network (string, optional): Network profile (online, 4g, 3g, 2g, offline)
  • Default: online

Returns:

• simulation_id: Unique identifier for the simulation
• deep_link: URL to open the simulation in your IDE extension
• status: Simulation status (started, pending, failed)

list_devices

Retrieves a list of available device profiles.

Parameters: None

Returns:

• devices: Array of device objects with:
  • id: Device identifier
  • name: Display name
  • width: Viewport width
  • height: Viewport height
  • device_pixel_ratio: Screen density
  • category: Device category (ios, android, desktop, foldable)

analyze

Runs AI-powered analysis on a simulation.

Parameters:

• simulation_id (string, required): ID of the simulation to analyze
• categories (array, optional): Analysis categories to run
  • Options: layout, performance, accessibility, seo, security
  • Default: All categories

Returns:

• analysis_id: Unique identifier for the analysis
• status: Analysis status (running, completed, failed)
• results: Analysis results (when completed)

Step 10: Basic Simulation with AI Agents

Example in Cursor

1. Open Cursor and start a new AI chat
2. Ask the AI: "Simulate https://example.com on an iPhone 15 Pro Max"
3. Cursor uses the Emuluxe MCP server to:
   • Parse your request
   • Call the simulate tool with appropriate parameters
   • Receive the simulation result
   • Open the simulation via deep link (if IDE extension is installed)
4. The IDE extension opens with the requested simulation

Example in VS Code with Roo Code

1. Open Roo Code in VS Code
2. Start a new conversation
3. Type: "Use Emuluxe to simulate my localhost:3000 on a Pixel 8 Pro"
4. Roo Code invokes the MCP server:
   • Calls simulate with URL http://localhost:3000
   • Specifies device pixel-8-pro
   • Receives simulation ID and deep link
5. The simulation opens in your IDE extension

Example in Antigravity

1. Open Antigravity AI panel
2. Request: "Test my current project on multiple mobile devices"
3. Antigravity uses MCP to:
   • Call list_devices to get available devices
   • Call simulate for each target device
   • Provide you with multiple simulation links
4. You can open each simulation to test across devices

Step 11: Automated Testing Workflows

The MCP Server enables powerful automated testing scenarios:

Regression Testing

1. Ask your AI agent: "Run regression tests on our checkout flow across all iPhone models"
2. The agent:
   • Lists available iPhone devices via list_devices
   • Simulates the checkout flow on each device
   • Runs AI analysis on each simulation
   • Compares results against baselines
   • Reports any regressions

Responsive Design Verification

1. Request: "Verify our homepage is responsive across all device sizes"
2. The agent:
   • Gets all available devices
   • Simulates the homepage on each
   • Analyzes layout shifts and viewport issues
   • Provides a comprehensive report

Performance Testing

1. Ask: "Test our site performance under 3G network conditions"
2. The agent:
   • Simulates the site with network profile 3g
   • Runs performance analysis
   • Identifies slow-loading resources
   • Suggests optimizations

Accessibility Audits

1. Request: "Run WCAG accessibility audit on our product page"
2. The agent:
   • Simulates the page
   • Runs accessibility analysis
   • Identifies WCAG violations
   • Provides code snippets for fixes

Step 12: Deep-Link Integration

When the MCP Server launches a simulation, it provides a deep link:

1. The deep link format: emuluxe://simulate?id={simulation_id}
2. If you have the Emuluxe IDE extension installed:
   • The deep link automatically opens the simulation
   • The simulation panel appears in your IDE
   • You can interact with the simulation normally
3. If the deep link fails to open:
   • The MCP server provides a manual bridge link
   • Click the link to open in your browser
   • Or manually enter the simulation ID in the IDE extension

Step 13: Error Handling

The MCP Server provides detailed error messages:

Authentication Errors

Error: "Invalid API token"

Solution:

1. Verify your API token is correct
2. Check if the token has expired
3. Generate a new token from the dashboard
4. Update your MCP configuration

IDE Extension Not Installed

Error: "IDE extension not found"

Solution:

1. Install the Emuluxe IDE extension for your IDE
2. VS Code: Install from Marketplace
3. Cursor: Install from Cursor Directory
4. Antigravity: Install from Open VSX Registry

Simulation Failures

Error: "Simulation failed to start"

Solution:

1. Verify the URL is accessible
2. Check your internet connection
3. Ensure the URL uses HTTP or HTTPS (not chrome://)
4. Try a different URL to test if the issue is URL-specific

Advanced Configuration

Step 14: Using Environment Variables

For security and flexibility, use environment variables:

1. Set the token as an environment variable:
   • macOS/Linux: Add to ~/.zshrc or ~/.bashrc:

     export EMULUXE_TOKEN="your_token_here"
     

   • Windows: Add to System Environment Variables
2. Update your MCP configuration to use the variable:

   "env": {
     "EMULUXE_TOKEN": "${EMULUXE_TOKEN}",
     "EMULUXE_IDE": "cursor"
   }
   

3. Restart your IDE to load the new environment

Step 15: Custom Device Profiles

If you have custom device profiles in your Emuluxe account:

1. The list_devices tool includes your custom devices
2. Use custom device IDs in simulation requests
3. Custom devices appear alongside standard devices

Step 16: Network Profile Configuration

Use different network profiles for testing:

1. Available profiles: online, 4g, 3g, 2g, offline
2. Specify in simulation requests:
   • "Simulate with 3G network conditions"
   • The agent sets network: "3g" in the simulate call
3. Test your site under various network conditions

Troubleshooting

MCP Server Not Starting

Problem: MCP server fails to start or shows errors

Solutions:

1. Verify Node.js version is 18 or higher
2. Check that npm is working: npm --version
3. Try running the server manually: npx -y @emuluxe/mcp-server
4. Check the IDE's output panel for error messages
5. Ensure your API token is valid and not expired

Tools Not Available to AI Agent

Problem: AI agent doesn't see Emuluxe tools

Solutions:

1. Verify MCP configuration file is correct
2. Restart your IDE to reload MCP configuration
3. Check the IDE's MCP server status
4. Verify the server is running (check output panel)
5. Try reinstalling the MCP server: npx -y @emuluxe/mcp-server@latest

Authentication Errors

Problem: "Invalid API token" or authentication failures

Solutions:

1. Verify your API token is copied correctly (no extra spaces)
2. Check if the token has expired in your dashboard
3. Generate a new token and update your configuration
4. Ensure your subscription is active (Pro or Enterprise)
5. Contact support if the token should be valid

Deep Link Not Opening

Problem: Simulation deep link doesn't open IDE extension

Solutions:

1. Ensure the Emuluxe IDE extension is installed
2. Verify the extension is enabled in your IDE
3. Try manually opening the extension and entering the simulation ID
4. Use the manual bridge link provided by the MCP server
5. Check if your IDE supports deep-link protocols

Simulation Not Starting

Problem: Simulation fails to start after MCP call

Solutions:

1. Verify the URL is accessible and valid
2. Check your internet connection
3. Ensure the URL uses HTTP or HTTPS
4. Try a simpler URL to test if the issue is URL-specific
5. Check the MCP server output for detailed error messages

Performance Issues

Problem: MCP server is slow or unresponsive

Solutions:

1. Check your internet connection speed
2. Verify the Emuluxe API status (check status page if available)
3. Close unused simulations to free up resources
4. Try using a different network profile
5. Contact support if issues persist

Best Practices

Security

1. Token Management: Never commit API tokens to version control
2. Environment Variables: Use environment variables for sensitive data
3. Token Rotation: Regularly rotate your API tokens
4. Access Control: Use appropriate token permissions
5. Audit Logs: Regularly review API usage in your dashboard

Workflow Optimization

1. Batch Operations: Group multiple simulations for efficiency
2. Device Selection: Use devices relevant to your target audience
3. Network Conditions: Test under realistic network profiles
4. Result Caching: Save analysis results for comparison
5. Automated Schedules: Set up recurring automated tests

AI Agent Interaction

1. Clear Requests: Be specific about what you want to test
2. Context Provision: Provide relevant context about your project
3. Result Review: Always review AI-generated results
4. Iterative Testing: Use AI suggestions to improve iteratively
5. Human Verification: Verify critical findings manually

Team Collaboration

1. Shared Configurations: Use consistent MCP configurations across team
2. Token Management: Use team tokens for shared workflows
3. Documentation: Document your MCP setup and workflows
4. Training: Train team members on MCP usage
5. Standardization: Standardize device and network profiles

Integration Examples

CI/CD Pipeline Integration

Integrate MCP Server into your CI/CD pipeline:

# Example GitHub Actions workflow
- name: Run Mobile Tests
  run: |
    npx -y @emuluxe/mcp-server simulate \
      --url https://staging.example.com \
      --device iphone-15-pro-max \
      --network 4g

Automated Regression Testing

Set up automated regression tests:

// Example script
const { spawn } = require('child_process');

async function runSimulation(url, device) {
  const result = await spawn('npx', [
    '-y',
    '@emuluxe/mcp-server',
    'simulate',
    '--url', url,
    '--device', device
  ]);
  return result;
}

// Test across multiple devices
const devices = ['iphone-15-pro-max', 'pixel-8-pro', 'galaxy-s24-ultra'];
devices.forEach(device => {
  runSimulation('https://example.com', device);
});

Pre-Commit Hooks

Add mobile testing to pre-commit hooks:

# .git/hooks/pre-commit
#!/bin/bash
npx -y @emuluxe/mcp-server simulate \
  --url http://localhost:3000 \
  --device iphone-15-pro-max

if [ $? -ne 0 ]; then
  echo "Mobile simulation failed. Commit aborted."
  exit 1
fi

Next Steps

After completing the setup:

1. Explore IDE Extensions for deeper IDE integration
2. Learn about AI Analysis for automated diagnostics
3. Configure CLI Toolchain for command-line automation
4. Set up Webhooks for event-driven workflows
5. Explore REST API for programmatic access

For additional help, visit the Help Center or contact support@emuluxe.com.