TestOptim MCP server
Commit Nov 9, 2026Allows AI assistants to run QA test suites on web applications, explore new pages, and retrieve detailed bug reports with reproduction steps.
Also known as TestOptim-AI/testoptim-mcp, testoptim-mcp
- Stars
- 0
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 9, 2026
- License
- MIT
What is TestOptim MCP?
TestOptim allows AI assistants to run QA test suites on web applications, explore new pages, and retrieve detailed bug reports with reproduction steps. It exposes 8 tools, such as list_projects, start_test_run, get_test_run.
Summary generated from the project's README
About TestOptim MCP server
TestOptim provides an AI-driven QA platform that allows developers to connect their coding assistants to a real browser testing environment. By integrating this MCP server with clients like Claude Code, Cursor, VS Code, or Windsurf, an AI agent can autonomously execute test suites, explore web application changes, and identify bugs. The server operates via streamable HTTP and requires a TestOptim API key starting with the topt_ prefix for authentication.
Users can manage testing workflows through specific tools such as start_test_run to execute suites or start_exploration to help the platform learn new pages and flows. The server supports granular permissions, meaning an API key can be restricted to specific projects or limited to read-only access. This setup allows an AI to not only find issues but also retrieve detailed reproduction steps, screenshots, and expected versus actual behavior to facilitate rapid debugging and code fixes.
What you can do with it
- 1Execute targeted regression testsAsk your AI assistant to run tests only on specific pages or flows that you have recently modified.
- 2Debug critical application issuesHave the agent identify high-severity bugs and retrieve the exact steps needed to reproduce them.
- 3Update application knowledge baseInstruct the AI to trigger an exploration so the testing platform recognizes new features or site structures.
- 4Automate the fix-test loopDirect the coding agent to run tests after a code change and automatically fix any discovered failures.
Written from the project's README. Every use case is checked against a quote from it.
How to install TestOptim MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall TestOptim MCP in Claude Code
$ claude mcp add --transport http testoptim-mcp https://api.testoptim.com/api/mcpInstall TestOptim MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"testoptim-mcp": {
"url": "https://api.testoptim.com/api/mcp"
}
}
}Install TestOptim MCP in VS Code
.vscode/mcp.json
{
"servers": {
"testoptim-mcp": {
"type": "http",
"url": "https://api.testoptim.com/api/mcp"
}
}
}Install TestOptim MCP in VS Code CLI
$ code --add-mcp '{"name":"testoptim-mcp","type":"http","url":"https://api.testoptim.com/api/mcp"}'Install TestOptim MCP in Codex
$ codex mcp add testoptim-mcp --url https://api.testoptim.com/api/mcpInstall TestOptim MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.testoptim-mcp] url = "https://api.testoptim.com/api/mcp"
Install TestOptim MCP in Gemini CLI
$ gemini mcp add -s user --transport http testoptim-mcp https://api.testoptim.com/api/mcpInstall TestOptim MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"testoptim-mcp": {
"url": "https://api.testoptim.com/api/mcp",
"type": "http"
}
}
}TestOptim MCP tools 8
Detected from the READMElist_projectsstart_test_runget_test_runstop_test_runlist_issuesget_issuestart_explorationget_exploration
| list_projects | — | |
| start_test_run | — | |
| get_test_run | — | |
| stop_test_run | — | |
| list_issues | — | |
| get_issue | — | |
| start_exploration | — | |
| get_exploration | — |
Configuration
TESTOPTIM_TOKEN
| Name | Description | |
|---|---|---|
| TESTOPTIM_TOKEN | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletestoptim-ai/testoptim-mcp is public and reachablegithub.com/testoptim-ai/testoptim-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/testoptim-ai/testoptim-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubTestOptim MCP server
Connect Claude Code, Cursor, VS Code and other MCP clients to TestOptim, so your AI assistant can run QA tests on your web app and read the issues they find.
"Run the QA suite on my project and show me the critical issues."
TestOptim is an AI QA platform: it explores your web app, writes test cases, runs them in a real browser and reports the bugs it finds. Learn more at https://testoptim.com.
TestOptim hosts the server; there is nothing to install or run. This repository holds the setup instructions, ready-to-copy client configs, the server.json that lists the server in MCP registries, and the lhm.plugin.json manifest for the LobeHub MCP marketplace.
- Website: https://testoptim.com
- Endpoint:
https://api.testoptim.com/api/mcp - Transport: Streamable HTTP (stateless;
POSTonly) - Auth: a TestOptim API key, sent as
Authorization: Bearer topt_...
Contents
- Before you start
- Create an API key
- Connect your client
- Agent skill and Claude Code plugin
- Tools
- Example prompts
- Security
- Limits and errors
- Troubleshooting
Before you start
- A TestOptim account with at least one project that has generated test cases. See Generate test cases.
- The Owner or Admin role in your organization, to create API keys.
- Runs started over MCP use your plan's test executions, the same as runs started in the app. They are attributed to the person who created the key.
Create an API key
- In TestOptim, open Settings, then API keys, and select New token.
- Give it a name you will recognise, such as
Claude Code - laptop. - Under Project access, choose All projects or a single project. A single project limits what a leaked key can reach.
- Keep only the permissions you need (see Tools for which tool needs which).
- Copy the token. It starts with
topt_and is shown once.
Then export it in the shell your client starts from, so it never lands in a config file:
export TESTOPTIM_TOKEN="topt_..."
The full guide, with screenshots, is Run TestOptim tests from CI with an API key.
To run tests from a GitHub Actions workflow instead, use TestOptim Run Tests.
Connect your client
Each snippet is also in examples/.
Claude Code
claude mcp add --transport http testoptim https://api.testoptim.com/api/mcp \
--header "Authorization: Bearer ${TESTOPTIM_TOKEN}"
This stores the token in your local Claude Code config. Add --scope user to use it in every project.
To share the server with your team without sharing a token, commit a project .mcp.json instead. Claude Code expands ${TESTOPTIM_TOKEN} from each person's environment (examples/claude-code.mcp.json):
{
"mcpServers": {
"testoptim": {
"type": "http",
"url": "https://api.testoptim.com/api/mcp",
"headers": {
"Authorization": "Bearer ${TESTOPTIM_TOKEN}"
}
}
}
}
Cursor
Add to ~/.cursor/mcp.json, or .cursor/mcp.json in your project (examples/cursor.mcp.json):
{
"mcpServers": {
"testoptim": {
"url": "https://api.testoptim.com/api/mcp",
"headers": {
"Authorization": "Bearer ${env:TESTOPTIM_TOKEN}"
}
}
}
}
Cursor reads TESTOPTIM_TOKEN from your shell or system environment; remote servers don't support envFile.
VS Code
Add to .vscode/mcp.json in your workspace, or run MCP: Open User Configuration for every workspace (examples/vscode.mcp.json). VS Code asks for the key the first time the server starts and stores it securely:
{
"inputs": [
{
"type": "promptString",
"id": "testoptim-token",
"description": "TestOptim API key (starts with topt_)",
"password": true
}
],
"servers": {
"testoptim": {
"type": "http",
"url": "https://api.testoptim.com/api/mcp",
"headers": {
"Authorization": "Bearer ${input:testoptim-token}"
}
}
}
}
Windsurf
Add to your MCP config file (open it from Cascade's MCP settings). Remote servers use serverUrl (examples/windsurf.mcp_config.json):
{
"mcpServers": {
"testoptim": {
"serverUrl": "https://api.testoptim.com/api/mcp",
"headers": {
"Authorization": "Bearer ${env:TESTOPTIM_TOKEN}"
}
}
}
}
Claude (claude.ai and Claude Desktop)
Add TestOptim as a custom connector:
- Open Customize > Connectors, select + Add, then Add custom connector.
- Name it
TestOptimand enterhttps://api.testoptim.com/api/mcpas the server URL. - Under Authentication, choose No sign in.
- Under Request headers, add
Authorizationwith the valueBearer topt_...(your key). - Select Add.
On Team and Enterprise plans an Owner adds it under Organization settings > Connectors, and everyone who uses the connector shares that one key. Use a key limited to one project, and leave out tests:run unless every member should be able to start runs. Claude's Research mode can call connector tools without asking first, which is another reason to keep write permissions off a shared key. To change the key later, remove the connector and add it again.
Other clients
Any client that supports Streamable HTTP with custom headers works. Point it at https://api.testoptim.com/api/mcp and send Authorization: Bearer <your key> on every request. The server is stateless: it doesn't issue session IDs, and it answers GET and DELETE with 405.
Agent skill and Claude Code plugin
The testoptim-qa skill teaches your coding agent the loop: after it changes a page or flow, it re-tests only that area, reads the critical and high issues, fixes them and re-tests. It asks you before every run, because runs use your plan's executions. It follows the open Agent Skills format, so it works in Claude Code, Codex, Cursor, Copilot and other agents that read SKILL.md.
Claude Code plugin
The plugin installs the skill and connects the MCP server in one step. When you enable it, Claude Code asks for your API key and keeps it in your system's secure credential store, so you don't need TESTOPTIM_TOKEN:
/plugin install testoptim --marketplace TestOptim-AI/testoptim-mcp
On Claude Code older than 2.1.275, add the marketplace first:
/plugin marketplace add TestOptim-AI/testoptim-mcp
/plugin install testoptim@testoptim
Other agents
Install the skill with the skills CLI, then connect the MCP server as shown in Connect your client:
npx skills add TestOptim-AI/testoptim-mcp
Tools
The server only lists the tools your key's permissions allow, so a read-only key never sees start_test_run.
| Tool | Permission | What it does | Arguments |
|---|---|---|---|
list_projects |
projects:read |
Lists the projects the key can access, to find the project ID the other tools need. | none |
start_test_run |
tests:run |
Starts a test run and returns the run ID. Pass changedAreas to re-test only the pages or flows you just changed; leave it out for the whole suite. Runs take minutes. |
projectId, changedAreas (e.g. ["/checkout", "/cart"]; optional) |
get_test_run |
tests:read |
Shows a run's status (pending, running, completed, failed), progress, current step and issue counts by severity. |
testRunId |
stop_test_run |
tests:run |
Stops a running test run, so no further test cases are executed and billed. A stopped run reports as failed. |
testRunId |
list_issues |
issues:read |
Lists a project's issues as summaries: ID, title, severity, category, status. Pass testRunId for only what one run found. |
projectId, severity (critical, high, medium or low; optional), testRunId (optional), limit (1-100, default 20) |
get_issue |
issues:read |
Gets one issue in full: description, steps to reproduce, expected and actual behaviour, page URL and screenshot. | issueId |
start_exploration |
knowledge:explore |
Explores the project's app so TestOptim learns new or changed pages and flows. Spends the plan's page allowance and replaces an exploration already running. Returns an exploration ID. | projectId |
get_exploration |
projects:read |
Shows an exploration's status, progress and, once it ends, how many pages, flows and entities it recorded. waiting_otp_ready or waiting_otp means the login needs a one-time code entered in the TestOptim app. |
explorationId |
Results come back as JSON text, using the same field names as the TestOptim API.
Example prompts
- "Which TestOptim projects can I access?"
- "Run the QA suite on the checkout project and tell me when it's done."
- "List the critical and high issues on my project, then show the steps to reproduce the first one."
- "I just changed the signup form. Run the tests, and if anything fails, open the issue and fix the code."
- "I changed /checkout. Re-test only that with TestOptim and fix any critical issues."
- "I added a settings page. Explore the app again so TestOptim picks it up."
- "Stop the test run you started; it's on the wrong project."
Security
- Least privilege. Create a separate key per client and per machine, limited to one project and to the permissions it needs. A key without
tests:runcan't start or stop runs. - Project-scoped keys are refused for any other project, and tools never show another organization's data.
- Keep keys out of files you commit. Use the environment-variable or input-prompt forms above. Keys start with
topt_, so they are easy to search for in logs and repositories. - Revoke a key under Settings > API keys if it leaks or a device is lost. It stops working immediately.
- An assistant connected with
tests:runcan start runs that use your plan's test executions. Most clients ask before calling a tool; keep that confirmation on.
Limits and errors
- 120 requests per minute per client IP address, shared with the TestOptim REST API.
- A project runs one job at a time. Starting a run while another job is in progress on the same project is refused; wait for it to finish and try again.
- Like Run all in the app, a run is trimmed to your remaining test executions. Check
totalCaseson the run if you need the full suite.
Troubleshooting
| Symptom | Cause |
|---|---|
401 Missing API token |
The Authorization header didn't arrive. Check the environment variable is set in the shell that starts your client, then restart the client. |
401 Invalid API token |
The key is wrong, revoked or expired. Create a new one. |
| A tool you expect is missing | The key lacks that tool's permission. Create a key with it. |
This token is restricted to a different project |
The key is scoped to one project; use that project's ID or a key for all projects. |
405 Method not allowed |
Something sent a GET or DELETE. The server only accepts POST; use a client with Streamable HTTP support. |
Contributing
Spotted an outdated client config, or want to add one for another client? See CONTRIBUTING.md. For problems with your account or the TestOptim service itself, contact TestOptim support instead.
License
MIT. TestOptim is at https://testoptim.com.
TestOptim MCP questions
How do I add TestOptim MCP to Claude Code?
Run claude mcp add --transport http testoptim-mcp https://api.testoptim.com/api/mcp in your terminal. Add --scope user to make it available in every project.
How do I add TestOptim MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does TestOptim MCP provide?
It exposes 8 tools, including list_projects, start_test_run, get_test_run, stop_test_run, list_issues.
How do I authenticate with TestOptim?
You use a TestOptim API key sent as a Bearer token in the Authorization header.
Can I run tests on specific parts of my application?
Yes, you can pass changedAreas to the start_test_run tool to re-test only specific pages or flows.
What information is included in a bug report?
The tool provides a full description, steps to reproduce, expected and actual behavior, the page URL, and a screenshot.
Does the server require installation?
No, TestOptim hosts the server, so there is nothing for the user to install or run locally.