MxChat Core

The free MxChat plugin — the AI chatbot itself, plus everything that powers it: setup, AI models, the knowledge base, behavior, actions, display, and the REST API. Add-ons extend this core; this page documents the core itself.

Overview

MxChat turns any WordPress site into an AI chatbot that answers from your content. It runs on your server, connects to the AI provider of your choice, and answers visitor questions using a knowledge base you control — no per-message fees, no data leaving your stack except the calls you make to your chosen AI provider.

Core capabilities:

Bring-your-own AI — OpenAI, Anthropic Claude, Google Gemini, xAI Grok, DeepSeek, or any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, Azure OpenAI).
RAG knowledge base — index your pages, posts, PDFs, and custom text so the bot answers from your real content.
A guided setup wizard that walks you from "just installed" to "live on my site."
Actions — let the bot do things (capture emails, search the web, generate images, hand off to a human) not just answer.
A REST API for headless access to transcripts and knowledge.

Getting Started

When you first open MxChat in your WordPress admin, you land on the Onboarding wizard. It walks you through setup one step at a time:

Chat model — pick your AI provider and model, and paste your API key inline.
Behavior — tell the chatbot how to act (its role, tone, and the topics it should stick to). Optional — you can use the AI's defaults and refine later.
Embedding model — pick the model used to index your knowledge base. If it's the same provider as your chat model, your key is reused automatically.
Knowledge base — optionally add your first content so the bot has something to answer from. You can skip this and build it later.
Actions — optionally enable Actions (see below). Skippable.
You're set up — test the bot in your dashboard, turn it on for your site, or grab an embed shortcode.

You can reopen the setup guide any time from Settings → Tutorials.

AI Models & Providers

Choose your chat model under Settings → AI Models → Select AI Model. MxChat supports:

OpenAI — the GPT-5 family (including GPT-5.5, GPT-5.4, and the GPT-5.x Chat models).
Anthropic Claude — the Opus, Sonnet, and Haiku families, including Claude Opus 4.8 (the latest flagship).
Google Gemini — the Gemini 3.x lineup (3.5 Flash, 3.1 Pro, and more) plus Gemini 2.5.
xAI Grok — Grok 4 and Grok 3 families.
DeepSeek and Custom (OpenAI-compatible) endpoints for local or self-hosted models.

Add your API key for each provider you use under Settings → API Keys. MxChat detects a saved key and confirms it inline. You can switch models at any time; the model you pick is the one used for live chat answers.

The model list refreshes as providers ship new models. If a provider retires a model you had selected, MxChat automatically falls back to a current, working model on your next admin load — you're never stranded on a dead model.

The Knowledge Base (RAG)

The knowledge base is what makes your chatbot know your stuff. Under Settings → Knowledge you can:

Auto-sync your posts and pages so published content is indexed automatically.
Upload PDFs and Word documents to extract and index their text.
Add manual entries — paste any text you want the bot to know.
Index content from a sitemap.

By default MxChat stores embeddings in your WordPress database. For larger knowledge bases you can switch to Pinecone or OpenAI Vector Store under the Knowledge page.

Tune retrieval under Settings → Behavior: the Similarity Threshold controls how strict content matching is, and the RAG Sources / Chunks limits control how much context is sent to the AI per answer.

Behavior & System Instructions

Under Settings → Behavior, the AI Instructions field is the chatbot's "job description" — the instructions it follows on every reply (its role, tone, and guardrails). This is the highest-leverage setting for making the bot sound like your brand.

Other behavior controls:

Contextual Awareness — let the bot reference the current page's content for more relevant answers.
Citation Links — allow the bot to include source links from your knowledge base.
Satisfaction Rating — show a 👍 / 👎 prompt after a conversation so you can measure answer quality.

Actions

Actions let your chatbot do things, not just answer. When a visitor's message matches phrases you set up, the bot can run an Action instead of generating a plain reply. The free core includes:

Loops Email Capture — collect a visitor's email into your Loops mailing list.
Brave Web Search and Brave Image Search — search the web and images from chat.
Generate Image — create an image with OpenAI (GPT Image) or Google (Imagen).
Chat with PDF — answer questions about an uploaded PDF.
Live Agent Handoff — transfer the conversation to a human on Slack or Telegram, and hand it back to the bot when done.

Configure Actions under Settings → Actions. Many add-ons (WooCommerce, Forms, Perplexity, and more) register additional Actions.

Displaying the Chatbot

Turn the chatbot on for your whole site under Settings → Display → Auto-Display Chatbot, or place it manually with a shortcode:

[mxchat_chatbot floating="yes"] — a floating widget in the bottom corner.
[mxchat_chatbot floating="no"] — an inline embedded chat anywhere on a page.

The Display tab also controls chat persistence, link behavior, the chat window's text and labels, and appearance. To deploy the same chatbot on a non-WordPress site, see the MxChat Anywhere add-on.

The floating launcher button is fully keyboard-operable: Tab to focus it, Enter or Space to open the chat, and Esc to close it — focus returns to the launcher on close (WCAG 2.1 Level A).

REST API

MxChat exposes a bearer-token-authenticated REST API for headless access. Generate and manage your token under Settings → API Access. Endpoints cover reading and deleting chat transcripts, pushing knowledge, and a health check. The chat widget itself also fetches a fresh per-request security token from /wp-json/mxchat/v1/nonce, which keeps the first message reliable even behind full-page caches.

For a Model Context Protocol (MCP) interface to your install — so Claude, ChatGPT, and other agents can talk to MxChat natively — see the MxChat MCP Server add-on.

Troubleshooting

"Invalid API key" / no replies — re-check the key under Settings → API Keys; make sure it matches the provider of your selected chat model.
Bot doesn't know my content — confirm the content is indexed under Settings → Knowledge, and that an embedding model + key are configured. Lower the Similarity Threshold if good content isn't being matched.
"Access denied" on the first message behind a cache — make sure you're on the current version; MxChat fetches a per-request nonce that resolves this for WP Rocket, LiteSpeed, FlyingPress, W3 Total Cache, and Cloudflare APO.
A model shows an error after a provider change — MxChat auto-recovers retired models on the next admin load; if a specific model errors, re-select a current one under Select AI Model.
An occasional dropped or failed reply — MxChat automatically retries on transient provider errors (5xx, rate-limit, and overload responses) for both streaming and standard chat, so brief provider hiccups usually recover on their own without a visible error.

Still stuck? Ask the Documentation Bot — it has access to the full MxChat source and every plugin's docs — or open a ticket.

Last reviewed by Sage on 2026-05-30 (MxChat core 3.2.7). Spotted an issue? Open a ticket and we'll patch the doc.