MxChat MCP Server

Exposes your MxChat install as a Model Context Protocol (MCP) server. AI agents (Claude, Claude Code, ChatGPT, mcp-inspector) connect to a single bearer-authenticated endpoint and call a focused set of chatbot-ops tools — list transcripts, push knowledge, inspect bots, browse WooCommerce — natively, with no per-message fees.

Overview

The Model Context Protocol is the open spec Anthropic, OpenAI, and others use to let AI agents call tools on a remote server. This add-on turns your WordPress site into an MCP server: agents connect to /wp-json/mxchat-mcp/v1/mcp, run JSON-RPC tools/list to discover what's available, and then tools/call to do real work against your MxChat data. It's for anyone running MxChat who wants Claude Code, Claude.ai custom connectors, ChatGPT desktop, or a homemade agent to inspect transcripts, search the knowledge base, push new content, or manage WooCommerce orders — without screen-scraping the chatbot UI or building a separate API client. Requires the main MxChat plugin (mxchat-basic) and an active MxChat Pro license; the endpoint is gated on both.

Setup

1. Install MxChat MCP Server via Plugins → Add New → Upload Plugin (or unzip into wp-content/plugins/).
2. Activate it from Plugins → Installed Plugins. The activation hook creates the OAuth tables and schedules the daily cleanup cron.
3. Confirm your MxChat Pro license is active at MxChat → Activation — the MCP endpoint will not register until it is.
4. Go to MxChat → API Access and generate a bearer token if you haven't already. MCP reuses this same token (mxchat_api_token); there is no second secret.
5. Open MxChat → MCP Server, set your default Role (read-only or admin), and use the Connect tab to copy a ready-made snippet for Claude Code, ChatGPT desktop, or mcp-inspector. For OAuth-aware clients (e.g. claude.ai custom connectors), just paste the endpoint URL — the plugin advertises Dynamic Client Registration and walks the user through a PKCE consent flow.

Settings

All settings live at MxChat → MCP Server, organized into five sidebar tabs.

Endpoint

Read-only display of the live MCP URL (/wp-json/mxchat-mcp/v1/mcp), the masked bearer token, and a Test endpoint button. The test now runs two probes and shows a result pill for each:

