# Connect an AI assistant to your site

Let Claude, ChatGPT, Cursor or Codex read your site’s security through BetterShield’s built-in MCP server, and choose what it may change.

The assistant connects to your site's own address, and runs as the account that connected it. Everything is under **BetterShield › Agents**, in four tabs: **Connect**, **Requests**, **Permissions** and **Surface**.

Each thing an assistant can do is an ability: in WordPress, a named action a plugin offers to AI assistants and other tools, such as reading the score. Each use of one is a call.

## Turn on access and connect

On the **Connect** tab, the **Three steps to a connected assistant** card has three switches, all off until you turn them on.

| Option | What it does | Why it matters | Default |
|---|---|---|---|
| **Let my agent read security information** | Step 1. Lets an assistant read what BetterShield's screens show. | Until it is on, nothing is offered to agents. Turning it off also turns step 2 off. | Off |
| **Let agents act: changes that can be undone right away, anything heavier once you agree** | Step 2, optional. Lets an assistant make changes. Needs step 1. | When off, an assistant reads and changes nothing. | Off |
| **Let an assistant connect to this site** | Step 3. Opens the connection. Needs step 1. | When off, the site answers no assistant, without ending any grant. | Off |
| **Allow this credential to change the site** | Whether the next credential may change the site or only read. Only while step 2 is on. | Issue a read-only credential whatever the switches say. | Ticked when step 2 is on |

### Connect an assistant

1. Turn on step 1, step 2 if you want changes, then step 3.
2. Click **Connect** and copy the **Connection credential**. It is shown once.
3. In **Set up your assistant**, pick your app and copy what it shows:
   - **Claude** or **ChatGPT**: add the **Address to paste**, then approve on the page that opens. Needs pretty permalinks (**Settings › Permalinks**).
   - **Claude Desktop** or **Cursor**: copy the **Configuration** block and replace `PASTE_YOUR_TOKEN_HERE` with your credential.
   - **Codex**: add the block to its `config.toml` and set the `BETTERSHIELD_TOKEN` environment variable to your credential.
4. Optionally copy **Something to start your assistant with**, a ready prompt.
5. Under **Connection health**, click **Test connection**. It makes one real call and says where it stopped.

On the approval page, **Allow it to change this site** is ticked when changes are possible; untick it for read-only.

**Rotate** replaces the credential. **Disconnect** ends the credential and every signed-in app. **Connected apps** lists apps that signed in through the browser, each with **Revoke**.

## What an assistant can read

Eighteen read-only abilities, each run as the account that connected the assistant:

- The score, grade and findings, with explanations, and any one audit check.
- Which hardening fixes are on, and the login protection settings (counts, never addresses).
- Two-factor and passkey rules.
- Users and roles by display name, and one member's session times.
- The activity log and agent activity.
- Incidents and their timelines.
- The file check and the quarantine list, with no file contents.
- Scheduled task health, and which recognized backup plugins are installed.
- Which plugins offer abilities, and where AI connector keys are stored, never the keys themselves.
- The vulnerability state, which in 1.1.0 says no data source is connected.

## How changes work

With step 2 on and a credential that may change the site:

- **Applied directly**, with a way back: Disable XML-RPC, Disable the dashboard file editor, Block public user listing, Stop publishing the WordPress version, Send security response headers, Find out what a content policy would break, and the five-minute, this-domain-only form of Tell browsers to refuse plain HTTP.
- **By a plan you agree to in the conversation**: the six **Signing in** fixes, the six-month or all-subdomains form of the HTTPS fix, taking any fix off, and putting a changed file back. Sign-in changes also need the recovery link verified within the last day (**Protect › Recovery**).
- **Never by an assistant**: Stop PHP running in uploads, Stop uploads directories listing their contents, Hide sensitive files from visitors.

A read-only connection cannot propose changes.

## Approve requests from other callers

On the **Requests** tab, plans from other callers, such as WP-CLI, wait for you once step 2 is on. **Show the plan** says what would change and whether it can be put back. **Allow once** shows a confirmation, once, to hand to whoever asked: it allows that single change one time, until the plan expires 15 minutes after it was made. **Withdraw** cancels it. **Include the ones already handled** adds the history.

Allowing a sign-in change also needs **Ask for my password before an action that removes a protection** on (**Settings › General**).

## What agents may do, and what stays yours

The **Permissions** tab repeats steps 1 and 2 under **What agents may do here**, then has two more cards:

- **Recording agent activity**: **Record what agents do on this site**, on by default, logs every ability call, refused ones too (WordPress 7.1 or newer). See [Agent activity](/docs/agent-activity/).
- **What stays yours**: no assistant can make an account or credential, change your recovery options, weaken two-factor or alerting, lift a lockout, remove log rows, or write wp-config.php or .htaccess. Under **How often an agent may act**: 5 changes of one kind and 30 plans per hour. Extra requests are refused, not queued.

## See what agents can reach

The **Surface** tab lists every ability any plugin offers agents, then **What else can reach this site**.

| Option | What it does | Why it matters | Default |
|---|---|---|---|
| **Registered abilities** | Every ability any plugin offers agents: whether it writes, is reachable over REST, and who can call it. Filter: **Open to lower roles**. | One that is all three becomes a finding. | All |
| **Application passwords** | Each account's application passwords, **stale** after 90 days unused. **Limit…** holds one to REST routes, an address range, or both. | A leaked one can do less. | No limit |
| **Retire application passwords that have gone unused** | Removes them daily after **Unused for (days)**, minimum 30. | Removal cannot be undone. | Off, 180 days |
| **Keep a decoy credential on my account** | Adds an application password nobody is given. | Any use is refused and alerts you. | Off |
| **Decoy URL** | A tripwire path (**Unused path**) that returns your normal 404 page and raises an urgent alert when requested. **Test matcher without alerting** checks it. | Flags probing or scanners; not proof of compromise. | Off |

**Connector credentials**, last, shows where AI connector keys are stored and how many plugins can read them (WordPress 7.0 or newer). The keys themselves are never shown.

## Related

- [Connect to BetterShield Hub](/docs/connect-to-bettershield-hub/)
- [Hardening](/docs/hardening/)
- [WP-CLI commands](/docs/wp-cli-commands/)
- [Features](/features/)