
The Spur MCP in action

Using the Spur MCP alongside other MCP tools.
Common workflows
Discover and Run Tests
“Run any tests I have for checkout”The agent finds matching tests and lets you run them directly from the conversation.See this in action
Analyze Failed Tests
“What went wrong in this run?”The agent reviews step results, console logs, and screenshots to surface the root cause.
Summarize Test Coverage
“What is missing from my checkout flow test coverage?”The agent reads all your tests across suites and environments to identify gaps.
Fix Raised Bugs
“Help me fix the bug from this failed test”The agent pulls failure details, logs, and context to help you resolve issues in your code.See this in action
Create Tests from Code
“Generate and save tests for this PR”The agent analyzes your code, generates test steps, and creates them directly in Spur via
create_test — no manual copy-paste required.See this in actionRun and Triage Test Plans
“Run the regression suite and tell me what failed”The agent triggers a full test plan run, then walks through every failure with detailed context for each one.See this in action
Connecting with Other MCP Tools
“Run the Spur test that covers this Jira ticket and this GitHub PR”Connect other tools, providing additional context to optimize your testing. Let your AI agent decide what to test.See this in action
In-Sprint Test Generation
“Here’s PR #247 — generate test cases for the search modal changes”Use Claude Code with your codebase context to generate, run, and iterate on tests directly from PRs and tickets — all within your sprint cycle.
Tool naming pattern
Most entity tools use these naming patterns:list_<entities>reads many rows filtered by asearchobject, or one row in full when you pass that entity’s own id (test_id,suite_id,plan_id,env_name,run_id,table_id,folder_id)create_<entity>andupdate_<entity>write one rowbulk_update_<entities>applies one state change to up to 200 rows at onceget_<thing>reads one computed thing that is not an entity row (a run’s evidence, guidance, coverage)run_<thing>/stop_<thing>act on runs
search, a single-record edit, and a bulk set.
Migrating a skill from the previous tool surface? The MCP server exposes
get_announcements, a machine-readable changelog with every rename, removal, and new tool. Ask your agent to “call get_announcements and update this skill” and it walks through the changes. On https://app.spurtest.com/api/mcp, Spur answers a call to most removed tool names with the replacement, so a broken skill leads to its fix. See Migrating from the previous tool surface.Available tools
Discovery
Discovery
list_tests – Lists tests, or reads one in full with test_id (steps, environments, viewports, scenario rows, login wiring, owner, and run configuration). The search object filters by id, suite_id, name_contains, steps_contains, test_type, is_draft, is_snoozed, saves_login_state, or owner_email. Pass login_state_for: { suite_id, test_type } to list the login tests a new test in that suite and platform can reuselist_suites – Lists suites with their environments, env key names, and connected scenario table. Pass suite_id to also get the description, tests, and dependency graph. The search object filters by id, name_contains, folder_id (use null for the top level), or environment_namelist_folders – Lists folders, or one folder with its suites via folder_idlist_scenarios – Lists scenario tables with columns and row names. Pass table_id to see every cell value, one page of rows at a time. max_rows sets the page size (10 by default, up to 100), and offset sets the first rowlist_environments – Lists environments with type and validity status. Pass env_name to see every property with its id — needed for {{env_key_id:N}} references. Filters: env_type, is_valid, name_contains. Properties shared by every test are labeled “(applies to all tests)”list_test_plans – Lists test plans with each plan’s schedule. Pass plan_id for the full per-suite config (required before update_test_plan, which replaces the suite list)list_test_runs – Test runs, newest first, grouped by the batch that triggered them, with review status, public link, and exported tickets (Jira, Linear, GitHub, and so on) on each row. Defaults hours_ago to 24; pass a larger value to reach further back. The search object filters by task_id, test_id, suite_id, env_name, run_name_contains, status, review_status, and has_ticket (true keeps runs with an exported ticket, false finds the ones not filed yet). Use get_coverage_snapshot for aggregates over a window instead of paging rowslist_test_plan_runs – Recent plan runs with pass/fail counts. With run_id, returns every test in that run — failure reason, warnings count, review status, latest note, and task_id, failures first. This is the one call for batch triageget_test_run – Evidence from one run, named by exactly one of task_id, test_id, or public_id (from a /t/<public_id> share link). include picks the sections in one call: overview (start here, lists any exported tickets filed from the run), steps, console, network, screenshots, and har. Request har explicitly to get a download link that requires a signed-in Spur browser session. stepRef narrows steps and screenshots — use the label the app shows, "Step 6" for a whole step or "Step 6.14" for one result. stepRef is required for screenshots. position (before, after, or both) picks the screenshot frame. contains, limit, and offset page the console and network logs; grep with contains rather than pulling a whole logget_coverage_snapshot – Whole-window coverage aggregates computed server-side over every run in the window: runs and failures per environment, distinct tests run per suite × environment, suites with zero runs, browser and viewport totals, and every failed run. Use this for coverage reports instead of paging list_test_runsget_test_guidance – Returns Spur’s test-writing best practices and the full step format reference. Pass topic: all | general | step_formats | organization. Call this before create_test or update_test so generated steps use the correct syntaxsearch_docs – Read-only. Searches the Spur documentation at docs.spurtest.com and returns the best-matching page, in full when it is short enough, followed by other relevant passages, with links. Pass a query in Spur’s own terms where possible, for example scenario tables. Agents call this before answering questions about how Spur works, where a page or setting is, or what a Spur term means, and link the page they usedTest execution
Test execution
run_tests – Runs one or more tests in a single collection run, grouped by shared configuration. Specify env_name along with optional viewport, browser, and scenario_row_name. For native tests, optional device and os_version run a test on a different device from the one in its saved Device Settings. Spur refuses a value or device and OS pair that the run modal doesn’t offerrun_test_plan – Triggers a full test plan run across all configured suites and environments. Optional device and os_version apply to every native test in the runstop_test_runs – Stops runs in progress: named runs by task_ids, or every run in one batch by run_id. Runs that already finished are left as they areTest plans
Test plans
create_test_plan – Creates a test plan grouping suites and environments for coordinated execution. Accepts a structured schedule: { frequency: { unit, value }, days?, first_run_at?, is_active? } — no raw cron. unit is hours (value 1–23), days (1–6), weeks (1–12), or month (1, 2, 3, 4, or 6). weeks with value 1 needs days as UTC weekdays. first_run_at is ISO 8601 with a zone; its time of day in UTC becomes the run time. If omitted, the requested start defaults to 30 minutes from now. The next run must be at least 15 minutes away. Day or month intervals greater than one follow calendar dates, rather than an elapsed interval from the requested startupdate_test_plan – Edits a test plan. suites and environments each replace the whole list — call list_test_plans(plan_id) first and pass back every entry you keep. schedule replaces the whole schedule; to pause, send the complete schedule with is_active: false, including frequency, days for a one-week schedule, and a valid future first_run_at that retains the intended UTC time and calendar pattern. schedule: null removes the schedule; omit the field to leave it unchangedEnvironment properties
Environment properties
update_environment_properties – Sets, adds, or removes property values on one environment: link and domain URLs, headers, HTTPS credentials, global variables, secrets, and route overrides. Pass env_name and a properties array where each entry has name, optional type (required when adding a new property name), and value. Set value to null to remove this environment’s value while keeping the property for others, or omit it to keep the current value. Headers also take optional header_name and url_pattern. For an HTTPS credential (type http_credential), value is the password and username is the username. A new credential needs both, and the password is always masked. Set applies_to_all_tests on a header, HTTPS credential, or route override to use it on every test run, as described in Apply to all tests. This setting belongs to the property, so it holds in every environment. Every entry is checked before anything is written. Builds, prompt overrides, and warning suppressions are refused because they have their own pages in the app. Manage warning suppressions on the Memory pageApplications, announcements, and feedback
Applications, announcements, and feedback
applications – Lists all applications on your account, or switches the active one. All subsequent tool calls use the newly selected applicationget_announcements – Machine-readable changelog of MCP tool changes: renames, removals, new tools, and field renames. Pass since (an announcement id or ISO date from a previous call) to get only what is new. Call this when a tool or argument you expected is missing, or when you are asked to update skillsgive_feedback – Sends a report to the Spur team when a tool errors, returns something confusing, or lacks a capability you need. You can also ask the agent to pass along your feedback. Include what you expected, what happened, and any workaround in message, with an optional tool_name. Keep secrets and credentials out. If the report fails, continue the task without retryingAccessibility
Accessibility
These tools read the accessibility (a11y / WCAG) findings collected while your tests run. They only appear when your account has the Accessibility add-on with MCP access. Ask your Spur contact to enable it. Accessibility runs on web applications only, not native iOS or Android. Findings are reported per viewport (
web_desktop, web_mobile, web_desktop_mobile), so desktop and mobile are separate reports.get_accessibility – The current accessibility state of the active application: open defects by severity, WCAG 2.2 A/AA coverage, and the worst journey findings with the tests and flows that reach them. Scope with env_name (or env_id) and test_type; omit both for the latest report across environmentsget_a11y_fix_plan – An actionable, worst-first fix plan for the whole application. Each defect includes a plain-language fix plus source anchors (exact file:line references or grep keys) so a coding agent can locate and fix the issue in your own repositoryget_test_a11y_fix_plan – The same fix plan scoped to a single run. Pass a task_id (a specific run) or a test_id (its latest run). Use this for “fix the a11y issues this test found”; use get_a11y_fix_plan for the application as a wholelist_a11y_findings – Lists individual findings with page URLs, markup, fixes, source anchors, and evidence references. Filter by rule, severity, host, test, or run. Use limit and the returned cursor to page through findings. Suppressed findings are excluded unless you request themget_a11y_evidence – Returns a finding’s screenshot. Copy its screenshot_ref and optional bounding_box from the report or fix plan to see the whole frame or crop to the elementgenerate_a11y_journeys – Generates and saves accessibility journeys: tests that reach states such as an open dialog or a form showing errors. Choose the destination suite with the user first, then pass its suite_id. An environment is required; when several sites or renderings are available, choose the target and viewport too. Each journey starts a browser and can take several minutes. Use dry_run: true when you want to preview candidates, then only to generate selected journeys. Use from_login_test_id for signed-in journeys. For goals such as “changing the zip code”, pass goals — up to 20 per call, with optional explicit start_url and states. Confirm goals before calling from an external MCP client because generation starts immediately. An existing goal is skipped unless regenerate is trueget_a11y_journeys – Lists the accessibility journeys already generated for the application: whether each finished, how long it took, and how many findings it produced. Use it to check on a generation started earlier, since findings land after the generating call returnsstop_a11y_journeys – Stops a running journey generation. Pass the collection_run_id that get_a11y_journeys reports for runs still in progress. Journeys already running finish their current step and close cleanly, so a large generation stops within a minute or twoScoping tools to an environment
Report tools such asget_accessibility accept env_name (case-insensitive) or env_id. If both are given, env_id takes precedence. An unknown environment name returns an error listing the available environments. Read tools can use the latest report across environments when both are omitted; journey generation requires an environment.
Migrating from the previous tool surface
Spur replaced the previous tool surface end-to-end. Onhttps://app.spurtest.com/api/mcp, Spur answers a call to a removed tool name below with its replacement, so an out-of-date skill leads you to its fix. The exception is get_test_details, which returns a tool-not-found error. Ask your agent to “call get_announcements and update this skill” for the full guide.
Read tools
Write tools
Field renames
Apply these wherever your skill builds arguments:- On
create_testandupdate_test:title→name - On
create_test,update_test, andbulk_update_tests:save_login_state→saves_login_state - On
update_test:allowed_viewports→test_type(a web test can switch between web values; a platform change needs a new test) - On
list_scenariosandupdate_scenario_table:table_name→table_id - On
list_tests:suite_idandquery→search: { suite_id, name_contains }
How to set up
Setup Instructions
Get started with Cursor, Claude Code, GitHub Copilot in VS Code, or ChatGPT.
Best practices
- Allow read-only tools; keep writes on manual approval: Set your MCP client to auto-approve read-only Spur tools (
list_*,get_*). Keep the write tools on manual approval so you can review each change before it lands:run_tests,run_test_plan,stop_test_runs,create_test,update_test,bulk_update_tests,create_suite,update_suite,create_folder,update_folder,create_scenario_table,update_scenario_table,create_test_plan,update_test_plan,update_test_runs,update_environment_properties,give_feedback,generate_a11y_journeys, andstop_a11y_journeys. Theapplicationstool can switch the active Application, so review calls that switch it too. - Grep the logs, don’t pull them whole: When you call
get_test_run(include: ["console", "network"]), passcontainsto filter to the lines you care about. Uselimitandoffsetto page. - Read before you bulk-write:
bulk_update_teststakes the idslist_testsjust returned. Show the user the matched names before applying the change. - Model quality matters: More capable models produce better results when choosing the right tools and interpreting test output. Smaller models may need more explicit guidance.
