Documentation

How to connect your AI client to your site

Let your own AI client read your store’s filters, Popular Facets and indexed product state through the optional xFacets site MCP server.

xFacets 0.1.24 · MCP Adapter 0.7.1–0.7.x · Desktop and command-line clients

What you need

Available from xFacets 0.1.24. The eight tools are read-only: they can explain your filters and indexed catalogue, but cannot save settings, reorder filters or change products.

  • A paid xFacets plan with a managed environment assigned to this site. Every assigned slot is supported; Free sites have no site MCP server.
  • WordPress 6.9 or later, on a single site. Multisite is not supported.
  • The separately installed, active MCP Adapter plugin, version ≥ 0.7.1 and < 0.8.0. We tested 0.7.1. A copy bundled inside WooCommerce or another plugin does not qualify.
  • HTTPS and WordPress Application Passwords enabled.
  • A desktop or command-line MCP client that supports HTTP authentication. The site integration does not support claude.ai or ChatGPT web connectors.

Your client talks to your own WordPress site. For index-backed reads, the plugin uses its existing managed-service connection. xFacets does not forward the MCP conversation to WPXFacets; your chosen AI client handles the data it reads.

1. Turn on agent access

  1. Install and activate the canonical MCP Adapter plugin in Plugins.
  2. Open XFacets → Settings → General.
  3. In Agent access (MCP), switch on Enable agent access and click Save Changes.
  4. Check the status below the switch. Agent access is on means the server is running. Otherwise the message identifies the missing requirement.

Access starts off. Installing or updating xFacets does not enable it automatically.

2. Create a dedicated user

  1. Open Users → Add New User on the client store.
  2. Choose a username such as ai-agent and an email address you control.
  3. Choose the xFacets agent (read-only) role and add the user.

This role has basic WordPress read permission and xfacets_read_site_config. Administrators can connect too; a dedicated user limits access and is easier to revoke. Application Passwords work on all WordPress API routes that the user is permitted to use, so keep the dedicated role narrow.

3. Create an Application Password

  1. Open Users → All Users and edit the dedicated user.
  2. In Application Passwords, enter a name such as Claude Code on my laptop and click Add New Application Password.
  3. Copy the generated password now; WordPress shows it once. Store it in your client’s private configuration or credential store.

Your normal WordPress login password is not used here. Keep the Application Password and its Base64 form out of chats, tickets, shared files and version control. Use one Application Password per client so you can revoke each connection separately.

To prepare an HTTP Basic header, encode username:application-password on your own computer. The header value is Basic <base64-encoded username:application-password>. Base64 is an encoding, not encryption.

4. Connect your AI client

Use the MCP endpoint on your own store:

https://your-store.example/wp-json/mcp/xfacets

This is a placeholder. Replace https://your-store.example with the URL of the client’s WordPress site. Include its subdirectory when WordPress is installed in one. Keep /wp-json/mcp/xfacets after that base URL. Do not use wpxfacets.com or the central WPXFacets MCP address.

For Claude Code, use an HTTP MCP connection with an Authorization header. The connection fields are:

{
  "mcpServers": {
    "xfacets": {
      "type": "http",
      "url": "https://your-store.example/wp-json/mcp/xfacets",
      "headers": {
        "Authorization": "Basic <base64-encoded username:application-password>"
      }
    }
  }
}

Place these values in the client’s private configuration. A project .mcp.json may be shared or committed; do not put a real password or header there unless the file is kept private and excluded from version control.

Restart or reconnect the client, then ask it to list the xfacets tools. We verified this direct HTTP connection with Claude Code 2.1.311 against a synthetic local store; all eight tools were listed and called successfully.

Other desktop clients may use the @automattic/mcp-wordpress-remote proxy. The following pinned configuration is documented, but was not tested by us:

{
  "mcpServers": {
    "xfacets": {
      "command": "npx",
      "args": [
        "-y",
        "@automattic/mcp-wordpress-remote@0.5.4"
      ],
      "env": {
        "WP_API_URL": "https://your-store.example/wp-json/mcp/xfacets",
        "WP_API_USERNAME": "ai-agent",
        "WP_API_PASSWORD": "<application-password>"
      }
    }
  }
}

What the eight tools can read

ToolReads
xfacets-get-site-overviewPlugin version, engine, languages, assigned environment, sync and index status.
xfacets-list-filtersThe configured filters in one catalogue language.
xfacets-get-category-filter-orderThe effective order, pins and hidden filters for one category.
xfacets-get-synonym-stateSynonym counts and local deployment state, without synonym terms.
xfacets-get-popular-facetsPopular Facets aggregates for 7, 30 or 90 days, with completeness and collection state.
xfacets-get-facet-countsFacet counts for a category, selected filters and optional bounded search text.
xfacets-get-facet-candidatesCategory attributes/taxonomies, coverage and top values, configured or not.
xfacets-inspect-productOne product’s indexed filter values compared with WordPress.

Responses identify their source, freshness and truncation. A tool reports unavailable with a reason when its index-backed read fails, instead of treating the failure as zero counts. Index-backed tools are limited to 20 calls per user per clock minute.

Popular Facets statistics stay in your WordPress database. xFacets itself sends no Popular Facets event, session value, hash or aggregate to WPXFacets infrastructure. If you enable MCP, your own AI client can read bounded aggregates directly from your store. Search Analytics, credentials, raw indexed documents and physical index names are excluded.

Try asking: “List the filters for catalogue language en”, “What is the effective filter order for category 42 in en?” or “Compare product 123’s indexed filter values with WordPress in en.” Use language codes and IDs that exist in your store.

Troubleshooting

ResultCheck
404 / rest_no_routeCheck the site URL, then the status under Agent access (MCP): setting, assignment, canonical adapter/version and single-site support.
401 / rest_forbiddenNo valid credentials reached WordPress. Use HTTPS and check whether the host or proxy stripped Authorization.
401 / incorrect_passwordCheck the dedicated username and Application Password; it may have been revoked.
403 / rest_forbiddenCheck that the dedicated user still has xFacets agent (read-only) or the required capability.
unavailable / rate_limitedWait the reported retry_after_s before another index-backed call.
No Application Passwords sectionConfirm HTTPS and whether a security plugin disables Application Passwords.

On hosts that strip the Authorization header, ask the host to pass it through to PHP. For an Apache WordPress rewrite setup, the relevant rule belongs after RewriteEngine On inside the WordPress rewrite block:

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

An invalid language, category, product or unknown input field is refused before the read. Ask the client to use a supported catalogue language and an existing category/product in that language.

Revoke access

  • For one client: open the dedicated user’s profile and Revoke its Application Password. Its next request fails authentication.
  • For all site MCP clients: turn off Enable agent access and save. The site MCP route disappears.
  • To withdraw the user’s permission: remove the dedicated role/capability or delete the dedicated user.
  • Deactivating the MCP Adapter stops this integration and any other servers that adapter provides.

Revoking access stops future reads. It does not remove information your AI client already received; manage that in the chosen client or provider.

WPXFacets newsletter

Stay up to date with WPXFacets.

We’re continuously improving WPXFacets. Subscribe for new features, product improvements and the latest news.

Product updates, occasionally. Unsubscribe anytime. Privacy policy