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 → Pro & Extensions — the MCP endpoint will not register until it is.
Open MxChat → MCP Server and set the Access level on the Role tab (Read-only or Admin).
On the Connect tab, under Connect an AI assistant, pick your client — claude.ai / Claude Desktop, Claude Code, ChatGPT or Other MCP client — and follow its steps. Each step has a copy button for the address or command. When the client sends you back to your site, sign in as an administrator and click Allow. The status line turns green when the first call arrives (the page watches for two minutes; Watch again restarts it).
If the client cannot connect, click Check this site on the same tab (see below).

A client that cannot sign in with OAuth (a script, CI, mcp-inspector) uses the static bearer token from MxChat → API Access instead; see Advanced: Static bearer token below.

Settings

All settings live at MxChat → MCP Server, organized into five sidebar tabs: Endpoint, Role, Connect, Tools and Connected Apps.

Endpoint

Read-only display of the live MCP URL (/wp-json/mxchat-mcp/v1/mcp), whether it accepts OAuth only or OAuth + static token, and a Test endpoint button.

Test endpoint runs from the server: the two OAuth discovery documents, the sign-in challenge a client without a token must receive, an external-client request, and the static token when the site accepts one. From 1.0.8 it works without a static token, so an OAuth-only site can run it too.

Role

Access level is a single choice — Read-only (default) or Admin — stored in the option mxchat_mcp_role. Read-only lets agents list transcripts, fetch sessions, search content and inspect bot info; write tools are rejected with JSON-RPC error -32000. Admin also allows the write tools: adding knowledge, deleting sessions, creating and updating posts, the note tools, generating images, and installing or updating plugins and themes. Changes take effect on the next agent request. Switch to Admin only when you trust the connected agent.

Role → Editor access

Added in 1.0.8 and off by default (Administrators only). By default only an administrator can approve an app, and the app gets every tool the site has turned on. Switch on Allow Editors to connect to let a writer connect an AI assistant with their own account. That connection gets the WordPress content tools only and runs as that user: no transcripts, no knowledge base, no WooCommerce, no deleting, and nothing they could not already do in WordPress. Choose who counts as an Editor:

Editors who can edit everyone's posts — the Editor role. The connection can update any post or page, as the Editor can.
Anyone who can edit posts — Authors and Contributors too. Each connection is limited to the posts that user can edit, and Contributors cannot publish.

Editor connections need the WordPress content tools switched on (Tools tab) to have anything to call, and the Access level set to Admin for drafts and updates; on Read-only they can list and read only. Turning Editor access off blocks every existing Editor connection at once; administrator connections are not affected.

Connect

Connect an AI assistant (1.0.8+) is a guided flow. Pick your client and follow its numbered steps:

claude.ai / Claude Desktop — Settings → Connectors → Add custom connector, paste the endpoint address, then Connect.
Claude Code — run the copied claude mcp add command, then type /mcp inside Claude Code, choose mxchat and Authenticate.
ChatGPT — turn on Developer mode under Settings → Connectors → Advanced settings, then Create a connector with the address and OAuth authentication. Custom connectors need ChatGPT Business, Enterprise or Edu, or a Plus or Pro account with developer mode on.
Other MCP client — give it the address as a Streamable HTTP MCP server. It finds the sign-in endpoints from /.well-known/oauth-protected-resource and needs OAuth 2.1 with dynamic client registration and PKCE (S256).

In each case you sign in to your site as an administrator (or as an Editor, if Editor access is on) and click Allow. The status line turns green on the client's first call, and the connection appears under Connected Apps.

Check this site runs eight checks from your server: HTTPS, the two site addresses, both OAuth discovery documents, the sign-in challenge, whether the Authorization header reaches PHP, and whether requests from Claude and ChatGPT get through. A failed row says what to change — for example, when Cloudflare answers before WordPress it tells you to turn off Block AI bots for the site or add a WAF skip rule for /wp-json/mxchat-mcp/.

Recent sign-in refusals lists clients turned away at sign-in, with the reason and a fix.

Advanced: Static bearer token (CLI / CI fallback) holds copyable snippets for Claude Code with a static bearer and for mcp-inspector, plus a curl probe (mimics claude.ai) to run from your own machine. A 200 response with valid JSON means outside clients can reach the endpoint; a 403, 406, 503 or an HTML page means a firewall or host is intercepting requests.

Tools

WordPress content tools — off by default (added in 1.0.6). Switch on Enable WordPress content tools and a connected agent can list, read, create and update your posts and pages, work with block-editor notes, and generate images into your Media Library. While off, these tools are absent from the tool catalog and refused if called. Writing also needs the Access level set to Admin. The permission model is described under Content tools in the API & Integration section below.

