> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tester.army/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Claude, Cursor, or any MCP client to the hosted TesterArmy MCP server over OAuth to create tests, start runs, and debug failures from your editor.

The TesterArmy MCP server gives any Model Context Protocol client - Claude,
Cursor, Codex, VS Code, Windsurf - 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
```

<Note>
  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 and the CLI both
  call the public API. The CLI covers a subset of the MCP tools: group schedules, issues, and run
  recordings are MCP-only.
</Note>

## Setup

The CLI's former `ta mcp` local server is no longer available. Replace any old
stdio entry with the hosted server configuration below. To run a saved test
from the terminal, use `ta tests run <testId> --wait` for cloud execution.

### One command for every client

```bash theme={"theme":"vesper"}
npx add-mcp --global --name testerarmy https://tester.army/mcp
```

[add-mcp](https://add-mcp.com) is Neon's open installer for MCP servers. It
finds the coding agents on your machine (Cursor, VS Code, Windsurf, Claude
Code, Codex and more), asks which of them to connect with the detected ones
preselected, and writes the server into each one's own config file. `--global`
targets the user-wide configs; drop it to set up the current repository only,
which puts the entry in files like `.cursor/mcp.json` that you can commit for
your team. Add `--yes` to skip the question, or `--agent <id>` (repeatable:
`cursor`, `vscode`, `windsurf`, `claude-code`, `codex`, ...) to name clients.
It needs no TesterArmy API key and never writes one into a client; each client
signs in through the browser on first use. Two limits to know: add-mcp writes
Claude Code's entry to `~/.claude.json` and does not follow `CLAUDE_CONFIG_DIR`,
so with a custom config directory use the Claude Code command below instead;
and clients it does not know take the server URL from the sections below.

### 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 theme={"theme":"vesper"}
{
  "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 theme={"theme":"vesper"}
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 theme={"theme":"vesper"}
{
  "mcpServers": {
    "testerarmy": {
      "url": "https://tester.army/mcp"
    }
  }
}
```

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

### Windsurf

Add the server to `~/.codeium/windsurf/mcp_config.json`. Windsurf uses
`serverUrl` for remote servers:

```json theme={"theme":"vesper"}
{
  "mcpServers": {
    "testerarmy": {
      "serverUrl": "https://tester.army/mcp"
    }
  }
}
```

### Codex

```bash theme={"theme":"vesper"}
codex mcp add testerarmy --url https://tester.army/mcp
```

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

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

Then run `codex mcp login testerarmy`.

### VS Code

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

```json theme={"theme":"vesper"}
{
  "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 theme={"theme":"vesper"}
{
  "mcpServers": {
    "testerarmy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://tester.army/mcp"]
    }
  }
}
```

## What your agent can do

<CardGroup cols={2}>
  <Card title="Projects and setup" icon="folder-gear" iconType="duotone">
    Create projects, manage static environments, store login credentials and inbox accounts, upload
    and manage mobile app builds, and save project memories.
  </Card>

  <Card title="Tests and groups" icon="list-check" iconType="duotone">
    Create, update, and delete saved tests; organize them into groups and set a preparation test.
  </Card>

  <Card title="Runs and schedules" icon="play" iconType="duotone">
    Queue runs for a single test or a whole group, target a saved environment, poll status, cancel
    work in flight, and put a group on a recurring schedule with a preset or a cron expression.
  </Card>

  <Card title="Failure analysis" icon="bug-slash" iconType="duotone">
    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.
  </Card>
</CardGroup>

The server also ships built-in best-practice guides the agent can fetch with the
`get_guide` tool - how to write reliable test steps, size tests so runs finish
with a verdict, organize tests into groups, target environments, debug failed
runs, and set up a project - so it follows TesterArmy conventions without you
having to explain them.

When a tool errors unexpectedly, returns wrong or confusing data, a guide
misleads it, or a capability is missing, the agent can report it to the
TesterArmy team with the `submit_feedback` tool: a summary plus what it was
trying to do, what it expected, what happened, and the tool involved. Feedback
reaches our team only; it never lands in your project.

## 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.
```

**Put tests on a schedule**

```
Run the "Production smoke" group every 30 minutes in the Europe/Warsaw
timezone, and tell me what it is currently set to first.
```

A schedule belongs to a group, so the agent reads the group's current schedule,
then replaces it with a `*/30 * * * *` cron. To schedule a single test, ask the
agent to create a group for it first. See [Production
Monitoring](/run/production-monitoring) for how scheduled runs report failures.

**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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Telemetry comes back empty or not found">
    Telemetry becomes available once the run finishes. Web runs capture browser console and network
    activity. Mobile runs capture the app's logs only, and only when the run installs an uploaded
    app, so Safari runs on iOS have no telemetry - use the transcript instead.
  </Accordion>

  <Accordion title="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 [public API](/api-reference), or the [CLI](/cli) for the subset of tools it
    covers.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="CLI" icon="terminal" iconType="duotone" href="/cli">
    Drive TesterArmy from a terminal, with or without an agent.
  </Card>

  <Card title="API Reference" icon="code" iconType="duotone" href="/api-reference">
    The same failure-analysis data over plain HTTP.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.