Cybersalt MCP for Joomla

Cybersalt MCP for Joomla lets an AI app work on your Joomla site directly. You connect ChatGPT, Claude, Codex, Cursor, VS Code with GitHub Copilot, Gemini CLI or any other app that speaks MCP (the Model Context Protocol), and it can then read and manage your articles, categories, menus, modules, users, custom fields, templates, extensions and Schema.org data, using the same permissions as the Joomla account it acts for.

The site itself is the MCP server. There's nothing to install on your computer and no service in between: the app talks to your site's own address.

⤢ Click to enlarge

What's in the package

One package installs four parts, and the installer enables all of them.

Installing

1. Download the package zip (pkg_csmcpforj_v*.zip) from cybersalt.com.
2. In your Joomla admin go to System → Install → Extensions and upload the zip.
3. Open Components → MCP for Joomla.

The package registers Cybersalt's update server, so new versions show up under System → Update → Extensions. Updating keeps your settings.

On cPanel and other PHP-FPM hosts the web server drops the Authorization header before Joomla sees it. To stop that, the installer adds a three-line rule to api/.htaccess. Uninstalling removes it again.

Connecting an AI app

Copy your site's Endpoint URL from the Dashboard's Connection details card. It ends in /api/index.php/v1/mcp. It's an address for AI apps, not a web page to open. Then pick one of the three ways on the Connect an AI app to this site card.

1. Log in (easiest)

With OAuth sign-in switched on, an AI app connects the way you'd sign in to any website. You paste the Endpoint URL into the app, it opens your site's normal login page, you log in and click Allow. You never copy a key, and your site's two-factor authentication applies. Some apps, including ChatGPT and claude.ai, can only connect this way.

A Super User switches it on in Options → OAuth sign-in. The Dashboard then shows a Ready check and lists every connected app, each with a Disconnect button. Switching OAuth off disconnects them all at once.

⤢ Click to enlarge

2. Paste a setup prompt

For AI apps that can run commands: Codex, Claude Code, Cursor, Cline, Copilot agent mode and similar. Click Get my API token, paste the token into the field on the Dashboard, click Copy the prompt and paste it into a new conversation. The AI tests the connection itself and offers to save it. This doesn't work in web-only chats such as claude.ai or chatgpt.com.

3. Config file or command line

For apps you set up once in a settings file. Paste your token, click Copy the configuration, and paste it into the app's MCP settings. The copied configuration looks like this:

{
  "mcpServers": {
    "joomla-yoursite": {
      "type": "http",
      "url": "https://yoursite.com/api/index.php/v1/mcp",
      "headers": { "Authorization": "Bearer YOUR_JOOMLA_API_TOKEN" }
    }
  }
}

If an app can't send an Authorization header, use "X-Joomla-Token": "YOUR_JOOMLA_API_TOKEN" instead. The Setup Guide has step-by-step instructions for Codex, Claude Desktop, Claude Code, Cursor and Gemini CLI. Claude Desktop on Windows needs a small wrapper file, which the guide creates for you.

⤢ Click to enlarge

Getting an API token

Each Joomla user has their own token. Open your profile (the Dashboard's Open my API token link takes you there), go to the Joomla API Token tab, click Reset, then the eye icon, and copy the whole value. Treat it like a password: whoever has it can do everything that user can do. Clicking Reset again makes the old token stop working immediately.

Who can use it

Every tool call runs as the Joomla user who owns the token (or who logged in). MCP for Joomla never lets an AI do something that user couldn't do in the Joomla admin. Two separate permissions decide who gets in:

• Web Services Login is Joomla's own switch for its whole API. Only Super Users have it by default. Grant it to a group in System → Global Configuration → Permissions, on the group.
• Use MCP endpoint allows the read tools, and Write through MCP endpoint allows the tools that change things. Set them in Components → MCP for Joomla → Options → Permissions. A group that can manage the component passes both.

Read-only connections

Options → MCP server → Read-only mode makes the endpoint offer and accept only tools that read: the ones whose names start with list_, get_, read_, check_, validate_ or fetch_, plus joomla_update_healthcheck. An app can also add ?read_only=1 to the endpoint address to make one connection read-only, but it can't switch writes back on for a site set to read-only. To limit a connection to some tool groups, add ?categories=articles,menus (group names are listed below).

The tools

The 93 built-in tools are grouped below. Every tool describes itself to the AI app (its inputs and whether it reads, changes or deletes), so the app discovers them on its own. The full list with a line on each is in the README.

Add-ons

Browse MCP Add-ons lists optional add-ons that give the AI tools for specific third-party extensions, such as AcyMailing, Akeeba Backup, Akeeba Ticket System, Community Builder, Convert Forms, DPCalendar, J2Commerce, JCE, Maximenu CK, Page Builder CK and VirtueMart. Each one is a separate plugin, so you install only what you use. You need the third-party extension itself, from its own vendor; the add-ons are built independently by Cybersalt.

• Free add-ons install with one click.
• Pro add-ons, for commercial extensions, are sold separately at cybersalt.com. Link your Cybersalt account once on the Dashboard and they install and update from the same screen.

⤢ Click to enlarge

Activity log

Components → MCP for Joomla → Logs shows what MCP for Joomla did: each app that connected, every tool call with its arguments and how long it took, anything that was refused and why, and every step of an OAuth sign-in. You can filter by status, source, event, time, user or request, sort, search, and download the log as CSV.

⤢ Click to enlarge

Entries are kept for 30 days by default (Options → Logging), and never more than the newest 20,000. API tokens, sign-in codes, client secrets and password-like arguments are never written to the log.

Options

Safety features

• When an app connects, the site tells it to treat everything it reads as untrusted, never to follow instructions found inside your content, and to ask before changing anything.
• Deletes go to the trash by default. Permanently deleting an article or module only works once it's in the trash. Deleting a custom field and applying a Joomla update need an explicit confirmation.
• Template file tools can only reach the template's own media folder and can't write PHP.
• The page-fetching tool only fetches pages from your own site.
• A tool call that contains the connection's own token is refused, because that's a common sign of a prompt-injection attempt.
• If one add-on breaks, only its tools are dropped; everything else keeps working, and the Logs name the add-on.

Troubleshooting

Uninstalling

Uninstall the Cybersalt MCP for Joomla package in System → Manage → Extensions. That removes all four parts, the OAuth and log tables, and the api/.htaccess rule. Add-ons are separate extensions; uninstall them on their own.

Getting help

Use the Support screen inside the extension (it attaches your versions and, if you like, recent warnings from the log), the Cybersalt support form, or GitHub.

Cybersalt MCP for Joomla is developed by Cybersalt Consulting Ltd. and released under the GNU General Public License v2 or later. It's an independent, clean-room implementation of the Model Context Protocol for Joomla.