Plugin and theme management — added in 1.0.8, off by default and shown with a warning. Switch on Allow plugin and theme management over MCP and an administrator's assistant can list the plugins and themes on the site, search the WordPress.org directory, and install or update plugins and themes from it. Items come from the WordPress.org directory only, never from a link or a ZIP file. Anything it installs or updates runs with full access to your site, so turn this on only for assistants you trust and keep a recent backup. If the site blocks file changes (DISALLOW_FILE_MODS in wp-config.php, or a plugin that blocks them), the card shows Blocked by this site and the tools stay hidden. Every call is recorded under Connected Apps, Recent activity.

Tools & Abilities (1.0.8+) lists every tool a connected assistant can call, with its own on/off switch; each tool is on unless you switch it off. Notes explain when a tool is hidden — for example while the content tools are disabled, or while the Access level is Read-only. Click Save tools to apply.

On WordPress 6.9 or later, the list also shows Abilities from other plugins: abilities another plugin marks as public for MCP. Each starts switched off until you turn it on (Turn on all from a plugin is available). An ability not marked read-only by its plugin is hidden while the Access level is Read-only. Abilities need an OAuth connection, because they run as the person who approved the app; Editor connections do not get them.

Shared with MCP — MxChat registers its five read-only chatbot tools as WordPress abilities in an MxChat category. They are kept from other MCP servers on the site unless you share them here, which lets the WordPress MCP Adapter, or another MCP server on the site, offer them to an administrator it has signed in. Adding knowledge and deleting sessions are never shared.

Connected Apps

Connection status shows whether the endpoint is active, the current Role (fixed in 1.0.8: it previously showed the wrong access level), when it was last used, and the endpoint. OAuth apps lists active OAuth clients (app name, registered date, last used, authorized by) with a per-client Revoke button that cascades to all of that client's tokens. The tab also holds the static bearer token (masked, with Reveal / Copy / Regenerate token) and the daily OAuth-cleanup cron status with a Run cleanup now button.

Recent activity keeps the last 20 calls (10 before 1.0.8). From 1.0.8 failed and refused calls are logged too, native tools and abilities alike, with the reason the client was given.

From 1.0.7 the card also names any connection whose authorizing administrator has been deleted or demoted, and says which of the two happened — those clients stop working immediately rather than at the next manual revoke.

Connected Apps → Advanced: Static bearer token

Added in 1.0.7. One checkbox, Accept the static bearer token on /mcp, decides whether the legacy mxchat_api_token header is honoured alongside OAuth.

The default depends on when the site first installed the add-on. Sites installing 1.0.7 or later start OAuth-only — the static token is not accepted until you switch it on. Sites that predate 1.0.7 keep accepting it, so command-line clients survive the update, and the MCP Server page carries a dismissible recommendation to turn it off once your clients connect over OAuth. An explicit save always wins over either default.

