# mabl MCP bridge

Dino exposes the official [mabl MCP server](https://help.mabl.com/hc/en-us/articles/47299375773844-mabl-MCP-overview) as pi.dev tools. The extension handles OAuth authentication automatically on first use.

## When to use

Use the mabl MCP tools when the user asks about:

- mabl workspaces, applications, environments, plans, or tests
- Running mabl tests or plans locally or in the mabl cloud
- Latest test runs, plan runs, deployment events, or diagnostics
- Creating new mabl tests from a description, a plan, or AI-assisted cloud generation
- Exporting mabl tests to Playwright
- Switching the active workspace or inspecting workspace credentials

## Authentication

The `mabl-mcp` extension does not run the OAuth check automatically on startup. To load the mabl MCP tools, run the command inside pi:

```
/mabl-auth
```

The command checks for an active mabl CLI session. If none exists, it runs `mabl auth login --auto` and streams the OAuth prompt to the terminal. The user must approve the login in a browser. After the one-time OAuth flow, the mabl CLI stores the token locally and subsequent `/mabl-auth` calls skip the prompt.

If OAuth cannot complete inside pi (for example, no browser is available), authenticate outside of pi:

```bash
npx @mablhq/mabl-cli auth login --auto
```

Then start pi and run `/mabl-auth` to load the mabl MCP tools.

If a tool later returns "The CLI is not authenticated," run `/mabl-auth` again to refresh the session.

## Tool categories

### Workspace and metadata

- `get_workspaces` — list accessible mabl workspaces
- `switch_workspace` — set the active workspace for subsequent calls
- `get_applications` — list applications in the workspace
- `get_environments` — list environments in the workspace
- `get_credentials` — list workspace credentials

### Tests and plans

- `get_mabl_tests` — list tests with optional filters
- `get_mabl_test_details` — retrieve details for a specific test
- `get_plans` — list plans
- `create_mabl_test` / `create_mabl_test_cloud` / `create_mabl_test_from_plan` — create tests
- `plan_new_test` — plan a new test before creating it

### Runs and results

- `run_mabl_test_local` / `run_mabl_test_cloud` — execute a test
- `get_latest_test_runs` — recent test runs
- `get_latest_plan_runs` — recent plan runs
- `get_plan_run_result` — detailed result of a plan run
- `get_mabl_deployment` — deployment/event information
- `analyze_failure` — diagnose a failed run

### Integrations

- `get_xray_test_cases` / `assign_xray_to_mabl_test` — Jira Xray integration
- `export_to_playwright` — convert a mabl test to Playwright code

### Utility

- `get_cloud_test_gen_status` — poll AI cloud test generation status
- `get_latest_authored_tests` — recently authored tests

## Best practices

1. **Start with workspace context.** Use `get_workspaces` and `switch_workspace` if the user has not specified a workspace.
2. **Prefer listing before running.** Ask the user or use `get_mabl_tests` / `get_plans` to resolve IDs before executing runs.
3. **Handle auth errors.** If a tool returns "The CLI is not authenticated," run `/mabl-auth` to refresh the session, or run `npx @mablhq/mabl-cli auth login --auto` outside of pi and then `/mabl-auth` inside pi.
4. **Cloud generation takes time.** When using `create_mabl_test_cloud`, poll `get_cloud_test_gen_status` until completion.
5. **Combine with Playwright skills.** Use `export_to_playwright` to generate a Playwright spec, then refine it with the `playwright-core` and `playwright-pom` skills.