WPSmarto

Smart MCPDocumentation

Everything you need to run Smart MCP.

Setup guides, settings explained, and fixes for the most common problems. For the free plugin and the Pro add-on. Written for Smart MCP 1.0.8 and Pro 1.0.4. Updated 2026-11-16.

Back to Smart MCP

20 sections in Smart MCP.

Start here

What Smart MCP does

Smart MCP turns your WordPress site into an AI workspace: a chat inside wp-admin, and an MCP server that Claude, ChatGPT, Cursor and other AI apps can connect to.

The AI works through a registry of tools. Every tool needs the right WordPress capability, and medium or high risk actions pause until you approve them. The free plugin is complete on its own. Nothing in it is locked or limited.

  • Chat with your site in WP Admin: streaming answers, saved conversations you can rename, a model switch per conversation, and a Stop button that ends a reply after the current step.
  • Connect AI apps such as Claude Desktop, the ChatGPT desktop (Codex) app, Claude Code, Cursor and VS Code: pick the app and paste one ready-made message. Claude.ai and ChatGPT on the web sign in through the browser.
  • Content and media: posts, pages, comments, media, menus and taxonomies. Create, schedule or duplicate posts with categories, tags, excerpt and featured image in one step, and change one heading, paragraph or section without touching the rest.
  • SEO internal linking: new blog posts are linked to related posts and pages in a number that fits their length. Link audits find broken links, and link rules per content type are set in Settings.
  • Free images: photos from Openverse, or Pixabay with your free key, placed inside posts with alt text and a credit.
  • Custom sites: maps custom post types, taxonomies, custom fields, custom plugins and code snippets, then works with them.
  • Block editor and Site Editor: read and edit blocks, use patterns, update block theme templates. Every change keeps a revision.
  • Elementor: build pages with native widgets, and full Elementor 4 design with tokens, global classes, per-device styles and animations.
  • Divi 5 (with Smart MCP Pro): build pages, Theme Builder headers and footers, Library items, global colors and presets, and change every Divi theme setting.
  • Checks its own work: empty headings and buttons, missing alt text, heading order, broken internal links and hand-typed colors.
  • Undo a whole conversation: every post or page changed in a chat gets a restore point. Ask the AI to undo and it all goes back.
  • Safe edits for live pages: bigger changes happen on a private draft copy with a preview link and go live only when you say so.
  • Telegram bot: chat with your site from Telegram.
  • System check: compares your hosting with what the chat needs and tests live replies, so you know what to change before long tasks.

Good to know:Requires WordPress 6.4 or newer and PHP 8.0 or newer. Tested up to WordPress 7.1. Multisite is not supported yet.

Start here

Install and send your first message

A short setup in five steps. Each step saves as you go.

  1. Install Smart MCP from the WordPress Plugins screen, or upload the smarto-smart-mcp folder to /wp-content/plugins/, and activate it. Getting Started opens.
  2. AI: choose the AI for the Chat page and Telegram (OpenAI, Anthropic, OpenRouter, Google Gemini or Custom), paste its API key, click Test and pick a model. Only connecting Claude or ChatGPT? Skip this step, they bring their own AI.
  3. Permissions: choose how much the AI asks first: Full control, Standard or Strict.
  4. Apps (optional): click the AI app you use, for example Claude Desktop or ChatGPT. The Connect page opens with that app ready.
  5. Done: click one of the example requests. The Chat page opens with it typed in, ready to send.

The WP Admin menu has these pages: Getting Started, Chat, Connect, AI Providers, Context, Telegram Bot, Audit Log and Settings. With Pro it also has Skills, Security and Pro License. Each page shows a header with the page name, whether an AI provider is set up, and whether the MCP server is on.

Start here

Hosting requirements and the system check

What your hosting needs for a smooth chat, and how to check it in one click.

Open Smart MCP > Chat and click System check. It compares your server with what the chat needs. When something needs attention, a banner on the Chat page says so.

