# How to Connect Your AI Agent to Elevated Site Search (agent documentation)

> Machine-readable documentation for AI agents. Human version: https://elevatedextensions.com/documentation/site-search/connect-ai-agent/

## What this connection is

Elevated Site Search registers 14 WordPress Abilities under the `elevated-site-search/*` namespace. Agent Connector for WP serves them over MCP (Streamable HTTP) at:

```
{site_url}/wp-json/mcp/mcp-adapter-default-server
```

Authentication: WordPress application password (Basic auth), typically via the `@automattic/mcp-wordpress-remote` stdio proxy with env vars `WP_API_URL`, `WP_API_USERNAME`, `WP_API_PASSWORD`.

## Discovery

- `tools/list` on the MCP endpoint returns the exposed tools.
- `mcp-adapter-discover-abilities` lists every registered ability; `mcp-adapter-get-ability-info` returns an ability's full input/output JSON Schema; `mcp-adapter-execute-ability` executes one.

## The ability surface (summary)

- Search: `search-site` (the same index, scope, and fuzzy matching visitors get)
- Settings: `get-settings`, `update-settings` (partial patch of the 169-key settings object), `reset-settings` (requires `confirm: true`)
- Index: `get-index-status`, `rebuild-index` (requires `confirm: true`; optional `engine`), `cancel-rebuild` (requires `rebuild_id` + `confirm: true`), `get-rebuild-progress`
- Scope lookups: `list-indexable-post-types`, `list-searchable-custom-fields`, `find-filter-terms`
- Analytics: `get-popular-searches`, `clear-popular-searches` (requires `confirm: true`)
- Diagnostics: `get-health`

The exact schema of every ability and captured request/response examples: https://elevatedextensions.com/documentation/site-search/managing-with-ai-agent/?format=agent

## Contract rules that will bite you if ignored

1. Four abilities require `confirm: true`: `reset-settings`, `rebuild-index`, `cancel-rebuild` (which also requires the running `rebuild_id`), and `clear-popular-searches`. The flag is schema-required, so an unconfirmed call fails validation before any handler runs: `Ability "elevated-site-search/rebuild-index" has invalid input. Reason: confirm is a required property of input.`
2. Settings and index operations are serialized behind a mutex. A concurrent attempt fails with `Another settings or index operation is already in progress.` Wait for `get-rebuild-progress` to report a terminal status before the next mutation.
3. `update-settings` takes a partial patch under `settings` and responds with `{ settings, index_rebuilding, rebuild_mode }`. Changing scope settings (indexed post types, custom fields, taxonomies, comments) triggers an index rebuild automatically. Note: `update-settings` is annotated destructive but takes no `confirm` key; sending one fails the closed schema.
4. `search-site` results are lean by design: `thumbnail` is always null, `url` is the plain `/?p=N` form, and `categories` is empty. The storefront UI resolves richer data separately; use the `id` when you need precision. Agent searches are NOT recorded in search analytics, so you can search freely without polluting the popular searches list.
5. Licensing, connector installation, and the access toggle are human-only. They are not abilities. When the site owner switches `Allow AI agent access` off (option `elevated_site_search_agent_access`), the abilities are not registered and calls fail with a `404`, code `rest_ability_not_found`, message `Ability not found.` Ask the human to switch it on; agents cannot.

## Minimal worked example

```json
// search-site (input)
{ "query": "denim care", "limit": 5 }
```

Response shape:

```json
{
  "success": true,
  "data": {
    "results": [
      { "id": 9150, "title": "<mark>Denim</mark> <mark>Care</mark> 101: How to Wash Jeans Without Fading", "excerpt": "Raw and dark-wash <mark>denim</mark> fades because...", "url": "/?p=9150", "type": "post", "typeLabel": "Post", "thumbnail": null, "date": "2026-08-25 23:02:41", "categories": [] }
    ]
  }
}
```

To rebuild the index:

```json
// rebuild-index (input)
{ "confirm": true }
```

Poll `get-rebuild-progress` until `status` is `"complete"` (`{ status, posts_done, total_posts, message, rebuild_id, target_engine }`), then verify with `get-health` (`{ status, engine, index_exists, document_count }`).