Leave it on only for scripted clients that cannot complete an OAuth flow — mcp-inspector, CI smoke tests, ad-hoc curl. Claude Code and ChatGPT do not need it.

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.
OAuth 2.1 + Dynamic Client Registration: Drop-in custom connector for claude.ai, Claude Desktop, Claude Code, ChatGPT and other MCP clients, with a branded consent screen. PKCE-S256 required, 10-minute single-use auth codes, refresh-token rotation, all tokens hashed at rest.
Granted access enforced on every call (1.0.8+): An app approved for reading only (scope mcp:read) sees no write tools, and the content and WooCommerce tools run as the person who approved the app, so they can do nothing that person could not do in WordPress.
Static bearer token fallback: For scripted clients, the token from MxChat → API Access (mxchat_api_token), accepted only while the site allows it.
Read-only / admin role gating: Per-site setting at mxchat_mcp_role decides whether write tools are exposed. Read-only is the default.
Owner re-checked on every request: An OAuth token is only as good as the administrator who authorized it. From 1.0.7 each request re-reads that user and fails closed with a 401 if they have been deleted or no longer hold manage_options — previously the capability was verified once, at authorization, so a token minted by an admin who was later offboarded kept working until somebody revoked it by hand. On multisite the check resolves against the site whose endpoint is being called; network super admins pass everywhere.
Guided connect flow and site checks (1.0.8+): Step-by-step setup for claude.ai, Claude Desktop, Claude Code, ChatGPT and other MCP clients with live confirmation of the first call, and Check this site with a fix for each failed check.
Editor access (1.0.8+, off by default): Writers connect with their own account and get the content tools only.
Per-tool switches (1.0.8+): Turn any individual tool off.
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.
WordPress content tool set (opt-in): list_posts, get_post, create_post, update_post — let an agent draft and edit posts and pages over MCP. Off by default, admin role required, new posts save as drafts, and there is no delete tool (added in 1.0.6). From 1.0.8 get_post returns a numbered outline of the post's blocks.
Block-editor Notes tools (1.0.8+, WordPress 6.9+): Read, add, reply to, resolve, reopen and delete notes on a chosen block without changing the post's text.
Image generation (1.0.8+, MxChat 3.2.26+): Generate an image with your site's image model and save it to the Media Library.
Plugin and theme management (1.0.8+, opt-in): List, search WordPress.org, install and update, with every call logged.
WordPress abilities over MCP (1.0.8+, WordPress 6.9+): Offer other plugins' public abilities to your assistant, and share MxChat's read-only tools with other MCP servers on the site.
Honest content fidelity: when WordPress strips markup from an agent's submission because the acting user lacks unfiltered_html, the tool result says so explicitly rather than reporting a silent success (added in 1.0.6).
Firewall detection: Check this site and Test endpoint send requests the way outside clients do, so a host firewall or CDN that blocks them is caught at setup time, with a vendor-named fix (Cloudflare, Sucuri, Wordfence, SiteGround) when one is detected. Sign-in refusals are logged with the reason.
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: an OAuth 2.1 access token, or Authorization: Bearer <mxchat_api_token> while the site accepts the static 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.

From 1.0.8 the transcript, session, add knowledge and delete session tools work on sites that accept OAuth clients only; previously they failed with "MxChat REST API is disabled".

Plugin and theme tools (1.0.8+, off unless enabled on the Tools tab):

mxchat.site.list_plugins — every installed plugin with its version, whether it is active, and any update available.
mxchat.site.list_themes — every installed theme with its version, whether it is active, its parent theme, and any update available.
mxchat.site.search_directory — search the WordPress.org plugin or theme directory.
mxchat.site.install — install a plugin or theme from WordPress.org by slug; left inactive unless the assistant asks to activate it. Admin role only.
mxchat.site.update — update one plugin or theme that has an update from WordPress.org; an active item stays active. Admin role only.

Content tools

Added in 1.0.6, and not advertised unless you turn them on at MxChat → MCP Server → Tools. Creating and changing content additionally requires the Role setting to be admin. From 1.0.8 they run as the person who approved the app, or as the Editor on an Editor connection.

mxchat.content.list_posts — list posts/pages, filterable by status.
mxchat.content.get_post — read one post/page in full, including its raw block markup and (1.0.8+) a numbered outline of its blocks.
mxchat.content.create_post — create a post/page. Returns the new id plus an edit_link.
mxchat.content.update_post — update an existing post/page's title, content, excerpt, or status.
mxchat.content.list_notes — read the block-editor notes on a post/page: each thread with its block, status (open or resolved), author, text and replies. Needs edit permission on the post. (1.0.8+, WordPress 6.9+)
mxchat.content.add_note — leave a note on one block, picked by its number in the get_post outline or by its text. The post's visible text never changes. Admin role only.
mxchat.content.reply_note, mxchat.content.resolve_note, mxchat.content.reopen_note — reply to, resolve or reopen a note thread. Admin role only.
mxchat.content.delete_note — move a note to the trash; only notes the connected user wrote through MCP, unless they can moderate comments. Admin role only.
mxchat.media.generate_image — generate an image with the image model chosen under MxChat → Content and save it to the Media Library with its alt text, at 1:1, 16:9, 9:16, 4:3 or 3:4. Your image provider bills each image. Needs MxChat 3.2.26 or later, the content tools enabled, Admin role and a user who can upload files. (1.0.8+)

The permission model is deliberately conservative:

New posts save as drafts. status defaults to draft; asking for publish or private requires the acting user to have WordPress's publish_posts capability, and the tool refuses with a clear message if not.
Editing someone else's post requires edit_others_posts.
There is no delete tool. An agent cannot remove your content.
post_type is restricted to an allowlist — post and page by default, filterable via mxchat_mcp_content_post_types.
content accepts raw Gutenberg block markup or HTML.

Content fidelity — read this before wiring an agent to author HTML. WordPress runs its kses security filter on saved content unless the acting user has the unfiltered_html capability. When it runs, it strips inline style attributes, ` <style> and <script> blocks, and similar markup. Single-site admins and editors have unfiltered_html`, so the common case is unaffected — but on multisite it is reserved for super-admins, and any custom role without the capability hits the same filter.