CheckRecommendedWhy it matters
PHP version8.1 or newer (8.0 works)Faster and still gets security updates
PHP time limit120 seconds or moreLong AI tasks need time. Smart MCP raises the limit for the chat when your host allows it.
PHP memory256MBig pages and long conversations need memory
cURL and OpenSSLInstalledNeeded to talk to AI services securely
PHP output compressionOffWhen on, replies appear all at once at the end instead of live
Proxy or CDNAllows long requestsCloudflare and some host proxies stop requests after a set time
Live repliesArrive live, connection stays openTested with the Run live reply test button

Run live reply test sends a reply in small parts for 30 seconds, like a long AI task. It shows whether replies arrive live and whether your host keeps the connection open, and names the host or proxy it detects.

Good to know:Your host can change most of these in its control panel. While the AI works, Smart MCP keeps the connection busy so proxies do not close it. For very long jobs, Claude, ChatGPT and other AI apps connected on the Connect page do not depend on these limits.

Set up

AI providers and API keys

Choose which AI powers the Chat page and the Telegram bot, and manage your keys.

ProviderWhat it is
OpenAIGPT models from OpenAI
Anthropic (Claude)Claude models from Anthropic
Google GeminiGemini models from Google
OpenRouterOne key for models from many companies
Custom (OpenAI-compatible)Any server with an OpenAI-compatible API, such as a local or self-hosted model. Add its base URL.
  1. Open Smart MCP > AI Providers.
  2. Under "API keys", paste a key for each provider you want to use and save.
  3. Click Test connection. It shows how many models are available.
  4. Under "AI for the Chat page and Telegram", pick a provider and a model. The model field is searchable: type any words, in any order, and use the arrow keys. Each provider's recommended model is listed first: GPT-5.4 mini (OpenAI), Claude Sonnet 4.6 (Anthropic), Gemini 3.7 Flash (Google) and ~deepseek/deepseek-v4-flash-latest (OpenRouter).

Keys are encrypted at rest and never shown again in full. Use Replace to enter a new one or Remove to delete it. Each provider shows a status: In use, Key saved or Not set up. You can still switch the model for a single conversation on the Chat page.

The At a glance panel shows the provider and model in use, how many keys are saved, which AI the Telegram bot uses, and a status line that says what is still missing, such as a key or a model.

Good to know:AI apps connected on the Connect page (Claude, ChatGPT and others) bring their own AI. They do not use this setting.

Set up

Connect Claude, ChatGPT, Codex, Cursor and other AI apps

Pick your app. The best way to connect it is already chosen, and every step is filled in for you.

The Connect page is for AI apps that bring their own AI. To use Gemini, OpenAI, Claude or OpenRouter inside WordPress, on the Chat page and in Telegram, add the key on AI Providers instead.

  1. Open Smart MCP > Connect. The MCP server switch at the top should show On, and the site check below it shows anything your site still needs, with a Turn on button where possible.
  2. Which app do you use? Pick it. Chat apps: Claude Desktop, Claude.ai, ChatGPT and the ChatGPT desktop (Codex) app. Coding tools: Claude Code and Cursor. More apps has VS Code, GitHub Copilot, Codex CLI, Windsurf, Antigravity, Cline, Roo Code, Kilo Code, Amazon Q, Zed and OpenCode.
  3. Set it up. For desktop and coding apps, type a key name and click Create key and fill in the steps. Copy the message under Easiest: paste this message into the app, paste it into the app and send it. In Claude Desktop, use the Code tab.
  4. For Claude.ai and ChatGPT on the web, follow the steps and approve in your browser: log in to WordPress as an administrator and click Approve.
  5. Check that it works. The page shows Connected when the app reaches your site. Start a new chat in the app: tools only load in new chats.

Each app gets its own key. Under Connected apps you see when each key was last used, and removing a key disconnects only that app. Set it up yourself instead shows the manual config and these addresses:

https://your-site.com/wp-json/smart-mcp/v1/mcp
https://your-site.com/wp-json/smart-mcp/v1/.well-known/mcp.json

For regular Claude chats in Claude Desktop, open Add as a Claude connector: in Claude Desktop go to Customize > Connectors > + Add > Add custom connector, name it Smart MCP and paste the server address. Then sign in through the browser, or choose No sign in and add the Authorization request header the Connect page shows. Connectors and the web apps need a public https:// site.

