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
npxwithout 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:
- Account Setup - Create Emuluxe account and generate API token
- IDE Configuration - Configure MCP settings in your preferred IDE
- Server Installation - Install MCP Server via npx
- Authentication - Configure API token and IDE identifier
- Testing - Verify the integration works correctly
Detailed Installation Steps
Step 1: Create Your Emuluxe Account
- Navigate to app.emuluxe.com
- Click the "Sign Up" button in the top-right corner
- 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
- Click "Create Account" to proceed
- Verify your email address by clicking the link in the confirmation email
- Log in to your account
Step 2: Upgrade to Pro or Enterprise Plan
The MCP Server requires a Pro or Enterprise subscription:
- After logging in, navigate to Settings → Billing
- Click "Upgrade Plan"
- 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
- Enter payment information
- Confirm your subscription
Step 3: Generate Your API Token
- Navigate to Settings → API Tokens
- Click "Generate New Token"
- Enter a descriptive name for the token (e.g., "MCP Server - Cursor")
- Set token permissions:
- Read: Access simulation results and device information
- Write: Create simulations and run analyses
- Delete: Remove simulations and sessions (optional)
- Click "Generate Token"
- Important: Copy the token immediately—it won't be shown again
- Store the token securely (use a password manager or environment variable)
Step 4: Install Node.js (if not already installed)
- Open your terminal or command prompt
- Check if Node.js is installed:
node --version - 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
- 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:
-
Open Cursor
-
Access Settings by pressing
Cmd + Shift + J(macOS) orCtrl + Shift + J(Windows/Linux) -
Navigate to Features → MCP Servers
-
Click "+ Add New MCP Server"
-
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 3EMULUXE_IDE:cursor
- Name:
-
Click "Save" to add the server
-
Cursor will automatically start the MCP server when needed
-
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
-
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
- macOS:
-
Open the file in a text editor
-
Add the following configuration:
{ "emuluxe": { "command": "npx", "args": ["-y", "@emuluxe/mcp-server"], "env": { "EMULUXE_TOKEN": "your_token_here", "EMULUXE_IDE": "vscode" } } } -
Replace
your_token_herewith your actual API token -
Save the file
-
Restart VS Code to load the new configuration

