# Claude Code

Source: https://webagent-docs-staging.lookover.ai/qa-testing/claude-code

> Add webagent to Claude Code as an MCP server, check the connection, and run your first smoke test.

> **Note: API address**
>
> Examples use the variable `$API_URL`. Set it once: `export API_URL=https://api.us.webagent.lookover.ai`. Webagent is in early access, so the address for your account can differ. The **API keys** page in the dashboard shows it as "API base", followed by `/v1`. Use the address without the `/v1`. Running the API on your own machine? Use `export API_URL=http://localhost:4400`.

You need an API key ([Quickstart](/quickstart)) and Claude Code. These steps were checked with Claude Code 2.1.

## 1. Set the address and the key [#1-set-the-address-and-the-key]

```bash
export API_URL=https://api.us.webagent.lookover.ai
export WEBAGENT_API_KEY=wa_us_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Add this line to your shell profile so it is set every time you start `claude`.

## 2. Add the server [#2-add-the-server]

```bash
claude mcp add --transport http lookover-webagent \
  "$API_URL/mcp" \
  --header 'Authorization: Bearer ${WEBAGENT_API_KEY}'
```

The shell fills in `$API_URL` when you run the command, so Claude Code saves the full address.

Use **single quotes** around the header. The shell then does not expand `${WEBAGENT_API_KEY}`. Claude Code saves the text `${WEBAGENT_API_KEY}` and reads your environment when it starts the server, so the key itself is never written to a config file. If the variable is not set when `claude` starts, `claude mcp list` warns `Missing environment variables: WEBAGENT_API_KEY` and the connection fails with `401`.

Things to know:

- **Do not name the server `webagent`.** Claude Code refuses it (`this name is reserved`). Any other name works. This page uses `lookover-webagent`.
- `--transport http` is the streamable HTTP transport. The webagent endpoint is `POST /mcp` and does not use SSE.
- The default scope is **local**: the server is available in the current project only and is not shared. Add `--scope user` to use it in every project. Use `--scope project` to write it to `.mcp.json` so your team shares the same line. The key is not in that file, only `${WEBAGENT_API_KEY}`, so each person uses their own key.
- Webagent also accepts the key in an `x-api-key` header, if you cannot send `Authorization`.

## 3. Check the connection [#3-check-the-connection]

```bash
claude mcp list
```

You want a line like this, ending in `Connected`:

```text
lookover-webagent: https://api.us.webagent.lookover.ai/mcp (HTTP) - ✔ Connected
```

Inside Claude Code, type `/mcp` to see the server, its status and its tool count.

The server should offer the 15 fixed tools (`create_session`, `run_task`, `get_task`, `smoke_test`, `get_report`, `list_sessions`, `get_session`, `stop_session`, `scrape`, `screenshot`, `pdf`, `crawl`, `list_skills`, `run_skill`, `get_skill_run`), plus one `skill_<name>` tool for each skill your workspace can run, such as `skill_smoke_uat`. Skills appear only if they are installed in your environment. If you see only 15 tools and no `skill_` tools, see [Skills](/concepts/skills).

If it fails to connect:

| What you see | What it means |
|---|---|
| `✘ Failed to connect — Server rejected the configured Authorization header (HTTP 401)` with `invalid API key` | The key is wrong, revoked, or `WEBAGENT_API_KEY` was not set when you started `claude`. |
| `421` or `wrong_region` | The key belongs to another region. Use the API address for that region. |
| `405` on a browser or GET request | Expected. The endpoint answers `POST` only. |
| Not found, DNS error | The API address is wrong. Copy it from the dashboard. |

## 4. Let Claude call the tools [#4-let-claude-call-the-tools]

By default, Claude Code asks before each tool call. To approve every webagent tool without a prompt, add an allow rule to `.claude/settings.json`:

```json title=".claude/settings.json"
{
  "permissions": {
    "allow": ["mcp__lookover-webagent__*"]
  }
}
```

Only do this for a project where you are happy for the agent to open any public URL you name in your prompt.

## 5. Run a first smoke test [#5-run-a-first-smoke-test]

First install the [agent setup snippet](/qa-testing/agent-setup) in your `CLAUDE.md`. Then try the Test Arena, a fake site meant for this:

```text
Use the webagent tools. Smoke test https://webagent-test-web.pages.dev/app/login:
sign in with the email qa@example.com and the password arena-pass. After signing in,
the text "Welcome" must be on the page. Give me the verdict, the failed steps, the
console errors and the report link.
```

Claude calls `smoke_test` once. It turns the sign-in into steps and "Welcome" into `expectText`. The tool opens a recorded browser, runs the steps and the checks, and waits up to 60 seconds. You can watch it in the dashboard under **Sessions** while it runs.

Say what must be on the page after the steps ("the text ... must be on the page"). If you only ask Claude to "check that the page shows" something, it can add that as a last step instead of an expectation. A step that runs while the page is still loading can then stop with `low_confidence` and fail the test, although the app is fine.

Claude Code 2.1.322 gives the model the whole report (`structuredContent`) as the tool result. Its `summary` field has the same sentences as the tool's text:

```text
Smoke test of https://webagent-test-web.pages.dev/app/login PASSED in 1 s: 13 of 15 steps passed. No console errors or failed network calls.
```

The report has a `verdict` (`pass`, `fail` or `error`), the steps, console errors, failed network calls and links to the proof. If the test is not done after the wait, the verdict is `running` and Claude calls `get_report` with the `id` until it ends. That is normal, not an error. A test that ran and failed is a normal result: `isError` is set only when the test could not run. See [Reading results](/qa-testing/reading-results).

For an open-ended goal, where the agent decides what to do, ask for a task instead. Claude then calls `run_task`:

```text
Use the webagent run_task tool on https://webagent-test-web.pages.dev/: open the
Pricing page and tell me its heading.
```

A task has no assertions: `ok` means the agent says it is done. Claude can call `get_report` with the task id for a report with the console errors and failed network calls.

[Recipes](/qa-testing/recipes) has more prompts. [Reading results](/qa-testing/reading-results) explains what each field means.

## Remove the server [#remove-the-server]

```bash
claude mcp remove lookover-webagent
```

If you added it with `--scope user` or `--scope project`, add the same `--scope` flag.