Careful:A message or config that contains a key gives access to your site. Do not share it or post it in public.

Set up

What AI apps can do, and as which account

External apps do content work only, under an account you choose.

External apps can work with posts, pages, Elementor and block editor design, media, comments, taxonomies, store content and read-only site information. They cannot install, activate or update plugins and themes, manage users, change site settings or modify site code. That work is part of Smart MCP Pro.

By default, requests run as a non-administrative user who can edit posts, for example an Editor. Under Connect > Account used by AI clients you can choose that account or create a dedicated Editor account.

If your site has only an administrator account, tick the confirmation box under Use my administrator account and turn it on. AI apps then create, edit and delete content under your name, but stay limited to the same content tools an Editor can use. Every action is recorded in the Audit Log and you can turn it off at any time.

Working with content

Write and edit posts and pages

Ask in plain words. The AI changes exactly what you asked and tells you what happened.

One request can create a post or page and set its categories (missing ones are created), tags, excerpt, URL slug, featured image and status. Dates work in plain words, for example "schedule it for next Monday at 10am". Ask to duplicate a post and you get a draft copy with its content, terms, featured image and Elementor design.

Change one part only. Ask for one heading, one paragraph or one section, and only that part changes. The rest of the post stays exactly as it was, in the block editor and the Classic Editor. For Elementor pages the AI changes the single element. Asking to add a paragraph adds it; it never rewrites the whole post for a small change.

  • Drafts stay drafts. The AI never publishes, schedules, unpublishes or trashes anything unless you ask.
  • Honest results. It says something is done only when the tool confirmed it. If an action was blocked or failed, it tells you.
  • Links in replies. After creating or changing an item, the AI names it as a link, with an edit link next to it. Drafts get a preview link. Only links to your own site are clickable in the chat; links to other sites are shown as text for safety.
  • Stop. While the AI works, the Send button turns into Stop. It stops after the current step, so nothing is left half done.
  • Undo. Ask the AI to undo and everything it changed in that conversation goes back.

Working with content

Images, Openverse and Pixabay

Ask for an image without a link and the AI finds a real, free photo.

By default the AI searches Openverse, the free library of openly licensed images run by WordPress.org. It uploads the best match to your media library with alt text and a credit caption, and can set it as the featured image.

Images inside posts. Ask for images in a post and the AI places one per section, under the matching heading after its first paragraph, each a different image.

Use Pixabay instead (optional):

  1. Create a free account on pixabay.com and copy your API key from the Pixabay API page.
  2. Open Smart MCP > Settings > Image search, paste the key and click Save key. It is checked with Pixabay first and stored encrypted.
  3. Image search now uses Pixabay. You can also paste a Pixabay page link and ask the AI to upload that image.

A saved key is shown masked, with Replace and Remove. Without a key, Openverse is used.

Working with content

Custom post types, fields and code

Many sites run on custom content. Smart MCP looks first, then works with it the right way.

Ask "What is custom on my site?" and the AI lists custom post types (with how many items each has), custom taxonomies, custom field groups and field names, custom shortcodes and blocks, plugins and themes that are not from WordPress.org, must-use plugins and code snippets (titles only).

It can then create and edit items of any content type, such as properties, courses or events, with their terms and field values. Fields from ACF or Secure Custom Fields are saved the way those plugins expect. Meta Box, Pods, JetEngine, ACPT, CMB2 and Carbon Fields are recognized too.

Good to know:The AI never edits plugin, theme or snippet code to change content. Complex field types such as repeaters, groups and relationships are handled by Smart MCP Pro.

Control

Permissions and approvals

You decide what the AI may do without asking.

Reading and other low-risk actions always run. On Smart MCP > Settings, the permission policy decides what happens to changes and risky actions:

PolicyChangesRisky actions
StrictAsk firstBlocked
Standard (recommended)RunAsk first
Full controlRunRun (critical tools still need their own switch)

Critical tools are the most powerful tools, added by extensions such as Smart MCP Pro (for example running PHP). When off, they are blocked on the Chat page and for AI apps. The Telegram bot has its own switch.

