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

# MCP

> Use Twin Runs and browser tests from a coding agent

Arga's MCP server lets supported coding agents provision twins, inspect twin environments, start browser tests, and run Saved Tests.

## Prerequisites

```bash theme={null}
uv tool install arga-cli
arga login
arga whoami
```

## Install

```bash theme={null}
arga mcp install
```

The installer adds an `arga-context` server entry to supported local clients:

* `~/.cursor/mcp.json`
* `~/.claude/mcp.json`
* `~/.config/codex/mcp.json`

It preserves existing `mcpServers` entries and uses the device credential stored by `arga login`.

The installed server points to `<api-url>/mcp` with a bearer authorization header:

```json theme={null}
{
  "mcpServers": {
    "arga-context": {
      "url": "https://api.argalabs.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

## Custom API URL

```bash theme={null}
arga mcp install --api-url http://localhost:8000
```

You can also set `ARGA_API_URL` before running the installer.

## Twin tools

<AccordionGroup>
  <Accordion title="get_twin_catalog">
    Lists available twin names, labels, surface kinds, and twin-hosted MCP paths where available.
  </Accordion>

  <Accordion title="create_twin_run">
    Provisions and optionally seeds one or more twins.

    | Parameter                  | Required | Description                                                                                                                                                          |
    | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `twins`                    | Yes      | Comma-separated twin names.                                                                                                                                          |
    | `scenario_id`              | No       | Saved Scenario used for seed state.                                                                                                                                  |
    | `scenario_prompt`          | No       | Natural-language seed description. Ignored when `scenario_id` is provided.                                                                                           |
    | `scenario_generation_mode` | No       | `"fast"` (default) for everyday scenarios, or `"thorough"` for complex requirements with a longer wait. Only affects `scenario_prompt` when `scenario_id` is absent. |
    | `ttl_minutes`              | No       | Session TTL. Defaults to `60` and is limited by your plan.                                                                                                           |
    | `public`                   | No       | Whether returned base URLs are public. Defaults to `true`.                                                                                                           |

    The result contains the Twin Run ID. Poll `get_twin_run` until the status is `ready` or `failed`.
  </Accordion>

  <Accordion title="get_twin_run">
    Returns status, per-twin URLs, environment variables, access details, and seed results for a Twin Run.
  </Accordion>

  <Accordion title="reset_twins">
    Restores a ready short-lived Twin Run to the baseline captured at provisioning time.
  </Accordion>

  <Accordion title="extend_twins">
    Extends a Twin Run within the TTL allowed by your plan.
  </Accordion>

  <Accordion title="teardown_twins">
    Ends a short-lived Twin Run immediately.
  </Accordion>
</AccordionGroup>

### Choose a generation mode

For a prompt with complex requirements, an agent can call `create_twin_run` with:

```json theme={null}
{
  "twins": "slack",
  "scenario_prompt": "A support channel with linked escalation threads and consistent message authors",
  "scenario_generation_mode": "thorough"
}
```

The tool schema advertises both supported values and the Fast default. Poll `get_twin_run` until the run is ready or failed. A saved `scenario_id` reuses existing seed data; changing the mode does not regenerate it. To save a reusable scenario, use [the REST API](/api-reference/post-create-a-scenario) or [the CLI](/cli-and-mcp#choose-a-generation-mode).

## Persistent Scenario environment tools

<AccordionGroup>
  <Accordion title="ensure_scenario_twin_environment">
    Creates or returns the persistent twin environment attached to a saved Scenario. Pass `scenario_id`, optional comma-separated `twins`, and optional `public` access.
  </Accordion>

  <Accordion title="get_scenario_twin_environment">
    Returns the status and stable twin URLs for one Scenario.
  </Accordion>

  <Accordion title="reseed_scenario_twin_environment">
    Restores a ready persistent environment from its saved Scenario.
  </Accordion>

  <Accordion title="delete_scenario_twin_environment">
    Tears down the persistent environment attached to one Scenario.
  </Accordion>

  <Accordion title="list_scenario_twin_environments">
    Lists persistent Scenario environments owned by the authenticated account.
  </Accordion>
</AccordionGroup>

## Browser test tools

<AccordionGroup>
  <Accordion title="create_test_run">
    Starts an ad hoc browser Test Run.

    | Parameter          | Required | Description                                                          |
    | ------------------ | -------- | -------------------------------------------------------------------- |
    | `prompt`           | Yes      | Natural-language browser task.                                       |
    | `start_url`        | Usually  | Reachable application URL. It may instead be included in the prompt. |
    | `test_config_json` | No       | Existing TestConfig JSON for deterministic execution.                |
    | `repo`             | No       | Repository metadata in `owner/repo` format.                          |
    | `branch`           | No       | Branch metadata.                                                     |
    | `pr_url`           | No       | Pull-request metadata.                                               |

    Point the application at any required twin endpoints before starting the Test Run.
  </Accordion>

  <Accordion title="run_test">
    Runs a Saved Test by `test_id`. Pass `start_url` to override the URL stored with the test and `prompt` to add run-specific guidance.
  </Accordion>

  <Accordion title="get_test_run">
    Returns status, events, artifacts, editable TestConfig, and summary fields for a Test Run.
  </Accordion>

  <Accordion title="list_tests">
    Lists Saved Tests. Pass `repo_full_name` to filter them to one repository.
  </Accordion>
</AccordionGroup>

## Compatibility tools

Older servers may also expose `start_url_validation`, `get_validation_results`, `cancel_validation_run`, `provision_twins`, `get_twin_provision_status`, and `cancel_run`. Prefer the Twin Run and Test Run tools above for new agent workflows.

Your MCP client's `tools/list` response is the authoritative list for the server version you are connected to.