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

# MCP reference

> Every tool the Katla MCP server exposes, the permission model, and self-hosting configuration.

This page documents what the Katla MCP server can do. To connect it to your assistant, start
with [Connect an AI assistant](/mcp).

## Endpoint

```
https://api.katla.app/mcp
```

Streamable HTTP, authenticated with OAuth 2.1 (PKCE, dynamic client registration). Sign-in is
delegated to the same identity provider the dashboard uses.

## Tools

### Teams and plan

| Tool               | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `katla_list_teams` | List the teams you belong to                                |
| `katla_get_plan`   | Current plan, subscription status, and usage against limits |

### Sites

| Tool                         | Description                                                   |
| ---------------------------- | ------------------------------------------------------------- |
| `katla_list_sites`           | All domains in a team with their latest scan status           |
| `katla_get_site`             | Full details for one site                                     |
| `katla_add_site`             | Add a domain, ready to scan                                   |
| `katla_scan_site`            | Start a cookie scan                                           |
| `katla_get_scan_status`      | Scan progress and history                                     |
| `katla_get_install_snippet`  | Widget script tag and CDN resource URLs                       |
| `katla_update_site_settings` | Regulation mode, privacy policy URL, Consent Mode, appearance |

### Cookies and consents

| Tool                              | Description                                                    |
| --------------------------------- | -------------------------------------------------------------- |
| `katla_list_cookies`              | Every cookie found by the latest scan, with categories         |
| `katla_update_cookie_category`    | Reclassify a cookie; the override survives rescans             |
| `katla_list_cookie_descriptions`  | Custom cookie descriptions written for this site, per language |
| `katla_set_cookie_description`    | Replace a cookie's description for one language                |
| `katla_remove_cookie_description` | Revert one language to the automatic description               |
| `katla_get_consent_stats`         | Aggregate accept/partial/reject counts and per-category rates  |
| `katla_list_consents`             | Individual consent records                                     |
| `katla_generate_privacy_policy`   | Save company details and return policy embed URLs              |

Sites can be referenced by domain (`example.com`) or by site ID — the assistant resolves
either. If you belong to more than one team, it asks which team to use.

## Asynchronous operations

Scanning is a queued job, not an immediate result. After starting one, the assistant polls
`katla_get_scan_status` rather than assuming it finished. Scans count against your plan quota.

## Custom cookie descriptions

Katla writes and translates a description for every cookie it recognises. When you want your
own wording instead, `katla_set_cookie_description` replaces it for one language at a time:

> "On example.com, describe the `_ga` cookie in German as 'Unterscheidet Besucher in unserer
> Analyse' and in Swedish as 'Skiljer besökare åt i vår analys'."

Your text is used by the consent banner, the cookie policy and the exports wherever that
language is served. Languages you have not written keep the automatic description, so a
German page never falls back to English wording. It also works for cookies Katla does not
recognise, which otherwise have no description at all.

The same overrides can be managed in the dashboard and with
[`katla cookies describe`](/cli-cookies-and-consents#write-your-own-cookie-description).

## Permissions and privacy

* **Scoped to your account.** The connector can only reach teams you are a member of, and
  role checks apply per action — a `member` cannot do what an `admin` can.
* **Read and write scopes.** Connections are granted `katla:read` and `katla:write` by
  default. A client that requests only `katla:read` gets a read-only connection, and every
  mutating tool refuses.
* **No billing changes.** Plan and payment changes are deliberately not exposed. `katla_get_plan`
  is read-only; change plans in the [dashboard](https://katla.app).
* **No destructive operations.** Removing a domain is not exposed over MCP.
* **No visitor PII.** Consent records returned over MCP include the consent decision,
  categories, and timestamp — never IP addresses or user agents.
* **Revocable.** Remove the connector in your assistant to stop it being used, or sign out
  of Katla everywhere to invalidate the underlying session.

## Self-hosted or staging

If you run Katla against your own API, point the connector at that origin instead:

```
https://your-api-host/mcp
```

Set `API_PUBLIC_URL` on the API to the public origin clients will reach. It is used as the
OAuth issuer and as the MCP resource identifier, so it must match the URL you connect to
exactly — otherwise discovery fails.

To check discovery is working, `https://<your-api>/.well-known/oauth-protected-resource/mcp`
should return JSON whose `resource` field matches the URL you entered.