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
• Subscription: Basic features are free; advanced simulation and AI features require a Pro or Enterprise plan.
• IDE with MCP Support: Cursor, Windsurf, VS Code (with Roo Code/Cline), Claude Desktop, Claude Code, Codex, 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. Dashboard Integration - Use the "Add MCP Server" buttons in the dashboard (Recommended)
3. IDE Configuration - Configure MCP settings in your preferred IDE
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: Recommended - Use Dashboard One-Click Sync

The easiest way to configure MCP is through the Emuluxe Dashboard:

1. Log in to app.emuluxe.com
2. Navigate to Settings → Integrations
3. Locate your IDE (Cursor, VS Code, Windsurf, Antigravity, Claude, or Codex)
4. Click "Connect" or "Add MCP Server"
5. Follow the IDE-specific instructions provided in the modal. This will provide you with the exact command (for CLI) or UI settings (for IDEs) pre-filled with your token.

Step 6: Configure MCP Server for Cursor

Cursor supports one-click automated MCP installation:

1. On the Integrations page, click "Add MCP Server" under Cursor.
2. An "Open Cursor" prompt will appear. Click it to initiate automated setup.
3. If the automated link fails, use the Manual Configuration provided in the modal:
   • Name: emuluxe
   • Type: command
   • Command: npx
   • Arguments: -y @emuluxe/mcp-server
   • Environment Variables: EMULUXE_TOKEN=your_token

Step 7: Configure MCP Server for Claude (Desktop & Code)

Claude supports MCP in both the Desktop app and the CLI:

Claude Desktop (GUI)

1. In the Emuluxe Dashboard, click Connect on the Claude card and select the Claude Desktop tab.
2. Open Claude Desktop Settings → Developer → Click "Edit Config".
3. Paste the provided JSON configuration into your claude_desktop_config.json.
4. Restart Claude Desktop.

Claude Code (CLI)

1. In the Emuluxe Dashboard, click Connect on the Claude card and select the Claude Code tab.
2. Copy the claude mcp add command.
3. Run the command in your terminal.

Step 8: Configure MCP Server for Codex AI

Codex uses a config.toml file or a CLI for MCP configuration:

UI Method (Recommended)

1. In Codex, go to MCP Settings → "Connect to a custom MCP".
2. Fill in the fields:
   • Name: emuluxe
   • Type: STDIO
   • Command: npx
   • Arguments: Add -y and @emuluxe/mcp-server
   • Environment Variables: Add EMULUXE_TOKEN (your token) and EMULUXE_IDE (codex).
3. Click Save.

CLI Method

1. Copy the codex mcp add command from the Emuluxe Dashboard.
2. Run it in your terminal.

Step 8: Configure MCP Server for Windsurf (Cascade)

Windsurf supports MCP via its Cascade AI system:

1. Click the MCP Servers (hammer) icon in the bottom bar or chat panel.
2. Click "Configure" or "View raw config" to open mcp_config.json.
3. Add the following to your mcpServers block:

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

4. Save the file and click "Refresh" in the Windsurf MCP settings.

Step 9: Configure MCP Server for VS Code

VS Code users can use the CLI to add the MCP server automatically:

1. Copy the CLI command from the Emuluxe Integrations dashboard: code --add-mcp '{"name":"emuluxe","command":"npx","args":["-y","@emuluxe/mcp-server"],"env":{"EMULUXE_TOKEN":"your_token"}}'
2. Run this in your terminal.
3. Alternatively, manually add it to your settings.json under "mcp.servers".

Step 10: 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 Codex AI

1. Open the Codex chat panel.
2. Type /mcp to verify that the emuluxe server is listed and active.
3. Ask: "What Emuluxe tools are available?"
4. The AI should respond with simulate, list_devices, and analyze.

In Claude Code

1. In your terminal session, run /mcp.
2. Verify that emuluxe is connected.
3. You can now ask Claude to "simulate my current page on a mobile device".

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.