SDK, CLI, and MCP

The web app, the CLI, the test reporters and the MCP server all use the same backend API. But each one offers different actions and signs in differently. Check a client’s own help and the API reference before you assume it can do everything another one can.

Language-specific support

TestLookup provides reporter libraries (SDKs) that send your test results:

Python: sends results in batches or live, and includes a Robot Framework listener.
JavaScript: adds live reporters for Playwright Test, Vitest, Cypress and Cucumber JS to the Jest and Mocha reporters.
Java and Go: each provides its own hooks for test frameworks.

No client is published to a package registry yet. Install each one from a clone of the repository. For the Go module, use a replace directive.

A running TestLookup server also serves the CLI as a wheel file. GET /api/v1/sdk/cli/info names the file, and you install it like this:

pip install http://<your-server>/api/v1/sdk/cli/<wheel-file>

A report format that the server can read is not necessarily one that every client can produce. No client offers every action of the web app.

Install the CLI

The CLI is the testlookup command-line tool, version 0.4.0. From the root of a clone, with Python 3.11 or newer, install it from source:

python -m pip install -e ./cli
testlookup --help

For the current options, run the help of the command group you need, such as auth, upload, release, projects or ci-verdict. The CLI has 21 command groups and three top-level commands: ci-verdict, ai-history and compare-ai.

Gate a release from CI

testlookup release gate <release> prints the release’s stored decision and ends with an exit code that a CI job can act on. By default the codes mean:

Exit code	Meaning
0	GO, or Conditional GO
1	NO-GO
3	No decision to act on: the release was not evaluated, was never evaluated, or has a decision the CLI does not recognise
2	An infrastructure problem, such as the network, a server error, sign-in, permission, or an unknown release name

A whole release is GO, NO-GO or Not evaluated at this version. So the Conditional GO rules apply only if a later version records that decision for a release.

These options change the behaviour:

--fail-on CONDITIONAL_GO: makes Conditional GO exit 1.
--fail-open: turns exit 2 into exit 0, so the build passes when TestLookup cannot answer.
--evaluate: records a fresh decision first. It needs a QA lead or a project API key.

To check a downloaded compliance pack without a network connection, run compliance-pack verify with --public-key and --manifest-sha256.

Project export and import

A QA lead or administrator can export a project. The export is a signed ZIP file with the project’s settings and test catalog:

testlookup projects export <project>

--history adds the history of finished runs.
--days 30|90|365|all chooses how far back the history goes. The default is 90 days.
--max-runs N limits the number of runs, newest first, up to 2,000.
With --history, the command waits up to 3 hours by default, instead of 10 minutes.

An administrator can import the file. An import always creates a new project:

testlookup projects import FILE [--name NAME] [--new-copy]

A file over 50 MB, up to 2 GB, is sent in 32 MB parts. If the import is interrupted, running it again sends only the missing parts. Running a finished import again prints Already imported as <name> instead of creating a second project, unless you add --new-copy.

Profiles

A CLI profile holds an API address, a choice of credential and a project. The CLI saves profiles in profiles.json, in your own settings folder. On Linux and macOS, only you can read that file.

A command picks its profile in this order:

--profile, when you give it;
the TESTLOOKUP_PROFILE environment variable;
the saved active profile;
the profile named default.

