MCP Server

Introduction

The Skyramp MCP (Model Context Protocol) Server brings powerful automated testing capabilities directly into Agentic IDEs. Generate and execute integration, contract, smoke, fuzz, load, E2E, and UI tests with AI assistance through natural language commands, without ever leaving your development flow.

Skyramp MCP Server is currently available for Cursor IDE.

Installation

Please refer to the Installation Guide for instructions on how to install Skyramp MCP Server.

Getting Started

The MCP is designed to provide a self-service experience to Cursor users. When you have any questions about Skyramp capabilities or guidelines for using a tool, simply ask Cursor and it will leverage internal MCP documentation to provide you with the most relevant and up-to-date guidance.

If Cursor does not recognize the MCP immediately, try entering a few of the example prompts. Once the context is established, it typically functions as expected.

When using Cursor, Skyramp MCP works best when using the Claude Sonnet 4.5 model

Below are some example prompts to help you get started.

Discover Capabilities

• “What can I do with Skyramp?”

• “How do I generate an integration test with Skyramp?”

• “How do I generate a UI test with the Skyramp?”

A sample workflow for creating UI tests with the MCP is outlined below. For instructions on how to create other test types using Skyramp, just ask Cursor.

UI Test Generation

Follow these steps to generate a UI test with Skyramp using the MCP integration in Cursor. Using Skyramp’s Demo Shop, a lightweight e-commerce application for product and order management, we will illustrate how traces can be collected and transformed into reliable tests. Learn more about the Demo Shop.

Trace Collection

Skyramp provides a native workflow for collecting traces that power reliable test generation. By working from traces, Skyramp ensures tests are built on real-world behavior, not assumptions, resulting in resilient tests that accurately mirror user flows and backend interactions.

A trace is simply a log of user actions and system behavior captured during a scenario. Skyramp operates as a man-in-the-middle proxy, capturing both UI activity (via Playwright) and network traffic. It collects data from three key sources:

• Network traffic through the CLI

• Network traffic from the Browser

• UI traces through the Playwright recorder

Skyramp’s test generation engine then correlates these trace files to automatically produce high-fidelity test cases. In the following sections, we’ll walk through how to record your first trace and use it as the foundation for generating a test.

Want to skip straight to test generation? Download the following trace file.
You can find more information on the recorded scenario here.

Start Trace Collection

To start collecting traces, you can use the following prompt in the chat.

The first time you run this command, it might take a while to bring up Skyramp. If you come across issues start the trace collection for the first time, please refer to the 'Trace Collections section of the Troubleshooting guide.

This will trigger Cursor to call the Skyramp function skyramp_start_trace_collection and will launch three new windows on your Desktop:

• Terminal window (records network traffic triggered via shell)

  • Note: The terminal window used when collecting backend calls during the trace, not relevant for UI Test generation

• Playwright Browser (records network traffic triggered via the UI)

• Playwright Inspector (records all UI interactions)

Additional flags

• Viewport-size: ... and use the viewport size "1440, 960"

  • This controls the browser size during trace collection.

  • You can choose from the following predefined sizes:

    • hd - 1280 x 720

    • full-hd - 1920 x 1080

    • 2k - 2560 x 1440

    • 'x,y' - you can choose what height and width you prefer for your trace collection

• Playwright-storage: ... and use the playwright storage path/to/session-file

  • This is useful if you want trace collection to start in an already authenticated state (bypassing login + 2FA)

  • If your login requires 2FA and you don’t yet have a session file created yet, please refer to the 'Handling 2FA' section of the Troubleshooting guide.

If you specify a session file or viewport size during trace collection, those settings will automatically carry over into test generation and execution.

Record Your User Scenario

Now, leverage the freshly spawned Playwright Browser to collect the traces for your UI test scenario. You can record your own custom user interactions or follow our example test case (Record Scenario Section). Here is a quick summary of the scenario:

1. Create a new product

2. Assert the price of the newly added product

3. Create a new order with the new product

4. Cancel the order

5. Delete the product

Stop Trace Collection

Once you have completed your scenario in the Playwright Browser, simply head back to Cursor and ask to stop the trace in the chat.

Stopping trace collection closes the Playwright Browser, Inspector, and the active terminal session. Skyramp will then generate two files in your working directory:

• skyramp-traces.json: Captures all collected network traffic (not required for UI test generation).

• playwright-ui-test.zip: Contains the Playwright trace data used for UI test generation.

Adjustments

You can adjust the prompt to control the following outputs:

• Output Directory: ... and save the traces in the /traces folder

• Playwright Trace File Name: ... and save the playwright trace as skyramp_playwright.zip

• Backend Trace File Name: ... and save the backend trace as skyramp.json

Generate the UI Test

Before generating the tests, ensure you’re using the latest version of the Skyramp MCP by toggling the server off and then back on. Now, with the trace files created, you can simply ask Skyramp MCP to generate the test.

What happens behind the scenes

• Test Generation - Skyramp leverages the playwright-ui-test.zip and generates your test file (ui_test.spec.ts).

• Code Optimization - Skyramp automatically modularizes and parameterizes the code for readability and reuse.

• Error Prevention - Skyramp resolves reference errors, undefined variables, and potential runtime issues.

• Execution Ready - Produces test code with smart selectors and intelligent waits that can be run immediately.

Adjustments

The prompt can be modified to control details such as:

• Language: Adjust the specified language to another supported language.

• Framework: Adjust the specified framework to another supported framework for the selected test language.

• Test File Name: Specify the test file name (e.g., ... and save the file as skyramp_test.spec.ts)

• Output Directory: Specify the output directory for the test file (e.g., ... and save the file to the /tests folder)

• Trace File: Specify the trace file you want to leverage for the test generation (e.g.,... and use the skyramp_playwright.zip as trace)

Execute Your UI Test

Now you can run the tests locally using Playwright. If you don’t have Playwright, refer to the Installation Guide for setup instructions. Before running the tests, ensure you have the latest npm version of Skyramp installed as well. (see the Installation Guide)

If your login requires 2-factor authentication, please refer to the 'Handling 2FA' section in the Troubleshooting guide.

Execution Command

npx playwright test ui_test.spec.ts --reporter

Additional Flags

--headed: Runs the test in a visible browser so you can confirm the scenario step by step.

Test Results

We are using Playwright's List reporter in this guide, printing a line for each test that is being run and listing all failures at the end. You can adjust the reporter behavior following this documentation.

Smart Selector

Local Execution

To enable smart selector capabilities that automatically update flaky selectors at runtime using your own LLM API, make sure to export it as API_KEY as an environment variable. If you don’t have an API key yet, please reach out to the Skyramp team.

export API_KEY

Skyramp Execution

When running the test using Skyramp executor which handles all dependencies and executes the test in a containerized environment, you can add your API key as an environment variable in the MCP client's configuration file.

Navigate to Settings -> Tools & MCP and select 'Edit Configuration' for the Skyramp MCP Server

{
  "mcpServers": {
    "skyramp": {
      "command": "npx",
      "args": [
        "@skyramp/mcp@latest"
      ],
      "env": {
        "SKYRAMP_ENV": "local",
        "API_KEY": "your-api-key",
        "DEBUG": "1"