On the Chat page and in Telegram, an action that needs approval shows an Approve button right where you chat. Claude, ChatGPT and other apps cannot show that button, so their requests wait on the Settings page under Waiting for approval. Approving runs the action right away.

Good to know:These choices never go beyond WordPress permissions: the account the AI works as still needs the capability for every action.

Control

Context and the Audit Log

Give the AI standing instructions, and see everything it did.

Smart MCP > Context shows the system context the AI receives and lets you add your own site-specific instructions, for example your tone of voice or what never to touch. They apply in every conversation. You can switch them off without losing the text.

Smart MCP > Audit Log records what the AI did, including actions from external apps. The summary at the top shows totals for all entries, tool calls, chat messages, errors and blocked actions; click one to filter the list. Filter by type, tool and status, open an entry to see what was sent and returned, and export the list as CSV. Users who are allowed to can also clear it.

Good to know:A number next to Settings in the Smart MCP menu counts AI actions waiting for your approval. Approve or deny them on Smart MCP > Settings under "Waiting for approval".

Telegram

Set up the Telegram bot

Chat with your site from Telegram. Only the chat you link can use the bot.

The Smart MCP > Telegram Bot page has a status badge (Setup needed or Bot ready) and four steps.

Step 1: Connect your bot

  1. In Telegram open @BotFather, the official bot for creating bots.
  2. Send /newbot, then choose a name and a username that ends in "bot", for example mysite_helper_bot.
  3. BotFather replies with a token like 123456789:AAH.... Copy it.
  4. Paste it into Bot token, keep Bot is on enabled and click Save and connect.

Saving checks the token with Telegram and connects the webhook for you. The token is stored on your site and only its first 6 and last 4 characters are ever shown. Use Replace token to change it.

Step 2: Connect the webhook. The webhook is how Telegram delivers your messages to your site. It connects automatically when you save the token. The page shows Connected, Connected without the security check, or Not connected, with buttons to Connect or Reconnect webhook, Disconnect webhook and Test bot.

https://your-site.com/wp-json/smart-mcp/v1/telegram/webhook

Step 3: Link your chat. Send any message such as "hi" to your bot. Your chat appears on the page within a few seconds (it stays offered for 30 minutes). Click Link this chat. Or enter your numeric chat ID: send a message to @userinfobot, which replies with your ID, then click Link chat ID.

Step 4: How the bot works (optional). Choose the AI provider and model for Telegram, the permission policy, and the Critical tools switch. By default the bot uses the same AI and permissions as the Chat page.

Good to know:Remove bot deletes the token, disconnects the webhook and unlinks your chat.

Telegram

Using the bot and its settings

Commands, approvals and what each setting means.

CommandWhat it does
/newStart a fresh conversation
/clearClear the conversation
/stopEnd and clear the conversation
/helpShow the commands

While the AI works, the bot shows as typing, and the answer arrives as one message. There are no extra status messages in the chat.

The bot remembers the conversation until you clear it. Anyone who is not the linked chat gets "This bot is private." The bot answers as a WordPress user with content permissions, such as an Editor.

SettingMeaning
AI providerSame as Chat page by default, or a different provider for Telegram only
ModelLeave empty to use the provider's model, or type a model name
Permission policySame as Settings, Full control, Standard or Strict. When an action needs your OK, the bot sends Approve and Deny buttons in Telegram.
Critical toolsThe most powerful tools from extensions such as Smart MCP Pro. Separate from the switch on the Settings page.

Good to know:In the free plugin the whole job runs inside one Telegram request, so it suits everyday tasks, one at a time. For very large jobs use Claude, ChatGPT or another app on the Connect page, or Smart MCP Pro, which runs Telegram jobs in the background.

Troubleshooting

The Telegram bot does not reply

