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

Install MxChat MCP Server via Plugins → Add New → Upload Plugin (or unzip into wp-content/plugins/).
Activate it from Plugins → Installed Plugins. The activation hook creates the OAuth tables and schedules the daily cleanup cron.
Confirm your MxChat Pro license is active at MxChat → Activation — the MCP endpoint will not register until it is.
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.
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 that fires a tools/list call server-side and reports response time + advertised tool count inline. Use this to verify the route is reachable before troubleshooting an external client.

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.

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.
Endpoint diagnostic: One-click button on the Endpoint tab fires tools/list against the local route and reports response time + tool count + tool names. Errors surface inline with a clear explanation.
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.

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-05-21. Spotted an issue? Open a ticket and we'll patch the doc.