Squidler MCP Server
Squidler.io
AI coding agents excel at the Build phase of a web app, but struggle with the Verify phase. Squidler is designed to validate your web app as a human based on natural language use cases, and without writing brittle, DOM-dependent tests.
Squidler is not just a testing tool; it enables your coding agent to analyze its own work from a user perspective, decoupled from the implementation. Squidler closes the autonomous Build → Verify → Fix loop, and enables you to act as the true human-in-the-loop who manages the outcome rather than the output.
Squidler MCP Server
With the Squidler MCP server you enable you AI coding agents, like Cursor, Claude Code, Replit, Lovable etc to work with Squidler. This means that you can have your coding agent build a feature, describe the use case in natural language for Squidler, ask Squidler to test it, to get the details of how the test run went, and details of all problems or friction that were found when using your web app.
Below are details and example for how to get started with Squidler via MCP. If you have any questions, don't hesitate to reach out to [email protected].
Configuration
Add to your MCP client configuration:
{
"mcpServers": {
"squidler": {
"transport": "http",
"url": "https://mcp.squidler.io",
"headers": {
"Authorization": "Bearer YOUR_SQUIDLER_API_TOKEN"
}
}
}
}
Get your API token from squidler.io/integrations/api-keys.
Built-in Agent Guidance
The MCP server includes built-in instructions that teach your AI agent a Test-After-Feature Workflow. When connected, the agent automatically knows how to use Squidler without you having to explain it. The workflow it follows:
- Run existing tests — verify nothing is broken by the new feature.
- Investigate failures — use test run outcomes and events to understand what failed. Fix the code if it's a bug, or update/delete the test if it's obsolete.
- Label the feature — create a label for the completed feature (e.g., "User Login", "Checkout Flow") to organize your test catalog.
- Cover the new feature — create test cases for the new behavior using the guided conversation (
test_case_create), tag them with the feature label, and run them to confirm they pass.
- For pages with no clickable link (hidden endpoints, deep links), write steps as: "Navigate directly to /path"
- Confirm green — re-run until all tests pass, then move on to the next feature.
Over time this builds a growing catalog of tests organized by feature that prevents regressions and documents how the system is meant to work.
Resources
| Resource URI | Description |
|---|
squidler://help | Server documentation and available capabilities |
squidler://sites | List of all available sites |
Tools
Sites
| Tool | Description |
|---|
sites_list | List all available sites |
site_details | Get site information (owner, URL, name, frontend link) |
site_create | Create a new site |
Problems
| Tool | Description |
|---|
problems_summary | Overview of problems (total count by type) |
problems_list | List problems with pagination and filtering |
problem_get | Get detailed information about a specific problem |
problem_resolve | Mark a problem as resolved |
problem_dismiss | Mark a problem as false positive |
Test Case Creation
| Tool | Description |
|---|
test_case_create | Start a guided conversation to create a high-quality test case stored on Squidler. Leverages site page knowledge, existing test coverage, and testing best practices. Returns a conversationId — continue with test_case_create_respond. |
test_case_create_respond | Continue an in-progress test-case-creation conversation — answer questions, review the draft, or confirm creation. Works for both test_case_create and test_case_create_standalone. |
Test Cases
| Tool | Description |
|---|
test_cases_list | List all test cases |
test_case_get | Get test case details |
test_cases_list_by_label | List test cases with a specific label |
validate_test_case | Validate a test case for quality, feasibility, and best practices |
test_case_update | Update an existing test case (includes automatic validation feedback) |
test_case_delete | Delete a test case |
test_case_run | Run a single test case |
test_cases_run_all | Run all test cases |
test_cases_run_by_label | Run test cases with a specific label |
Repo-Stored / Standalone Test Cases
For agents that manage test cases as markdown files in their own repo (no Squidler storage). Covers the create → validate → run → promote cycle. Particularly useful for local dev iteration: pair test_case_run_standalone with the @squidlerio/squidler-mcp npx proxy to route runs through a local Chrome against http://localhost:<port>.
| Tool | Description |
|---|
test_case_create_standalone | Guided conversation that produces standalone markdown text (no Squidler storage). The architect asks more clarifying questions than the site-bound flow since it has no site context. Final result is {filename, markdown} for the agent to write to its local repo. Continue with test_case_create_respond. |
validate_test_case_text | Validate a System B test case file's markdown without running it. Returns typed errors for frontmatter, schema, and body problems, each with a file-line number when available. Use before writing generated files, after hand-edits, or in CI hooks. |
test_case_run_standalone | Run a test case supplied as inline markdown against a custom baseUrl (typically a localhost dev server or preview deploy). Step Optimization / Fixed Actions automatically draw on prior runs of the same (org, contentHash). Returns a checkId. |
test_case_runs_standalone_list | List past standalone runs for the caller's org with a given identifier, most-recent first. Standalone counterpart to test_runs_list — useful for dedup-before-rerun via content hash. |
test_case_promote | Promote a repo-stored markdown file into a site-bound test case on Squidler. Idempotent on (siteId, identifier): produces UNCHANGED, UPDATED, or CREATED depending on content-hash comparison with the latest revision. |
Test Runs
| Tool | Description |
|---|
test_runs_list | List execution history for a test case |
test_case_poll | Long-poll for test execution status updates and events |
test_run_outcome | Get pass/fail outcome and goal results for a test run |
test_run_events | Get detailed execution events and screenshots |
test_run_stop | Stop a currently running test |
pending_checks_list | List checks queued (waiting to start) for a site, plus the currently running checks each is blocked by. Use when test_case_run returns queued: true. |
Labels
| Tool | Description |
|---|
labels_list | List all labels |
label_get | Get label details |
label_create | Create a new label |
label_update | Update a label |
label_delete | Delete a label |
test_case_labels_add | Add labels to a test case |
test_case_label_remove | Remove a label from a test case |
Headers
| Tool | Description |
|---|
headers_list | List custom headers for a site |
header_add | Add or update a custom header |
header_delete | Remove a custom header |
Credentials
| Tool | Description |
|---|
credentials_list | List available login credentials |
credentials_create_userpass | Create credentials with explicit email/username and password |
credentials_create_email | Create credentials with auto-generated @squidlermail.io email for verification testing |
credentials_create_oidc | Create OIDC credentials for sites using OpenID Connect |
Persona Reviews (UX Feedback)
| Tool | Description |
|---|
personas_list | List all available personas for UX reviews |
persona_review_run | Run a persona review on a validated test case |
persona_review_findings | Get detailed findings from a completed persona review |
persona_findings_list | List persona findings for a site and persona, filtered by status |
persona_finding_triage | Update finding status (RESOLVED, DISMISSED, IN_PROGRESS, OPEN) |
Account Management
| Tool | Description |
|---|
account_status | Check current plan, remaining test quota, and available upgrades |
account_upgrade_url | Generate a short-lived URL to upgrade your plan |
Prompts
| Prompt | Description |
|---|
create-test-case | Guided test case creation with goals, steps, and failure strategies |
site-health-check | Quick overview of site quality status with actionable recommendations |
run-test-suite | Run all or labeled tests and monitor results |
get-started-with-squidler | Complete onboarding: create site, generate initial tests, run them |
suggest-initial-tests | Analyze codebase to suggest 2-4 initial test cases |
enhance-tests-from-runs | Analyze test run events to identify and fix test weaknesses |
identify-ux-improvements | Discover usability issues from AI tester friction patterns |
correlate-accessibility-and-ux | Cross-reference accessibility problems with test execution friction |
run-persona-review | Run persona reviews on validated test cases to discover UX issues |
migrate-legacy-tests | Migrate legacy test cases to current format |
Example Prompts
| What you can say | What it does |
|---|
| "Create a site for https://myapp.com called 'My App'" | Register your website with Squidler to start monitoring and testing |
| "Analyze the codebase and create test cases for the key user flows" | Uses guided conversations to create comprehensive test cases covering happy flows, edge cases, and negative tests |
| "Run all my test cases" | Execute your test cases in a real browser with goal validation and issue detection |
| "Show me the results of my latest test runs" | See which goals passed or failed, and understand what happened during execution |
| "Get the detailed test events for test case #1 and analyze the UX" | Review execution logs to identify UX friction and usability issues |
| "Fix the issues preventing test case #1 from passing" | Analyzes test failures and fixes the underlying code issues |
| "Get problem #42 and help me fix it" | Address specific accessibility, functionality, or content issues |
| "Fix all accessibility issues in my site" | Batch-fix WCAG compliance issues by iterating through problems |