Check these in order on Smart MCP > Telegram Bot.

  1. Token. It must look like 123456789:AAH.... If the page says the saved token is not a Telegram bot token, your browser may have filled in a password. Paste the token from BotFather again. If it says the token has not been checked, click Save.
  2. Bot is on. When off, the bot ignores every message.
  3. Webhook. It must say Connected. If it says Not connected or Connected without the security check, click Connect webhook or Reconnect webhook. Read "Last error reported by Telegram" if one is shown, and click Test bot.
  4. Linked chat. If the bot says "This bot is not linked to your site yet", send it a message and click Link this chat. If the saved chat ID is not a number, link the chat again.
  5. "This bot is private". You are writing from a chat that is not the linked one.
  6. No user found. The bot needs a WordPress user with content permissions. Create an Editor.
  7. AI key. Make sure a provider key is saved on AI Providers, otherwise the bot cannot answer.
  8. HTTPS. Telegram must be able to reach your site over HTTPS. A local site on localhost cannot receive Telegram messages.
  9. Long jobs. They can stop at your host's time limit. Send /new and ask for smaller steps, or use Smart MCP Pro background jobs.

Troubleshooting

The AI chat does not answer or stops

The chat explains every problem and what to do next. These are the most common ones.

  • On AI Providers, select the provider and a model, add the API key and click Test connection. "No models returned. Check the API key." means the key is wrong or has no access.
  • For the Custom provider, add the base URL of your OpenAI-compatible server. Keys are not shown again; use Replace to enter a new one.
  • Keep the Chat page open while the AI works. The waiting line shows how long it has been working; long tasks can take a few minutes.
Message in the chatWhat to do
The connection closed before the AI finishedYour host or a proxy ended the request. Click Continue, or ask for smaller steps. Run the system check to see your limits.
Your host stopped the requestThe task ran longer than your hosting allows. Click Continue, or work in smaller steps.
Your login session endedReload the page and send the message again.
The chat could not reach your siteA security plugin or server rule blocks the WordPress REST API. Allow /wp-json/smart-mcp/.
Something blocked the replyA security, cache or maintenance plugin answered instead of WordPress. Exclude /wp-json/smart-mcp/ from it.
Your site hit a server errorA PHP error stopped the request. Your hosting error log has the details.

Good to know:Steps the AI finished before a problem are saved. You can see them in the Audit Log and undo them from the chat.

Troubleshooting

An AI app cannot connect or its action does not run

Start with the site check at the top of the Connect page.

  • On Connect, fix anything marked in red at the top. The MCP server switch must be on.
  • Start a new chat or session in the app. Chats that were already open do not see new tools.
  • Quit and reopen the app if you edited a config file.
  • Make sure the whole key was pasted. If unsure, create a new key: old ones keep working until you remove them.
  • Claude.ai, ChatGPT on the web and Claude connectors reach your site from the internet, so local or password-protected sites do not work with them. Paste the message into the app instead.
  • Actions that need approval from an AI app wait on Settings > Waiting for approval. Approve them there.
  • AI apps can only do content work in the free plugin. Plugin, theme, user and settings actions need Smart MCP Pro.
  • See Recent connections on the Connect page and the Audit Log for what the app did.

Using a security plugin, a firewall or a custom login address? See Security plugins, firewalls and custom login URLs below.

Troubleshooting

Security plugins, firewalls and custom login URLs

Smart MCP works with custom login addresses and with security plugins. A few addresses just need to stay open.

AI apps never use wp-login.php or wp-admin. They talk to your site through the WordPress REST API, with an API key or a browser sign-in. So a custom login address, such as /my-login/ instead of wp-admin, changes nothing for them.

Browser sign-in (Claude.ai, ChatGPT on the web and Claude connectors) asks you to log in through WordPress's own login address, so it sends you to your custom login page automatically. After you log in, you approve the app and go back to it.

Smart MCP > Connect checks your setup at the top of the page. It tells you when:

  • REST API open to AI apps fails: a security plugin allows the REST API only for logged-in users, or turned it off, or a firewall blocked the request. The message says which.
  • API key reaches WordPress fails: a firewall blocks requests that carry a key, or your server removes the Authorization header.

If something is blocked, allow these addresses in your security plugin or firewall:

AddressUsed for
/wp-json/smart-mcp/Everything AI apps do (the MCP server, keys, browser sign-in steps)
/?smartmcp_oauth=authorizeThe page where you approve an app after browser sign-in
/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resourceHow Claude.ai, ChatGPT and connectors find the browser sign-in

