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

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

## What this connection is

Elevated Product Search registers 12 WordPress Abilities under the `elevated-product-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 and lookups: `search-products` (the same index and filters the storefront widget uses), `find-filter-terms`, `list-searchable-custom-fields`
- Settings: `get-settings`, `update-settings` (partial patch), `reset-settings` (requires `confirm: true`)
- Index: `get-index-status`, `rebuild-index` (requires `confirm: true`), `get-rebuild-progress`, `get-index-schedule`
- Diagnostics: `get-environment-status`, `get-debug-logs`

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

## Contract rules that will bite you if ignored

1. `rebuild-index` and `reset-settings` require `confirm: true`. The flag is declared in the input schema with true as its only accepted value, so an unconfirmed call fails validation before any handler runs: `Ability "elevated-product-search/rebuild-index" has invalid input. Reason: confirm is a required property of input.`
2. Input schemas are closed. Unknown keys are rejected, not ignored.
3. `update-settings` takes a partial patch under `settings` and responds with the full effective settings plus `index_rebuilding`, `updated_keys`, and `deleted_keys`. Verify writes from that response.
4. Changing search-scope settings (the `searchIn*` keys) schedules an index rebuild automatically; the response reports `index_rebuilding: true`.
5. `search-products` searches the same index the storefront widget uses, honouring the configured include and exclude filters. Its `total` never exceeds the requested `limit`; it is not a catalogue-wide count.
6. Licensing, connector installation, and the access toggle are human-only. They are not abilities; do not attempt them. When the site owner switches `Allow AI agent access` off (option `elevated_product_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-products (input)
{ "query": "dress", "limit": 3 }
```

Response shape:

```json
{
  "success": true,
  "data": {
    "query": "dress",
    "total": 3,
    "products": [
      { "id": 91, "title": "Black Western Dress", "sku": "", "url": "{site_url}/product/black-western-dress/", "price": "$120.00", "in_stock": true, "type": "simple" }
    ],
    "categories": []
  }
}
```

To rebuild the index:

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

Then poll `get-rebuild-progress` until `status` is `"complete"` (`{ status, is_rebuilding, products_done, total_products, message, rebuild_id }`), and read `get-index-status` to verify `indexed_documents`.