Integration

MCP server

Let Claude, or any MCP-capable agent, run your test suite and report every step into TestCatalyst, live.

1. Get a token

In TestCatalyst, go to Settings → MCP and click Generate Token (or copy an existing one).

2. Add the server to your MCP client

Add this to your Claude Desktop config (or the equivalent for your MCP client):

claude_desktop_config.json

{
  "mcpServers": {
    "testcatalyst": {
      "command": "npx",
      "args": ["-y", "testcatalyst-mcp"],
      "env": {
        "TC_API_URL": "https://testcatalyst.co",
        "TC_TOKEN": "your-mcp-token-here"
      }
    }
  }
}

TC_API_URL: https://testcatalyst.co for the hosted app, or your local URL if self-hosting.
TC_TOKEN: the token from step 1.

Restart your MCP client after saving.

3. Connect a browser tool

The MCP server tracks and reports runs, but doesn't drive a browser itself. For any test that navigates a real page, also connect one of:

Tool	Config
Chrome DevTools MCP· Recommended	`{ "command": "npx", "args": ["chrome-devtools-mcp@latest"] }`
Playwright MCP	`{ "command": "npx", "args": ["@playwright/mcp@latest"] }`
Claude in Chrome	`Browser extension, install from the Chrome Web Store`

If no browser tool is connected, the agent should tell you which one to install instead of failing partway through a run. That check happens before tc_start_run is called.

The tools

Discover

Tool	When it's used
tc_list_projects	List the projects this token can access. Usually the first call in a session.
tc_get_project_context	Existing test cases and recent bugs for a project, so the agent doesn't duplicate work.
tc_get_test_cases	Fetch test cases, optionally filtered by Jira key or suite.
tc_get_jira_issue	Fetch a ticket's summary, description, acceptance criteria, and comments, plus an auto-detected Figma link, if the ticket text contains one.

Run

Tool	When it's used
tc_ensure_suite	Find-or-create a suite. Idempotent by Jira issue key (preferred) or suite name: pass the same key/name on a re-run so results update the existing suite instead of duplicating it.
tc_start_run	Starts the run and returns a live-view URL. Requires a connected browser tool for web-based tests.
tc_report_step	Report one step after every action. Pass a screenshot for UI steps, or http/response fields for API steps: TestCatalyst renders a request/response snapshot automatically. Mentioning a TC-XXX id links the step to that test case.
tc_get_run	Poll a run's current status and steps.
tc_finish_run	Marks the run passed/failed/stopped, syncs test case results, auto-resolves bugs whose case just passed, and kicks off AI report generation.
tc_save_script	Save the Playwright script written during the run. Required after a passing run: this is what makes the run reusable in CI.
tc_upload_recording	Attach a screen recording to the run, if one was made and the user agreed to save it.

Report

Tool	When it's used
tc_create_bug	Log a bug for human review. Never auto-pushed to a tracker. Mention a TC-XXX id to link it to a test case.
tc_post_jira_comment	Post the run's results or report link directly onto the Jira ticket.

Design & API context

Tool	When it's used
tc_list_figma_frames	List frame names in a Figma file, so the agent can pick the right one from a bare file link.
tc_get_figma_design	Render a specific Figma frame (needs a node-id) to an image, for visual diffing against a live-page screenshot.
tc_check_figma_fields	Extract field-like layer names from a Figma frame and diff them against observed API field names.
tc_list_postman_collections	List the workspace's connected Postman collections by name.
tc_get_postman_collection	Fetch a collection's requests and variables, so the agent can drive API tests without the user describing each endpoint.

A typical session, end to end

tc_list_projects → tc_get_project_context: orient, avoid duplicate work.
tc_get_jira_issue (optional): pull the ticket, and its Figma link if it has one.
tc_ensure_suite: create or reuse the suite, idempotent by Jira key.
tc_start_run: get the live-view URL, share it.
Loop: drive the browser (or call an API directly), calling tc_report_step after every action. Mention a TC-XXX id to link a step to its test case.
On a failure: tc_create_bug.
Optional: tc_get_figma_design / tc_check_figma_fields for design comparison, or tc_list_postman_collections / tc_get_postman_collection to source real API requests.
tc_upload_recording (if agreed) then tc_finish_run.
On a pass: tc_save_script, which makes the run reusable in CI.
tc_post_jira_comment (optional): share the result on the ticket.

Sample prompt

prompt

Use TestCatalyst to test the login flow on http://localhost:3000.

1. List my TestCatalyst projects and pick the most relevant one (or ask me).
2. Check the project context for existing test cases and recent bugs.
3. Start a TestCatalyst run before opening the browser.
4. Navigate to the login page and try logging in with valid credentials,
   reporting each step.
5. If anything fails, file a bug with what you observed.
6. Finish the run and save the script if it passed.