Authentication

Browser login with tb_login (loopback)

The simplest way to authenticate on a desktop is the tb_login tool. It uses a loopback authorization flow (RFC 8252): the server opens your default browser to TestingBot, you click Authorize while signed in, and the credentials are captured on a local 127.0.0.1 callback. Nothing is ever copied, pasted or shown to your AI client.

How it works, step by step

1. Ask your AI client to authenticate, for example:

"Log in to TestingBot"

2. Your client invokes the tb_login tool.
3. The server opens your default browser to TestingBot and starts a temporary local callback listener.
4. If you are not signed in yet, log in to your TestingBot account, then click Authorize.
5. The browser redirects back to the local 127.0.0.1 callback and the credentials are captured.
6. The server writes them to ~/.testingbot/credentials and starts using them immediately, no restart needed.

After this, all other tools (such as getUserInfo, getTests or tb_openBrowser) work automatically because the server reads the credentials file.

Device-code flow

When there is no local browser (SSH sessions, remote or headless hosts, containers, or web-based MCP clients), use the device-code flow (RFC 8628). Instead of opening a browser locally, the server prints a short code that you enter on any device with a browser.

How it works, step by step

1. Run tb_login with the device mode, for example:

"Log in to TestingBot using the device code flow"

2. The server prints a short, human-readable code.
3. On any device, open https://testingbot.com/device.
4. Enter the code, sign in if needed, and click Authorize.
5. The server detects the approval, writes the credentials to ~/.testingbot/credentials and starts using them.

The mode parameter

tb_login takes a single optional mode parameter that chooses the authorization flow. You can also set a default with the TESTINGBOT_AUTH_MODE environment variable.

For example, to force the device flow regardless of environment, ask your client to run tb_login with mode set to device, or set TESTINGBOT_AUTH_MODE=device in your client's env block.

API key & secret

As an alternative to tb_login, you can supply your TestingBot API key and secret directly. This is the preferred option for CI pipelines and shared configurations where there is no interactive browser. Add them to your MCP client's env block:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"],
      "env": { "TESTINGBOT_KEY": "<key>", "TESTINGBOT_SECRET": "<secret>" }
    }
  }
}

You can find your key and secret on your TestingBot account page. Both must be set for the environment-variable path to take effect.

Where credentials live

When you authenticate with tb_login, the server stores your credentials in an INI file at ~/.testingbot/credentials. The file is organized into profile sections so you can keep more than one account on the same machine:

[default]
key = your-api-key
secret = your-api-secret

By default the server reads the [default] profile. To use a different profile, set TESTINGBOT_PROFILE; to relocate the whole directory, set TESTINGBOT_CONFIG_DIR.

File permissions

The credentials are written with restrictive permissions so other users on the machine cannot read them:

• The directory ~/.testingbot is created with mode 0700 (owner only).
• The credentials file is written with mode 0600 (owner read/write only).

Environment variables

The following environment variables can be set in your MCP client's env block (or your shell) to control authentication and connection behavior. Several have aliases for compatibility with existing TestingBot tooling.

Degraded mode

If the server cannot find credentials (neither a key/secret pair in the environment nor a credentials file), it starts in degraded mode. In this state every tool except tb_login returns a message like:

No TestingBot credentials configured. Run the tb_login tool to authenticate.

This is not an error in your client configuration, it simply means you have not authenticated yet. To fix it:

• Run the tb_login tool (ask your client to "log in to TestingBot"), or
• Set TESTINGBOT_KEY and TESTINGBOT_SECRET in your client's env block and reload the server.

Security notes

The TestingBot MCP server is designed so your credentials stay under your control and never leak into your AI conversation.

• Credentials stay local. Whether captured by tb_login or read from environment variables, they live on your machine (in ~/.testingbot/credentials or the process environment) and are never sent to your LLM provider.
• Direct API calls. The MCP server talks directly to the TestingBot API. Your AI client sends natural-language requests to the local server; the server performs the work and returns results.
• No key pasting. The browser and device-code flows capture credentials out of band, so your key and secret never pass through the chat transcript.
• Restrictive permissions. The credentials file is written 0600 inside a 0700 directory, readable only by your user account.