• Loopback — a tools/list call the server makes to its own route. Confirms the plugin, token, and route are wired correctly. Reports response time + advertised tool count.
• External — a second probe that hits the same endpoint with the exact headers claude.ai sends (User-Agent: Claude-MCP/1.0, Accept: application/json, text/event-stream, Mcp-Protocol-Version, Origin: https://claude.ai). This is the one that catches a host-level firewall (WAF) sitting in front of WordPress.

Each probe is classified as Pass, WAF-blocked, Unreachable, or Error. If the external probe is WAF-blocked, a callout names the detected vendor (Cloudflare, Sucuri, Wordfence, SiteGround) and tells you to allowlist the endpoint — see the WAF entry under Troubleshooting below. The two-probe split matters because a WAF intercepts outside traffic but not the server's loopback call, so a loopback-only test would pass while claude.ai still couldn't reach you.

Role

A single radio choice — read-only (default) or admin — stored in the option mxchat_mcp_role. Read-only blocks the two write tools (mxchat.add_knowledge, mxchat.delete_session) with JSON-RPC error -32000; admin allows them. Switch to admin only when you trust the connected agent.

Connect

One-click copyable snippets for Claude Code (claude mcp add ...), ChatGPT desktop, and mcp-inspector, prefilled with your endpoint URL. No editable settings here — it's a help surface. A copyable curl command is also included that mimics claude.ai's request headers, so you can reproduce the external connection test from your own machine when diagnosing a firewall block.

Tools

Live list of every tool advertised by the server with its description and input schema. Auto-derived from MxChat_MCP_Tools::definitions() — what you see is exactly what an MCP client sees.

Connected Apps

Lists active OAuth clients (name, registered date, last used, authorized-by user) with a per-client Revoke button that cascades to all of that client's tokens. Also surfaces the bearer token (masked with Reveal/Copy/Regenerate), the last-used timestamp, a Recent Activity log of the last 10 tool calls, and the daily OAuth-cleanup cron status with a manual Run cleanup now button.

Features

• JSON-RPC 2.0 over HTTP: Single POST endpoint at /wp-json/mxchat-mcp/v1/mcp implementing initialize, tools/list, tools/call, and ping. Negotiates MCP protocol versions 2025-06-18 and 2024-11-05.
• Bearer-token auth that reuses MxChat's REST token: No second credential. Whatever token you generated on MxChat → API Access is what MCP clients use.
• OAuth 2.1 + Dynamic Client Registration: Drop-in custom connector for claude.ai with a branded consent screen. PKCE-S256 required, 10-minute single-use auth codes, refresh-token rotation, all tokens hashed at rest.
• Read-only / admin role gating: Per-site setting at mxchat_mcp_role decides whether write tools are exposed. Read-only is the default.
• Connect snippets for common clients: Claude Code, ChatGPT desktop, and mcp-inspector get prefilled copy-paste blocks.
• Chatbot-ops tool set: bot_info, list_transcripts, get_session, search_transcripts, list_knowledge, add_knowledge, delete_session. Focused on what you actually do with a chatbot, not generic WP admin.
• WooCommerce tool set: list_products, get_product, list_orders, get_order, search_customers. Thin adapters over /wc/v3/* with payment-secret meta stripped defensively from order payloads.
• Two-probe endpoint diagnostic with WAF detection: The Endpoint tab's test runs a loopback tools/list (response time + tool count) AND an external probe that copies claude.ai's headers, so a host firewall that blocks outside traffic is caught at setup time instead of surfacing as a silent "claude.ai can't connect". Results render as Pass / WAF-blocked / Unreachable / Error pills per probe, with a vendor-named callout (Cloudflare, Sucuri, Wordfence, SiteGround) when a block is detected.
• Daily OAuth cleanup cron: mxchat_mcp_oauth_cleanup prunes expired auth codes and revoked tokens nightly. Revoked tokens are retained for 30 days as an audit trail.

API & Integration

Endpoint: POST https://your-site.example/wp-json/mxchat-mcp/v1/mcp
Auth: Authorization: Bearer <mxchat_api_token> or an OAuth 2.1 access token.
Diagnostic GET: a GET on the same URL returns server identity (no auth needed) so you can confirm the route is live.

Example tools/list request:

curl -X POST https://your-site.example/wp-json/mxchat-mcp/v1/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tools advertised:

• mxchat.bot_info — plugin version, active embedding/chat models, transcript counts (24h / 7d / 30d), KB entry count. Call this first.
• mxchat.list_transcripts — paginated transcript rows; filter by since/until, session_id, role, has_rag_context.
• mxchat.get_session — full ordered transcript for one session_id (ascending).
• mxchat.search_transcripts — LIKE search across user + assistant messages, returns matching session_ids with snippets.
• mxchat.list_knowledge — paginated read of wp_mxchat_system_prompt_content entries; optional content_type filter.
• mxchat.add_knowledge — embed + store a new KB entry keyed by source_url (re-submit = replace). Admin role only.
• mxchat.delete_session — delete one session by id, cascading to translations and URL-click tracking. Admin role only.
• mxchat.woo.list_products — list WooCommerce products with search, category, status filters.
• mxchat.woo.get_product — full product payload by id or slug.
• mxchat.woo.list_orders — list orders with status, customer_email, after, before filters.
• mxchat.woo.get_order — full order payload; card/CVV/token meta keys scrubbed defensively.
• mxchat.woo.search_customers — find a customer by email or name (up to 20 matches).

Write tools are gated by the Role setting and return JSON-RPC error -32000 ("This tool requires admin role") in read-only mode. WooCommerce tools throw a clean error if WooCommerce is not active on the site.

Requirements

• MxChat (mxchat-basic): Required and active. The MCP server delegates auth, validation, and business logic to mxchat-basic's REST API.
• MxChat Pro License: Required. The license check (is_mxchat_pro_license_active_mcp()) gates the /mcp route — without an active Pro license the endpoints don't register. See pricing.
• WordPress: 5.8 or newer.
• PHP: 7.4 or newer (matches mxchat-basic).
• WooCommerce (optional): Only required if you want the mxchat.woo.* tool set. Other tools work without it.

Troubleshooting

"MxChat MCP Server requires MxChat Pro to be activated" notice

The license check sees mxchat_license_status as anything other than active. The /wp-json/mxchat-mcp/v1/mcp route will not register until this is fixed — agents will get a 404. Activate your license at MxChat → Activation. The OAuth discovery endpoints (.well-known/oauth-authorization-server) still register without a license so connectors can probe a license-gated resource.

"No bearer token is set" when running the endpoint test

You haven't generated a token yet. Go to MxChat → API Access and create one. The MCP add-on does not generate its own token; it reads mxchat_api_token.

claude.ai can't connect but the endpoint test passes (host WAF)

If the Loopback probe passes but the External probe comes back WAF-blocked, a firewall in front of WordPress — WP Engine's default WAF, Cloudflare, Sucuri, Wordfence, or SiteGround SG-Optimizer — is intercepting outside requests to /wp-json/mxchat-mcp/v1/mcp while letting the server's own loopback call through. That's why the route looks healthy from the admin but claude.ai still can't reach it. The callout under the test result names the vendor it detected. Fix it by allowlisting the MCP path (or the Claude-MCP/1.0 user agent) in that firewall's rules — most WAFs have a "URL exception" or "allowlist" setting for exactly this. After changing the rule, click Test endpoint again and confirm the External probe flips to Pass before reconnecting from claude.ai. Use the curl command on the Connect tab to reproduce the external request from your own machine while you tune the rule.

Client gets 401 after a token rotation

Expected. Clicking Regenerate token in the Connected Apps tab invalidates the old token instantly. Reconnect each client (Claude Code, ChatGPT, etc.) with the new token.

Write tool returns -32000 This tool requires admin role

The Role setting is read-only. Switch it to admin at MxChat → MCP Server → Role, or accept that mxchat.add_knowledge and mxchat.delete_session are blocked on this install.

mxchat.woo.* tools return "WooCommerce is not active"

The plugin defensively checks for the WooCommerce class before dispatching to /wc/v3/*. Install + activate WooCommerce, or just don't call those tools.

OAuth tables growing unbounded

They shouldn't — the daily mxchat_mcp_oauth_cleanup cron prunes expired codes and revoked tokens. If wp-cron is disabled on your host, hit Run cleanup now in the Connected Apps tab to trigger it manually, then fix wp-cron.

Last reviewed by Sage on 2026-06-10. Spotted an issue? Open a ticket and we'll patch the doc.