Cloud

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 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:

Authorization: Bearer $SHIPLIGHT_API_TOKEN

Error Handling

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:

REST API

Base URL: https://api.shiplight.ai

Test Cases

List Test Cases

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases

Query parameters:

Response: { data: [{ id, title, test_flow, folder_id, ... }], count: number }

Get Test Case

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases/123

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).

curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases/123

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.

curl -X PUT -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"test_ids": [101, 102], "folder_id": 5}' \
  https://api.shiplight.ai/v1/test-cases/batch-update-folder

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

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data

Use ids to fetch specific files:

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-data?ids=1,2,3"

Response: array of { organization_id, id, name, s3_path, created_at, updated_at, usage_count? }

Get Test Data

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data/123

Response: { organization_id, id, name, s3_path, created_at, updated_at }

Download Test Data File

Streams the file from S3 as application/octet-stream.

curl -L -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data/123/download \
  -o ./filename.ext

Test Runs

List Test Runs

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-runs?limit=10"

Query parameters:

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.

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/run-results/456

Response:

{
  "testRun": { "id": 456, "status": "COMPLETED", "result": "PASSED" },
  "testCaseResults": [
    { "id": 789, "test_case_id": 123, "result": "PASSED", "duration": 45 }
  ]
}

Trigger Test Run

Run a test case, test suite, or a combination in the cloud.

By test case:

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger": "API"}' \
  https://api.shiplight.ai/v1/test-run/test-case/123

By test suite:

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger": "API"}' \
  https://api.shiplight.ai/v1/test-run/test-suite/1

Generic (multiple test cases, suites, and/or labels):

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger": "API", "test_case_ids": [101, 102], "test_suite_ids": [1]}' \
  https://api.shiplight.ai/v1/test-run

By labels (run all test cases with any of the specified labels):

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger": "API", "label_ids": [22, 18]}' \
  https://api.shiplight.ai/v1/test-run

Body (all trigger endpoints):

Response (201): test run object with { id, status, result, ... }