If no saved profile has that name, the CLI uses TESTLOOKUP_URL (default http://localhost:8000) and TESTLOOKUP_API_KEY, which it sends as X-API-Key. Keep profile files out of your repository, choose the project yourself, and never copy credentials into public examples.

Most routes accept either a sign-in token (JWT) in an Authorization: Bearer header, or an API key in the X-API-Key header. TestLookup refuses an API key sent as a bearer token.

These still apply: your project membership, your role, the key’s project and the actions the key allows. A key limited to certain actions can do only those actions. A key with no limits can do everything its owner’s role allows. A few actions, such as changing the review-gate date, need a person signed in to the web app. The MCP server accepts sign-in tokens only.

MCP over stdio and SSE

The MCP server lets AI assistants such as Claude or Cursor use TestLookup. It can run in two ways:

Over local stdio, it uses the credentials in its own settings.
Over SSE, it passes each caller’s own sign-in token to the REST API, and checks that token on every request.

It accepts sign-in tokens (JWTs) only, not API keys. It has 80 tools, 11 resources and 7 prompts. It lists pending reviews, but it never offers to accept or reject a report.

Live-session SSE, agent-run SSE and the WebSocket each sign in differently; see live protocols. Tickets for agent-run streams are short-lived and work only once, so every reconnect needs a new one.

Connect an AI assistant over MCP

From a clone of the repository, install the server’s libraries:
Terminal window
```
pip install -r mcp/requirements.txt
```
Create a separate TestLookup user for each AI assistant, with only the role its job needs. The server has no rights of its own. The backend checks the role and project membership on every call, and records every change under that user.
For Claude Code, Claude Desktop or Cursor, set the assistant to start python mcp/server.py over stdio. Put TESTLOOKUP_API_URL, TESTLOOKUP_USERNAME and TESTLOOKUP_PASSWORD in its MCP settings. That settings file then holds the assistant user’s password.
For an assistant on the network or in CI, connect to the SSE address instead: /sse, on port 8002 by default. The assistant sends its own bearer access token on both /sse and /messages/.

The agent cookbook on GitHub has the settings blocks and seven recipes, from triaging the latest run to fixing a flaky test.

Invoking agents

You can start an AI agent run with POST /api/v1/agents/{agent_id}/invoke, or with the MCP tool invoke_agent. The request accepts an Idempotency-Key header. A retry with the same key and the same request returns the existing agent run instead of starting a new one. Reusing a key for a different request gets HTTP 422.

The summary agent, agent.summary.v1, can also take pasted failures in inline_input:

1 to 10 failures, and at most 262,144 bytes;
tied to a stored run of the project;
cleaned of sensitive values before TestLookup stores them.

Its output is a draft that is reviewed as part of the agent run. It stays out of the run’s report, release checks and notifications, and it sends nothing.

Retry and errors

When TestLookup is busy or limiting your requests, wait for the time in the Retry-After header. When a client retries, send the same source details, such as the build and the CI run URL. Do not repeat a change because a response was lost, unless that endpoint says that sending it twice is safe.

When something fails, find out which step failed: accepting the request, storing it, analysing it, reviewing it or delivering it.

Keeping versions compatible

Keep the clients, the API, the web app, the MCP server and the backend at versions that work together. The packages carry their own version numbers:

the repository’s VERSION file reads 0.1.0;
the CLI is 0.4.0;
the Python testlookup-reporter is 1.3.0;
the JavaScript and Java reporters are 1.0.0;
the Go module declares no version.

Check your server’s build with GET /health/version, and use the documentation for that build. Do not judge compatibility from a package name or an installed program alone.

Client reference

Client details

The web app uses the same API as the clients on this page.

The CLI reference documents every command. The MCP server README lists the server’s tools, resources and prompts. The MCP review tools let an AI assistant read reviews, but not accept or reject reports.

# From the root of a clone of the repository, with Python 3.11+
python -m pip install -e ./cli
testlookup --help
testlookup auth --help
testlookup upload --help
testlookup ci-verdict --help

For credential, profile and file options, read each command’s help instead of copying credentials into examples. Each language’s reporter supports different formats, so a report format that the server can read is not one that every reporter can produce.

Failure and retry guidance

The retry rules are under Retry and errors, above. When TestLookup accepts a proposed action, that does not mean the remote system accepted the call.

Delivery to another system can be late, or fail, after a successful upload. Check the delivery attempts, integration health, whether the workers and the scheduler are running, and policy refusals. Never treat text from an outside integration as instructions that override project policy.

Live and health routes

The live protocols page describes the live WebSocket and SSE routes, their credentials and their reconnect rules. These routes are not in the OpenAPI document.

To check a server before a client uses it, call its health routes. The /health/live route checks that the process is running, and /health/ready checks the services it cannot work without. The /health/version route reports which build is running. The /health/details route reports on each service it depends on, and it can answer 200 with the status degraded when some of them have problems. The /metrics route exists only when metrics are configured, and it is left out of the exported OpenAPI document. A healthy answer alone does not prove that the workers process jobs, that the AI model is installed correctly or that the database updates match the code.

Continue with the CI integration tutorial, using a project you can throw away afterwards.