> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://tester.army/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tester.army/_mcp/server.

# MCP Server

The TesterArmy MCP server gives any Model Context Protocol client - Claude,
Cursor, Codex, VS Code - direct access to your projects, tests, and runs. Your
agent can create and run tests, then read the transcript and browser telemetry
of a failure and tell you what broke, without leaving your editor.

The server is hosted by us and follows the authenticated remote
[MCP spec](https://modelcontextprotocol.io/specification), using Streamable HTTP
as its transport. You sign in with your TesterArmy account through OAuth, so
there is no API key to create, paste, or rotate.

```
https://tester.army/mcp
```

Prefer the [CLI](/cli) when you want an agent to work in a terminal, or the [public
API](/api-reference) when you are writing your own integration. The MCP server exposes the same
capabilities to clients that speak MCP natively.

## Setup

### General

Point your client at `https://tester.army/mcp`. On first use the client
registers itself automatically and opens a browser for you to sign in - the
interactive flow uses OAuth 2.1 with dynamic client registration, so there is
nothing to configure ahead of time.

Most clients accept this configuration shape:

```json
{
  "mcpServers": {
    "testerarmy": {
      "url": "https://tester.army/mcp"
    }
  }
}
```

### Claude

In Claude Desktop or claude.ai, open **Settings → Connectors**, choose **Add
custom connector**, and enter `https://tester.army/mcp`. Claude opens a browser
window for you to sign in to TesterArmy and approve access.

### Claude Code

```bash
claude mcp add --transport http testerarmy https://tester.army/mcp
```

Then run `/mcp` inside a Claude Code session to complete the sign-in.

### Cursor

Add the server to `.cursor/mcp.json` in your project, or to the global
`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "testerarmy": {
      "url": "https://tester.army/mcp"
    }
  }
}
```

Cursor prompts you to authenticate the first time a tool is used.

### Codex

```bash
codex mcp add testerarmy --url https://tester.army/mcp
```

Or add it to `~/.codex/config.toml`:

```toml
[mcp_servers.testerarmy]
url = "https://tester.army/mcp"
```

Then run `codex mcp login testerarmy`.

### VS Code

Add `.vscode/mcp.json` to your workspace:

```json
{
  "servers": {
    "testerarmy": {
      "type": "http",
      "url": "https://tester.army/mcp"
    }
  }
}
```

### Clients without remote MCP support

Older clients that only speak stdio can bridge through
[`mcp-remote`](https://github.com/geelen/mcp-remote):

```json
{
  "mcpServers": {
    "testerarmy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://tester.army/mcp"]
    }
  }
}
```

## What your agent can do

#### Projects and setup

Create projects, manage static environments, store login credentials and inbox accounts, upload
and manage mobile app builds, and save project memories.

#### Tests and groups

Create, update, and delete saved tests; organize them into groups and set a preparation test.

#### Runs

Queue runs for a single test or a whole group, target a saved environment, poll status, and
cancel work in flight.

#### Failure analysis

Read the agent transcript, browser console logs, and network requests for any run to work out
why it failed, and get a download link for the run video.

## Common use cases

Once connected, ask in plain language. Useful starting prompts:

**Triage a failure**

```
The last run of my checkout test failed. Read the transcript and the browser
telemetry and tell me whether it's a bug in our app or a problem with the test.
```

The agent goes verdict → transcript → console and network logs, which is
usually enough to name the failing request or the step where the UI diverged.

**Get the run video**

```
Give me a download link for the video of that failed run.
```

The agent returns a signed link that expires in 15 minutes, so it can hand the
MP4 to you or attach it to an issue. The video is never pulled into the
conversation.

**Upload a new app build**

```
Upload build/app-release.apk to the Mobile project and delete it automatically
after a day.
```

The agent asks TesterArmy for a signed upload link, sends the file from disk
itself, and confirms the build, so the binary never enters the conversation.

**Run a regression suite and report back**

```
Run the "Checkout" group against the staging environment and summarize which
tests failed and why.
```

**Turn a bug report into a test**

```
Create a test in the Web project that signs up a new user with a temporary
email, verifies the welcome email arrives, and asserts the dashboard loads.
```

**Keep tests healthy**

```
List the runs that failed in the last day and tell me which failures share a
root cause.
```

**Give the agent product context**

```
Save a memory for this project: our login uses a magic link, so tests should
use an inbox credential rather than a password.
```

## Teams

TesterArmy accounts can belong to several teams, and an OAuth connection covers
all of them. If you are in a single team, everything targets it automatically.
If you are in more than one, tools ask which team to use and your agent will
call `list_teams` to resolve it - you can also say "use the Acme team" up front.

## Security

* **You only ever see your own data.** Every tool call is scoped to a team you
  are a member of, and each request is re-checked against your current
  membership. Losing access to a team immediately stops the tools reaching it.
* **Sign-in is handled by our identity provider.** The MCP server never sees
  your password, and the access token it receives is short-lived and refreshed
  automatically by your client.
* **Credentials stay secret.** Stored login passwords are never returned by any
  tool, and credential-bearing steps are redacted from transcripts.
* **Your agent can delete things.** Tools that delete projects, tests, or groups
  are marked destructive, and good clients ask you to confirm before running
  them. Treat an MCP connection with the same care as a signed-in browser
  session, and be deliberate about which client you connect.

## Troubleshooting

#### The client says it cannot connect, or reports 'No authorization provided'

This is the expected first response before you sign in - it means the client has not completed
the OAuth flow yet. Trigger the sign-in from your client (in Claude Code, run `/mcp`), complete
it in the browser, and retry. If the browser never opens, your client may not support dynamic
client registration; use the `mcp-remote` bridge above.

#### A tool says I belong to multiple teams

Your account is in more than one team, so the tool needs to know which one to use. Tell your
agent which team to work with, or ask it to list your teams first.

#### Telemetry comes back empty or not found

Console and network telemetry is captured for web runs only, and becomes available once the run
finishes. Mobile runs have no telemetry - use the transcript instead.

#### I want to use an API key instead

The MCP server authenticates with your TesterArmy account rather than an API key. For key-based
automation use the [CLI](/cli) or the [public API](/api-reference), which expose the same
functionality.

## Related

#### [CLI Reference](/cli)

Drive TesterArmy from a terminal, with or without an agent.

#### [API Reference](/api-reference)

The same failure-analysis data over plain HTTP.