mcp

The Squidler MCP Server lets AI agents interact with Squidler to validate new features in a web application. Agents can describe features in natural language, have Squidler run tests or test suites, and retrieve detailed results, including test run outcomes and any friction encountered during testing. Built-in guidance implements a Test-After-Feature workflow: run existing tests, investigate failures, label the feature, cover with new test cases, and confirm green before moving on. The server exposes a set of tools to manage sites, problems, test cases, test runs, labels, headers, and credentials, enabling agents to build, test, and catalog features in an automated yet human-audited loop. Connect your agent (like Cursor, Claude Code, Replit, or Lovable) to the MCP endpoint, provide your API token, and start issuing prompts that drive end-to-end verification of new features against your web app.

Once connected, you can use the built-in prompts and tools to: list and inspect sites, create and run test cases, view test run events and outcomes, manage labels for test organization, and retrieve detailed problem summaries and resolutions. The agent workflow is designed to operate with a Test-After-Feature pattern, ensuring that verifications are performed after feature changes and that regressions are caught early. Documentation and capabilities are accessible via the squidler:// protocol endpoints listed in the Resources section, enabling quick discovery of available sites, tests, and test runs.

Prerequisites:

• Node.js (LTS recommended) or a runtime compatible with the chosen deployment method
• Access to an MCP-compatible runtime environment (local or server) with network access to the Squidler MCP API
• An API token from Squidler (for client configuration)

Option A: Run the MCP server directly (Node.js)

1. Clone the repository: git clone https://github.com/squidler/squidler-mcp-server.git cd squidler-mcp-server

2. Install dependencies: npm install

3. Create a configuration file or set environment variables (example uses env): export SQUIDLER_API_TOKEN=YOUR_SQUIDLER_API_TOKEN export BASE_URL=https://mcp.squidler.io

4. Start the server: npm run start

Option B: Run with a Docker container

1. Build or pull the image (example tag may vary): docker pull squidler/squidler-mcp-server:latest

2. Run the container with required environment variables: docker run -d
   -e SQUIDLER_API_TOKEN=YOUR_SQUIDLER_API_TOKEN
   -e BASE_URL=https://mcp.squidler.io
   -p 8080:8080
   --name squidler-mcp-server
   squidler/squidler-mcp-server:latest

Option C: npx or package manager (if published as an MCP server package)

1. If applicable, you can start via npx with your token: npx -y squidler-mcp-server --token YOUR_SQUIDLER_API_TOKEN

Note: Replace YOUR_SQUIDLER_API_TOKEN with the actual API token. The server will expose an MCP-compatible endpoint for clients to connect and manage the built-in tools and prompts.

Tips and caveats:

• Ensure the API token has permissions to access the Squidler capabilities you intend to use (sites, tests, labels, etc.).
• If you encounter connectivity issues, verify that BASE_URL and network egress are allowed to reach mcp.squidler.io.
• The built-in guidance implements a Test-After-Feature workflow; if test runs fail, inspect test_run_events and test_run_outcome for failure reasons.
• When labeling features, use descriptive labels (e.g., "User Login", "Checkout Flow") to build a searchable catalog of tests.
• Tools are grouped by function (Sites, Problems, Test Cases, Test Runs, Labels, Headers, Credentials); use test_case_run or test_runs_list to observe execution histories.
• If you plan to run multiple agents, consider using per-agent labels and separate test catalogs to avoid cross-contamination of test results.