Skip to main content
MCP (Model Context Protocol) is a way to give your AI assistants and agents access to external tools and data — so they can take actions on your behalf, not just answer questions. With Spur’s MCP server, your AI assistant can run tests, analyze results, and help you debug failures — all without leaving your editor.
The Spur MCP in action

The Spur MCP in action

Using the Spur MCP alongside other MCP tools

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 action

Run 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 a search object, 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> and update_<entity> write one row
  • bulk_update_<entities> applies one state change to up to 200 rows at once
  • get_<thing> reads one computed thing that is not an entity row (a run’s evidence, guidance, coverage)
  • run_<thing> / stop_<thing> act on runs
The same field names appear in a list 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

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 used
create_test – Creates and saves a new test to a suite. Requires suite_id, name, env_key_name, test_type, and steps. Use list_suites first to discover valid values. The agent shows you a full summary and asks for approval before savingupdate_test – Edits one test by test_id. Content fields: name, description, steps (replaces every step), env_key_name, web_path, test_type. Run configuration fields: owner_email, location, location_column (runs each scenario from a Test Run Location column), network_throttle, user_agent, headers, record_har, and har_url_filters. State fields: is_draft, is_snoozed, saves_login_state. Providing steps replaces the whole step list, so include every step you want to keep. Omitted fields stay as they are; every field is checked before anything is writtenbulk_update_tests – Applies one state change to up to 200 tests in one call. Pass the ids returned by list_tests after the user has seen the matched names, plus a set object with any of suite_id, is_draft, is_snoozed, saves_login_state, or owner_email. Use this to snooze, unsnooze, mark ready, set an owner, or move tests between suites. Per-test content stays in update_testgenerate_test_steps_from_loom – Turns a public Loom video into a draft list of test steps. Does not save on its own — normalize the draft with get_test_guidance, confirm suite and environment, then call create_testcreate_folder / update_folder – Manage folders that group suites. Folders do not nest; names are unique per application. Move a suite into a folder with update_suite(folder_id)create_suite – Creates an empty suite. Add tests with create_test, or move existing tests in with bulk_update_tests(set: { suite_id })update_suite – Edits one suite: name, description, folder_id, environment_names, scenario_table_id, and dependencies (the full ordering graph, so read list_suites(suite_id) first). scenario_table_id: null disconnects the current tablecreate_scenario_table / update_scenario_table – Create a scenario table or edit its columns and rows. update_scenario_table replays every column and row operation against an in-memory copy first, so a request that cannot complete fails with nothing changed. Use add_rows to append rows, and add_columns with type: "run_location" to add a Test Run Location column; a delete on a column a test still reads is refused
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 are
update_test_runs – Sets a review status (Unreviewed, Needs Investigation, Needs Rework, Bug, Closed — the labels the app shows) on runs from a test plan, or turns a public share link on or off for any run. Pass the task_ids from list_test_runs or list_test_plan_runs(run_id), a set object with review_status and/or is_public, and an optional note. Needs Rework marks the test as a draft
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 unchanged
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 page
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 retrying
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 two

Scoping tools to an environment

Report tools such as get_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. On https://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_test and update_test: title → name
  • On create_test, update_test, and bulk_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_scenarios and update_scenario_table: table_name → table_id
  • On list_tests: suite_id and query → search: { suite_id, name_contains }

How to set up

Setup Instructions

Get started with Cursor, Claude Code, GitHub Copilot in VS Code, or ChatGPT.
Authentication uses OAuth by default. When you connect for the first time, your browser will open to authorize access to your Spur account. For CI, bots, and headless agents that can’t sign in, use an API key instead.

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, and stop_a11y_journeys. The applications tool 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"]), pass contains to filter to the lines you care about. Use limit and offset to page.
  • Read before you bulk-write: bulk_update_tests takes the ids list_tests just 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.