Previously that stripping was silent: the agent got a success, and the saved post quietly differed from what it sent. As of 1.0.6, when this happens the tool result includes content_modified: true and a content_notice explaining what was removed and why. MxChat does not bypass kses — that would hand a limited role a privilege it isn't meant to have. It reports the loss instead of hiding it. To preserve such markup, connect as a user that has unfiltered_html.

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. The Notes tools and WordPress abilities need WordPress 6.9 or later.
MxChat 3.2.26 or later: Needed for the image tool (mxchat.media.generate_image) only.
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 → Pro & Extensions. 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" on the Connect tab

You only need a static token for a client that cannot sign in with OAuth (a script, CI, mcp-inspector). Generate one at MxChat → API Access; the MCP add-on does not generate its own token, it reads mxchat_api_token. From 1.0.8 Test endpoint runs without a static token.

claude.ai or ChatGPT can't connect (host firewall)

Click Check this site on the Connect tab. If the rows for requests from Claude or ChatGPT fail, a firewall in front of WordPress — WP Engine's default WAF, Cloudflare, Sucuri, Wordfence, or SiteGround SG-Optimizer — is turning away outside requests to /wp-json/mxchat-mcp/ while the server's own calls get through. The failed row names the vendor it detected and the fix: allow the client's user agent, or POST requests to /wp-json/mxchat-mcp/, in that firewall. On Cloudflare, turn off Block AI bots for the site or add a WAF skip rule. Run the check again and confirm the row passes before reconnecting. Also look at Recent sign-in refusals on the same tab for the reason a client was turned away, and use the curl probe under Advanced to reproduce the outside request from your own machine.

An Editor's connection stopped working

Editor access was turned off. That blocks every Editor connection at once. Switch Allow Editors to connect back on under MxChat → MCP Server → Role, or have the Editor's work done through an administrator's connection.

A tool is missing from the client's tool list

Check Tools & Abilities on the Tools tab: the tool may be switched off, or hidden because the content tools or plugin and theme management are disabled, or because the Access level is Read-only. An app approved for reading only, and an Editor connection, see fewer tools by design. Reconnect the client afterwards so it re-reads the tool list.

Tools fail with "MxChat REST API is disabled"

Update to 1.0.8. On sites that accept OAuth clients only, the transcript, session, add knowledge and delete session tools failed with this message.

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.

A working OAuth client started returning 401 and nothing was revoked

From 1.0.7 the administrator who authorized a connection is re-checked on every request. If that WordPress user was deleted, or their role was changed so they no longer have manage_options, the connection fails closed from that moment. Open Connected Apps — the affected client is named there with the reason. Re-authorize it from an account that is still an administrator.

A CLI script that used the bearer token gets 401 on a fresh install

Sites that first installed the add-on on 1.0.7 or later accept OAuth only. Switch on Connected Apps → Advanced: Static bearer token → Accept the static bearer token on /mcp if the client genuinely cannot do OAuth, or move it to an OAuth flow. Sites that were already running an earlier version are unaffected — the static token keeps working there until you turn it off.

Write tool returns `-32000 This tool requires admin role`

The Access level is Read-only. Switch it to Admin at MxChat → MCP Server → Role, or accept that the write tools (mxchat.add_knowledge, mxchat.delete_session, content create/update, the note write tools, mxchat.media.generate_image and mxchat.site.install / mxchat.site.update) are blocked on this install.

The agent can't see the `mxchat.content.*` tools

They're off by default. Turn them on at MxChat → MCP Server → Tools, and confirm Role is set to admin — both are required before the tools are advertised in tools/list. Reconnect the client afterwards so it re-reads the tool list.

The agent saved the post, but the styling / embed is missing

Check the tool result for content_modified: true and its content_notice. WordPress's kses filter removed the markup on save because the connection's acting user lacks the unfiltered_html capability — most often on multisite (where it's super-admin-only) or with a custom role that doesn't grant it. The save genuinely succeeded; the markup just wasn't stored. Connect as a user with unfiltered_html to preserve it. MxChat reports this rather than bypassing kses.

The agent published something when I expected a draft

create_post defaults to draft, so this means the agent explicitly asked for status: publish and the acting user had publish_posts. If you don't want that possible at all, set Role back to read-only or turn the content tools off — or connect as a user without publish_posts, which makes the tool refuse the publish and save a draft instead.

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