For Cline
-
Locate your Cline configuration file:
- macOS:
~/.cline/mcp_config.json - Windows:
%USERPROFILE%\.cline\mcp_config.json - Linux:
~/.cline\mcp_config.json
- macOS:
-
Open the file in a text editor
-
Add the same configuration as above for Roo Code
-
Save the file
-
Restart VS Code
Step 7: Configure MCP Server for Antigravity
Antigravity uses a dedicated configuration directory:
-
Locate your Antigravity MCP configuration:
- macOS:
~/.gemini/antigravity/mcp_config.json - Windows:
%USERPROFILE%\.gemini\antigravity\mcp_config.json - Linux:
~/.gemini\antigravity/mcp_config.json
- macOS:
-
Open the file in a text editor
-
Add the following configuration:
{ "emuluxe": { "command": "npx", "args": ["-y", "@emuluxe/mcp-server"], "env": { "EMULUXE_TOKEN": "your_token_here", "EMULUXE_IDE": "antigravity" } } } -
Replace
your_token_herewith your actual API token -
Save the file
-
Restart Antigravity
Step 8: Verify Installation
Test that the MCP Server is correctly configured:
In Cursor
- Open a new chat with the Cursor AI assistant
- Type a test message like: "Can you use the Emuluxe MCP server to simulate my current project?"
- Cursor should recognize the Emuluxe MCP server
- The AI agent should be able to access Emuluxe tools
In VS Code (Roo Code/Cline)
- Open the Roo Code or Cline panel
- Start a new conversation
- Ask: "List available Emuluxe MCP tools"
- The AI should list the available Emuluxe tools
- Check the VS Code output panel for any MCP server errors
In Antigravity
- Open the Antigravity AI panel
- Start a new conversation
- Ask: "What Emuluxe tools are available?"
- The AI should respond with available tools
- 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
- Default:
orientation(string, optional): Device orientation (portraitorlandscape)- Default:
portrait
- Default:
network(string, optional): Network profile (online,4g,3g,2g,offline)- Default:
online
- Default:
Returns:
simulation_id: Unique identifier for the simulationdeep_link: URL to open the simulation in your IDE extensionstatus: 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 identifiername: Display namewidth: Viewport widthheight: Viewport heightdevice_pixel_ratio: Screen densitycategory: Device category (ios, android, desktop, foldable)
analyze
Runs AI-powered analysis on a simulation.
Parameters:
simulation_id(string, required): ID of the simulation to analyzecategories(array, optional): Analysis categories to run- Options:
layout,performance,accessibility,seo,security - Default: All categories
- Options:
Returns:
analysis_id: Unique identifier for the analysisstatus: Analysis status (running,completed,failed)results: Analysis results (when completed)
Step 10: Basic Simulation with AI Agents
Example in Cursor
- Open Cursor and start a new AI chat
- Ask the AI: "Simulate https://example.com on an iPhone 15 Pro Max"
- Cursor uses the Emuluxe MCP server to:
- Parse your request
- Call the
simulatetool with appropriate parameters - Receive the simulation result
- Open the simulation via deep link (if IDE extension is installed)
- The IDE extension opens with the requested simulation
Example in VS Code with Roo Code
- Open Roo Code in VS Code
- Start a new conversation
- Type: "Use Emuluxe to simulate my localhost:3000 on a Pixel 8 Pro"
- Roo Code invokes the MCP server:
- Calls
simulatewith URLhttp://localhost:3000 - Specifies device
pixel-8-pro - Receives simulation ID and deep link
- Calls
- The simulation opens in your IDE extension
Example in Antigravity
- Open Antigravity AI panel
- Request: "Test my current project on multiple mobile devices"
- Antigravity uses MCP to:
- Call
list_devicesto get available devices - Call
simulatefor each target device - Provide you with multiple simulation links
- Call
- You can open each simulation to test across devices
Step 11: Automated Testing Workflows
The MCP Server enables powerful automated testing scenarios:
Regression Testing
- Ask your AI agent: "Run regression tests on our checkout flow across all iPhone models"
- 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
- Lists available iPhone devices via
Responsive Design Verification
- Request: "Verify our homepage is responsive across all device sizes"
- The agent:
- Gets all available devices
- Simulates the homepage on each
- Analyzes layout shifts and viewport issues
- Provides a comprehensive report
Performance Testing
- Ask: "Test our site performance under 3G network conditions"
- The agent:
- Simulates the site with network profile
3g - Runs performance analysis
- Identifies slow-loading resources
- Suggests optimizations
- Simulates the site with network profile
Accessibility Audits
- Request: "Run WCAG accessibility audit on our product page"
- 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:
- The deep link format:
emuluxe://simulate?id={simulation_id} - 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
- 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:
- Verify your API token is correct
- Check if the token has expired
- Generate a new token from the dashboard
- Update your MCP configuration
IDE Extension Not Installed
Error: "IDE extension not found"
Solution:
- Install the Emuluxe IDE extension for your IDE
- VS Code: Install from Marketplace
- Cursor: Install from Cursor Directory
- Antigravity: Install from Open VSX Registry
Simulation Failures
Error: "Simulation failed to start"
Solution:
- Verify the URL is accessible
- Check your internet connection
- Ensure the URL uses HTTP or HTTPS (not chrome://)
- 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:
- Set the token as an environment variable:
- macOS/Linux: Add to
~/.zshrcor~/.bashrc:export EMULUXE_TOKEN="your_token_here" - Windows: Add to System Environment Variables
- macOS/Linux: Add to
- Update your MCP configuration to use the variable:
"env": { "EMULUXE_TOKEN": "${EMULUXE_TOKEN}", "EMULUXE_IDE": "cursor" } - Restart your IDE to load the new environment
Step 15: Custom Device Profiles
If you have custom device profiles in your Emuluxe account:
- The
list_devicestool includes your custom devices - Use custom device IDs in simulation requests
- Custom devices appear alongside standard devices
Step 16: Network Profile Configuration
Use different network profiles for testing:
- Available profiles:
online,4g,3g,2g,offline - Specify in simulation requests:
- "Simulate with 3G network conditions"
- The agent sets
network: "3g"in the simulate call
- Test your site under various network conditions
Troubleshooting
MCP Server Not Starting
Problem: MCP server fails to start or shows errors
Solutions:
- Verify Node.js version is 18 or higher
- Check that npm is working:
npm --version - Try running the server manually:
npx -y @emuluxe/mcp-server - Check the IDE's output panel for error messages
- Ensure your API token is valid and not expired
Tools Not Available to AI Agent
Problem: AI agent doesn't see Emuluxe tools
Solutions:
- Verify MCP configuration file is correct
- Restart your IDE to reload MCP configuration
- Check the IDE's MCP server status
- Verify the server is running (check output panel)
- Try reinstalling the MCP server:
npx -y @emuluxe/mcp-server@latest
Authentication Errors
Problem: "Invalid API token" or authentication failures
Solutions:
- Verify your API token is copied correctly (no extra spaces)
- Check if the token has expired in your dashboard
- Generate a new token and update your configuration
- Ensure your subscription is active (Pro or Enterprise)
- Contact support if the token should be valid
Deep Link Not Opening
Problem: Simulation deep link doesn't open IDE extension
Solutions:
- Ensure the Emuluxe IDE extension is installed
- Verify the extension is enabled in your IDE
- Try manually opening the extension and entering the simulation ID
- Use the manual bridge link provided by the MCP server
- Check if your IDE supports deep-link protocols
Simulation Not Starting
Problem: Simulation fails to start after MCP call
Solutions:
- Verify the URL is accessible and valid
- Check your internet connection
- Ensure the URL uses HTTP or HTTPS
- Try a simpler URL to test if the issue is URL-specific
- Check the MCP server output for detailed error messages
Performance Issues
Problem: MCP server is slow or unresponsive
Solutions:
- Check your internet connection speed
- Verify the Emuluxe API status (check status page if available)
- Close unused simulations to free up resources
- Try using a different network profile
- Contact support if issues persist
Best Practices
Security
- Token Management: Never commit API tokens to version control
- Environment Variables: Use environment variables for sensitive data
- Token Rotation: Regularly rotate your API tokens
- Access Control: Use appropriate token permissions
- Audit Logs: Regularly review API usage in your dashboard
Workflow Optimization
- Batch Operations: Group multiple simulations for efficiency
- Device Selection: Use devices relevant to your target audience
- Network Conditions: Test under realistic network profiles
- Result Caching: Save analysis results for comparison
- Automated Schedules: Set up recurring automated tests
AI Agent Interaction
- Clear Requests: Be specific about what you want to test
- Context Provision: Provide relevant context about your project
- Result Review: Always review AI-generated results
- Iterative Testing: Use AI suggestions to improve iteratively
- Human Verification: Verify critical findings manually
Team Collaboration
- Shared Configurations: Use consistent MCP configurations across team
- Token Management: Use team tokens for shared workflows
- Documentation: Document your MCP setup and workflows
- Training: Train team members on MCP usage
- 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:
- Explore IDE Extensions for deeper IDE integration
- Learn about AI Analysis for automated diagnostics
- Configure CLI Toolchain for command-line automation
- Set up Webhooks for event-driven workflows
- Explore REST API for programmatic access
For additional help, visit the Help Center or contact support@emuluxe.com.