If your server removes the Authorization header, ask your host to pass it to PHP, or add this line to .htaccess (Apache):

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

Good to know:Our free Smarto Login Security plugin works with Smart MCP out of the box: custom login URL, two-factor authentication, brute-force limits and CAPTCHA protect the login forms, not the REST API, so AI apps keep working.

Troubleshooting

After you update Smart MCP

Updates keep your settings, keys and license. Your AI app just needs to load the tool list again.

While WordPress installs an update, it switches the plugin off for a few seconds and turns it back on when the files are in place. An AI app that is connected at that moment loses the connection or sees a shorter tool list. AI apps also keep the tool list they loaded first, so new tools from an update do not show up on their own.

After each update of Smart MCP or Smart MCP Pro:

  • Wait until WordPress says the update is done, then reload your Plugins page once.
  • In your AI app, reconnect or refresh the connection to your site. In Claude Desktop, quit and reopen the app. In Claude.ai and ChatGPT, open the connector settings and reconnect or refresh it.
  • Start a new chat. Chats that were already open keep the old tool list.
  • Check with a real request, such as "Show me the site info". Asking the AI to list its tools is not a reliable check: with many tools, some apps load only the ones a chat needs.

Updating never resets your license, settings, API keys or the Pro tool switches on Smart MCP > Connect. If a tool still answers that it is not available after these steps, tell us the exact message on the contact page or our AI assistant and we will look right away.

FAQ

Frequently asked questions

Quick answers about Smart MCP.

Which AI providers are supported?

OpenAI, Anthropic (Claude), Google Gemini, OpenRouter and any OpenAI-compatible endpoint.

Which MCP clients can connect?

Any client that supports the Model Context Protocol, for example Claude Desktop, Claude Code, ChatGPT, Cursor and VS Code.

Do you store my AI provider API key on your servers?

No. Your AI provider key is saved in your own WordPress database, encrypted with sodium using a key derived from your site's secret salts. It never reaches WP Smarto. Your site sends it only to the AI provider you chose, and the plugin never shows it again in full.

Is it safe?

Every tool requires the right WordPress capability, and actions that need approval must be approved before they run. API keys are encrypted at rest and every action is recorded in the Audit Log.

Will it work with a custom login page or a security plugin?

Yes. AI apps connect through the WordPress REST API, not wp-login.php or wp-admin, and browser sign-in follows your custom login address. If a security plugin or firewall blocks the REST API, allow /wp-json/smart-mcp/ in it. The site check on Smart MCP > Connect tells you when something is blocked.

Can I chat from Telegram?

Yes. Set up a bot on the Telegram Bot page.

Can I undo what the AI did?

Yes. Ask it to undo and every post and page it changed in that conversation goes back, including Elementor designs. Posts it created move to the trash.

Which AI model should I use?

Each provider starts with a recommended model that is fast, low cost and good with tools: GPT-5.4 mini (OpenAI), Claude Sonnet 4.6 (Anthropic), Gemini 3.7 Flash (Google) and ~deepseek/deepseek-v4-flash-latest (OpenRouter). The model field on AI Providers is searchable and marks it Recommended.

Can it add internal links?

Yes. New blog posts are linked to related content automatically, and you can ask for links or a link check on any post. Choose where links are allowed in Settings > Links in content.

Does it work on multisite?

Not yet. Multisite support is planned.

Is there a Pro version?

Yes. Smart MCP Pro is an optional add-on with more tools for running and maintaining the whole site. Nothing in the free plugin is locked, and it works the same with or without Pro.

Where does my data go?

Chat messages, tool definitions and tool results go to the AI provider you selected. Telegram messages go through api.telegram.org if you enable the bot. Plugin and theme searches use api.wordpress.org and send only the slug. Image searches use api.openverse.org (run by WordPress.org), or the Pixabay API if you saved a Pixabay key, and send only the search words. AI apps connect directly to your site, with no relay server in between.

Still stuck?

Ask our assistant, it knows these docs. If it cannot solve it, it passes your question to the team, who reply by email.

Contact the team