Sync local tests with Shiplight cloud — push and pull YAML test cases, templates, and functions between your repo and the cloud. Requires a Shiplight cloud subscription.

Shiplight Cloud Sync local YAML test cases, templates, and TypeScript functions with the Shiplight cloud using MCP tools. Primarily used to push local tests up to the cloud (and pull cloud tests back down) so they can run on a schedule, be shared with your team, and integrate with CI. Also manages test runs, environments, folders, suites, and accounts via the REST API. Setup Requires a [Shiplight cloud subscription](https://www.shiplight.ai) and a SHIPLIGHT API TOKEN . If cloud MCP tools ( save test case , get test case , etc.) are not in the tool list, the token is missing. Tell the user: Cloud tools are not available. Get your API token from https://app.shiplight.ai/settings/api tokens, set SHIPLIGHT API TOKEN in your project's .env file, then reconnect MCP ( /mcp ). If the user provides a token, append it to the project's .env file (create if needed) and tell them: "Saved to <project /.env — make sure .env is in your .gitignore . Reconnect MCP ( /mcp ) to activate cloud tools." All REST API calls require: Error Handling Error Action 401 Unauthorized Token is invalid or expired — ask user to check SHIPLIGHT API TOKEN in .env 403 Forbidden Insufficient permissions — inform user 404 Not Found Resource not found — report to user 422 Validation Show validation message to user Tool not found Token is missing — guide user through setup above MCP Tools These tools are available when SHIPLIGHT API TOKEN is set. Prefer file path over passing content directly (saves tokens). Always use output format: 'yaml' for get test case . Upload: save test case , save test account , save template , save function Download: get test case , get template , get function Account: save test account — create/update test account with optional storage state path to upload local browser session to cloud ID Tracking After uploading, add the returned cloud ID to the local file so future saves update instead of creating duplicates: Artifact Local file ID field Test case .test.yaml test case id: 123 (top level YAML field) Template templates/ .yaml template id: 45 (top level YAML field) Function helpers/ .ts @function id 67 (JSDoc tag per export) REST API Base URL: https://api.shiplight.ai Test Cases List Test Cases Query parameters: Param Type Description ids string Comma separated test case IDs folderId number Filter by exact folder folderIdRecursive number Filter by folder and all descendants labelIds string Comma separated label IDs (OR logic — matches test cases with ANY of the labels) createdBy string Filter by creator user ID orderBy string Order by field (default: "id" ) order asc \ desc Order direction (default: "desc" ) limit number Max results to return Response: { data: [{ id, title, test flow, folder id, ... }], count: number } Get Test Case Response: { id, title, test flow, folder id } Delete Test Case (soft delete) Marks the test case and its results as deleted (soft delete — records are retained but hidden from queries). Response: { success: true, message: "Test case deleted" } Move Test Cases to Folder Batch update the folder assignment for multiple test cases. Set folder id to null to move to root. Body: { test ids: number[], folder id: number null } Response: { success: true, data: [/ updated test cases /], message: "Successfully updated 2 test cases" } Test Data List Test Data Use ids to fetch specific files: Response: array of { organization id, id, name, s3 path, created at, updated at, usage count? } Get Test Data Response: { organization id, id, name, s3 path, created at, updated at } Download Test Data File Streams the file from S3 as application/octet stream . Test Runs List Test Runs Query parameters: Param Type Description testPlanId number Filter by test plan trigger string Filter by trigger ( "API" , "MANUAL" ) result string Filter by result ( "PASSED" , "FAILED" ) limit number Max results to return Response: array of { id, status, result, trigger, start time, end time, duration, total test case count, passed test case count, failed test case count } Get Test Run Details Note: This endpoint has no /v1/ prefix . Response: Trigger Test Run Run a test case, test suite, or a combination in the cloud. By test case: By test suite: Generic (multiple test cases, suites, and/or labels): By labels (run all test cases with any of the specified labels): Body (all trigger endpoints): Field Type Description trigger string Required. Use "API" test case ids number[] Generic endpoint only — test case IDs to run test suite ids number[] Generic endpoint only — test suite IDs to run label ids number[] Generic endpoint only — label IDs; resolves to test cases with ANY of these labels (OR logic). Can be combined with test case ids and test suite ids environment { id?: string } Override environment Response (201): test run object with { id, status, result, ... } After triggering, poll GET /v1/test runs?limit=1 or GET /run results/<id to check status. Get Test Case Result Note: This endpoint has no /v1/ prefix . Response: { id, test case id, test run id, result, status, duration, environment name, environment url, video, trace, report s3 uri, report, error } The video , trace , and report s3 uri fields contain S3 URIs — use the Artifacts endpoint to download them. The report field contains step by step execution details in report[0].resultJson — each step has description , status , message , duration , and artifact S3 URIs ( screenshot s3 path , messages s3 path , etc.). Environments List Environments Response: array of { id, name, url } Get Environment Response: { id, name, url } Variables Environment scoped variables — the cloud equivalent of variables in playwright.config.ts . Use isSensitive: true for secrets (passwords, API keys) so they're masked in logs. List Variables Response: array of { id, name, value, environment id, is sensitive } Test Accounts List Test Accounts Query: environmentId (number, optional but recommended) — filter by environment. Response: array of { id, name, username, environmentId, loginConfig } Get Test Account Response: { id, name, username, password, environmentId, loginConfig } Forward Email Configs Forward email configs store the Mailgun forwarding address and extraction filters used by email based login and verification flows. All responses are scoped to the organization associated with SHIPLIGHT API TOKEN . List Forward Email Configs Returns all forward email configs for the organization, ordered by created at descending. Response: array of { id, organization id, name, forward email, extraction type, prompt, filter from email, filter to email, filter subject, filter body contains, created at, updated at } Get Forward Email Config Response: { id, organization id, name, forward email, extraction type, prompt, filter from email, filter to email, filter subject, filter body contains, created at, updated at } Fields: Field Type Description id number Forward email config ID organization id string Organization that owns the config name string Human readable config name forward email string Mailgun forwarding inbox address extraction type string Extraction mode, such as verification code , activation link , or custom prompt string Optional custom extraction prompt filter from email string Optional sender filter filter to email string Optional recipient filter filter subject string Optional subject filter filter body contains string Optional body text filter created at string ISO timestamp updated at string ISO timestamp Folders List All Folders Optional query: ?search=keyword Response: array of { id, name, description, parentId, pathIds } List Folders by Parent Omit parentId entirely for root level folders. Response: array of { id, name, description, parentId } Get Folder Response: { id, name, description, parentId, pathIds } Create Folder Body: { name: string, description?: string, parentId?: number null } Response (201): { success: true, data: { id, name, description, parentId } } Update Folder Body: { name?: string, description?: string } Response: { success: true, data: { id, name, description } } Delete Folder Response: { success: true } Move Folder Move a folder to a different parent. Set parentId to null to move to root. Body: { parentId: number null } Response: { success: true } Test Suites Test suites group test cases for organized execution. Use suites to manage which test cases run together. List All Suites Response: array of { id, title, description, testCount, createdAt, updatedAt } Get Suite Returns suite metadata and its test cases. Always use ?fields= to select only the columns you need — without it, the endpoint returns full test case entities which is too expensive. ?fields= accepts a comma separated list of columns: id , title , description , status , folder id , test type , created at , updated at , url Response: Create Suite Body: { title: string, description?: string } Response (201): { id, title, description, createdAt, updatedAt } Update Suite Body: { title?: string, description?: string } Response: { success: true, message: "Test suite updated successfully" } Delete Suite Response: { success: true, message: "Test suite deleted" } Add Test Cases to Suite Body: { testCaseIds: number[] } Response: { success: true, message: "Test cases added to suite successfully" } Remove Test Cases from Suite Body: { testCaseIds: number[] } Response: { success: true, message: "Test cases removed from suite successfully" } Labels Labels let you tag test cases (e.g., daily regression , pre merge ) and trigger runs by label instead of manually managing suites. List Labels Response: { success: true, data: [{ id, name, color, organizationId, createdAt, updatedAt }] } Create Label Body: { name: string, color: string } Response (201): { success: true, data: { id, name, color } } Update Label Body: { name?: string, color?: string } Delete Label Add Labels to Test Case Body: { labelIds: number[] } Remove Labels from Test Case Body: { labelIds: number[] } Get Labels for Test Case Response: { success: true, data: [{ id, name, color }] } Get Test Case IDs by Label Response: { success: true, data: [101, 102, 103] } Templates (Reusable Steps) Reusable test step sequences that can be referenced from test cases via template: in YAML or reference id in the cloud. The API uses the legacy name "reusable steps". Get Template Response: { id, name, description, statements } Test Functions Custom TypeScript functions that can be called from test cases via call: "file export" in YAML. Get Test Function Response: { id, name, description, code, status } Artifacts Download S3 File Download test artifacts (videos, traces, reports) referenced by S3 URIs in test case results. Query: uri (string, required) — S3 URI from test result fields ( video , trace , repo