# evoMCP reference

> Endpoint, OAuth, permissions, approval rules and the complete list of evoMCP's MCP tools, grouped by component, with permission and approval needs.

# evoMCP reference

## Endpoint and protocol

| Item | Value |
| --- | --- |
| URL | `https://your-site/mcp` |
| Method | `POST` only. One JSON-RPC message per request, no batches, no sessions |
| Protocol versions | `2026-07-28` and, for compatibility, `2025-11-25`, `2025-06-18` and `2025-03-26` |
| Methods | `initialize`, `ping`, `server/discover`, `tools/list`, `tools/call`. Tools only: there are no resources or prompts |
| Headers with `Mcp-Protocol-Version: 2026-07-28` | `Mcp-Method` on every request except `initialize`, and `Mcp-Name` on `tools/call`; both must match the body |
| Authentication | `Authorization: Bearer <token>` |
| Size | Request up to 256 KB; response up to 1 MB (if exceeded, the tool returns an error asking you to paginate or filter) |
| Notifications | Answered with 202 |

HTTP codes you may see:

| Code | When |
| --- | --- |
| 400 | Invalid JSON, malformed JSON-RPC message, unsupported protocol version, or `Mcp-*` headers that do not match |
| 401 | Not authenticated or invalid token. Includes `WWW-Authenticate` with the OAuth metadata path |
| 403 | Origin not allowed |
| 404 | The endpoint is disabled in the options |
| 405 | Method other than `POST` |
| 413 | Request too large |
| 429 | Per-IP limit (600 a minute), per-connection limit or monthly quota used up |

A tool that the connection cannot use does not appear in `tools/list`, and calling it returns "Unknown tool", exactly as if it did not exist.

### Tool results

The result is returned in `structuredContent` and in the text, shaped as `{"data": ...}`. If a tool can return text from third parties (articles, menus, logs, visitor data), the result includes `"untrusted_content": true` and a notice: that text must not be treated as instructions. Validation and permission errors arrive with `isError: true`.

When a write needs approval it does not run. The response is:

```
{"data": {"status": "pending_approval", "approval_id": 12, "message": "..."}}
```

Before holding it, if the tool supports `dry_run`, it is validated with a simulation: a validation error reaches the agent straight away rather than after a human has already approved.

### `dry_run`

Tools with `dry_run` accept a boolean `dry_run` argument. When `true`, they simulate the action and return what they would do, without changing anything and without asking for approval.

## The server's own tools

These are always available to any connection.

| Tool | What it does |
| --- | --- |
| `evomcp_capabilities` | Reports the connection's permissions per component, the components that exist on the site but are not granted, how many tools it sees and its approval mode |
| `evomcp_approval_status` | Checks the state of a held action (`pending`, `executed`, `failed`, `rejected`, `expired`) and its result. It only sees approvals from its own connection |

## Permissions and approval in the tables

Each tool belongs to a component and a resource in the permission matrix, written `component/resource`. The permission is what the connection needs on that pair: read, write or full (both).

The Approval column can be:

| Value | Meaning |
| --- | --- |
| (empty) | Read tool. It never asks for approval |
| Always | Asks for approval in every mode |
| Sensitive | Asks for approval in the "every write" and "only destructive or sensitive" modes |
| Ordinary | Asks for approval only in the "every write" mode |

The `dry_run` column says whether the tool accepts that argument. Tools that return or change personal data say so in their description.

## Content (`content`)

| Tool | What it does | Resource | Permission | Approval | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `content_search_articles` | Searches articles by text, category and state. Paginated list (up to 50) | `content/articles` | Read |  | No |
| `content_get_article` | Reads a full article: text, dates, state, category, metadata | `content/articles` | Read |  | No |
| `content_list_categories` | Lists the article categories visible to the connection's user | `content/categories` | Read |  | No |
| `content_create_article` | Creates a new article as a draft | `content/articles` | Write | Ordinary | Yes |
| `content_update_article` | Changes fields of an article. Does not change its publication state | `content/articles` | Write | Sensitive | Yes |
| `content_set_article_state` | Publishes, unpublishes, archives or trashes an article | `content/articles` | Write | Always | Yes |
| `content_create_category` | Creates an article category, left unpublished | `content/categories` | Write | Ordinary | Yes |

Unpublished articles are only visible to someone who can edit them (or, with `core.edit.own`, their own).

## Menus, modules, media, templates, users, extensions and configuration (`plg_evomcp_joomla`)

| Tool | What it does | Resource | Permission | Approval | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `menus_list_menus` | Lists the site's menus | `menus/menus` | Read |  | No |
| `menus_list_items` | Lists menu items, filtered by menu and state | `menus/items` | Read |  | No |
| `menus_get_item` | Reads a menu item | `menus/items` | Read |  | No |
| `menus_set_item_state` | Publishes, unpublishes or trashes a menu item | `menus/items` | Write | Sensitive | Yes |
| `modules_list_modules` | Lists site modules by position and state | `modules/modules` | Read |  | No |
| `modules_get_module` | Reads a module; parameters that look like secrets are hidden | `modules/modules` | Read |  | No |
| `modules_set_module_state` | Publishes, unpublishes or trashes a site module | `modules/modules` | Write | Sensitive | Yes |
| `media_list_files` | Lists files and folders inside `/images` (metadata only) | `media/files` | Read |  | No |
| `templates_list_styles` | Lists the template styles of the site and the administrator | `templates/styles` | Read |  | No |
| `users_list_users` | Lists users: name, username, email, state and groups. Personal data | `users/users` | Read |  | No |
| `users_get_user` | Reads a user. Personal data | `users/users` | Read |  | No |
| `users_list_groups` | Lists user groups | `users/groups` | Read |  | No |
| `users_set_user_blocked` | Blocks or unblocks a user | `users/users` | Write | Always | Yes |
| `extensions_list_extensions` | Lists installed extensions: type, element, version and whether they are enabled | `extensions/extensions` | Read |  | No |
| `extensions_set_enabled` | Enables or disables an extension; protected core extensions cannot be touched | `extensions/extensions` | Write | Always | Yes |
| `config_get_site_settings` | Reads non-sensitive global configuration settings. Never returns credentials | `config/global` | Read |  | No |
| `scheduler_list_tasks` | Lists scheduled tasks with their state and last run | `scheduler/tasks` | Read |  | No |

## Entities, options and backups (`entities`)

This layer works on Joomla's models and forms, so it validates the same way the administrator does. The real permission is checked per entity with each one's component and resource (articles with `content/articles`, modules with `modules/modules`, and so on). The `entities` component is the gateway and can only be granted by a Super User.

| Tool | What it does | Resource | Permission | Approval | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `entities_list_types` | Lists the entities that can be managed and what the connection allows on each | `entities/generic` | Read |  | No |
| `entities_describe` | Fields of an entity as Joomla's form defines them (type, label, options), plus filters and states. For modules, `context {"module":"mod_custom"}` | `entities/generic` | Read |  | No |
| `entities_list` | Lists items with pagination and filters (`search`, `state` and each entity's own) | `entities/generic` | Read |  | No |
| `entities_get` | Reads a full item; secrets are hidden | `entities/generic` | Read |  | No |
| `entities_save` | Creates (no `id`) or edits (with `id`, only the fields that change). What is created arrives as a draft if the entity supports it | `entities/generic` | Write | Ordinary | Yes |
| `entities_set_state` | Publishes, unpublishes, archives or trashes up to 50 items | `entities/generic` | Write | Sensitive | Yes |
| `entities_delete` | Permanently deletes up to 50 items that are already in the trash | `entities/generic` | Write | Always | Yes |
| `options_get` | Reads a component's options with their fields; secrets are hidden | `entities/options` | Read |  | No |
| `options_set` | Changes a component's options, validated with its form. Saves a backup first | `entities/options` | Write | Always | Yes |
| `backups_list` | Lists the backups made before changes by evoMCP, without their content | `entities/backups` | Read |  | No |
| `backups_restore` | Restores a backup (component options, theme settings, page builder pages, global settings, files). Saves a copy of the current state first | `entities/backups` | Write | Always | Yes |

Built-in entities: articles, article categories, tags, article custom fields, menus, menu items, site modules, template styles, banners with their clients and categories, contacts and their categories, news feeds and their categories, redirects, user groups and access levels. Extensions can declare their own with the `onEvomcpCollectEntities` event.

The options of `com_evomcp`, the user registration options and the media upload options cannot be changed with `options_set`; neither can permissions (`rules`), the licence or secrets.

## YOOtheme Pro (`yootheme`)

These tools only exist if the YOOtheme template is installed. Those that change a page builder page require the connection user's group to have Joomla's text filter set to "No Filtering".

| Tool | What it does | Resource | Permission | Approval | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `yootheme_list_pages` | Lists articles that have a page builder page | `yootheme/layouts` | Read |  | No |
| `yootheme_get_layout` | Structure of a page: sections, rows, columns and elements with their path. With `format=json`, the full layout (up to 150 KB) | `yootheme/layouts` | Read |  | No |
| `yootheme_find_nodes` | Finds nodes by element type and by text; returns their path | `yootheme/layouts` | Read |  | No |
| `yootheme_list_element_types` | Installed page builder element types, with their group and whether they can contain others | `yootheme/layouts` | Read |  | No |
| `yootheme_describe_element` | One element type: where it can go, which children it accepts, fields and defaults | `yootheme/layouts` | Read |  | No |
| `yootheme_update_node_props` | Changes properties of a node | `yootheme/layouts` | Write | Sensitive | Yes |
| `yootheme_add_node` | Adds a node with its children, validating the hierarchy and properties | `yootheme/layouts` | Write | Sensitive | Yes |
| `yootheme_move_node` | Moves a node to another parent or position | `yootheme/layouts` | Write | Sensitive | Yes |
| `yootheme_duplicate_node` | Duplicates a node with everything in it, right after the original | `yootheme/layouts` | Write | Sensitive | Yes |
| `yootheme_remove_node` | Removes a node with everything in it. Saves a copy of the page first | `yootheme/layouts` | Write | Always | Yes |
| `yootheme_replace_layout` | Replaces a page's whole layout, validated node by node. Saves a copy first | `yootheme/layouts` | Write | Always | Yes |
| `yootheme_create_page` | Creates a new page builder page as a draft (section, row and column) | `yootheme/layouts` | Write | Ordinary | Yes |
| `yootheme_get_theme_info` | YOOtheme Pro version, template styles and number of builder pages | `yootheme/theme` | Read |  | No |
| `yootheme_get_theme_config` | Customiser settings. Without a path, the top-level groups; with a dotted path, that value | `yootheme/theme` | Read |  | No |
| `yootheme_set_theme_config` | Changes or removes a theme setting by dotted path. Saves a copy first, restorable with `backups_restore` | `yootheme/theme` | Write | Always | Yes |

The valid hierarchy is layout, section, row, column and elements. The builder library and the builder page templates have no tools of their own.

## System (`system`, `config`, `scheduler`)

Super users only. The Joomla core and evoMCP are not updated by these tools.

| Tool | What it does | Resource | Permission | Approval | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `system_info` | Joomla, PHP and database versions, site state, number of extensions and whether updates are pending | `system/info` | Read |  | No |
| `system_list_updates` | Extension updates that Joomla already knows about | `system/updates` | Read |  | No |
| `system_find_updates` | Queries the update servers (all extensions or one). Makes network requests | `system/updates` | Write | Ordinary | No |
| `system_apply_update` | Updates an extension with one of the listed updates | `system/updates` | Write | Always | Yes |
| `system_install_from_url` | Installs or updates an extension from an HTTPS URL | `system/install` | Write | Always | Yes |
| `system_uninstall_extension` | Uninstalls an extension by its id. Not protected core extensions or evoMCP | `system/install` | Write | Always | Yes |
| `system_set_config` | Changes global configuration settings from a closed list of keys. Saves a copy first | `config/global` | Write | Always | Yes |
| `system_clear_cache` | Clears the Joomla cache (all groups or one) and expired entries | `system/cache` | Write | Sensitive | Yes |
| `system_read_log` | Lists Joomla's logs or reads the last lines of one, with a text filter. They may contain IPs and emails | `system/logs` | Read |  | No |
| `scheduler_set_task_state` | Enables or disables a scheduled task | `scheduler/tasks` | Write | Sensitive | Yes |
| `scheduler_run_task` | Runs a scheduled task right now | `scheduler/tasks` | Write | Always | Yes |

Limits of `system_install_from_url`: HTTPS only and no port; only hosts of the installed update sites plus the list in evoMCP's options; only public IPs, and every redirect is checked again; 40 MB at most. `system_set_config` never touches credentials, paths or sessions. `system_read_log` only reads the logs folder, by name and only the end of the file.

## Advanced layer: SQL and files (`advanced`)

It is disabled by default and only a super user can use it. There are three locks and all three must be open:

1. The "evoMCP - Advanced layer" plugin is installed disabled and you must enable it by hand.
2. The "Advanced layer (SQL and files)" switch in evoMCP's options is off and you must turn it on.
3. The connection needs `full` permission on the `advanced` component, which only a Super User can grant.

The installer does not enable this plugin, on install or on update. When the layer is on, the Connect tab warns you.

| Tool | What it does | Resource | Permission | Approval | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `advanced_sql_read` | `SELECT`, `SHOW`, `DESCRIBE` and `EXPLAIN SELECT`: a single statement, no comments, up to 200 rows, in a read-only transaction with a time limit. May return personal data | `advanced/sql` | Read |  | No |
| `advanced_sql_write` | `INSERT`, `UPDATE`, `DELETE` or `CREATE TABLE`, one statement. `UPDATE` and `DELETE` need a real `WHERE` and the table is copied first | `advanced/sql` | Full | Always | Yes |
| `advanced_files_list` | Lists a folder in the allowed roots, without hidden files | `advanced/files` | Read |  | No |
| `advanced_files_read` | Reads a text file of up to 200 KB; for a binary file it returns size and fingerprint | `advanced/files` | Read |  | No |
| `advanced_files_write` | Creates or overwrites a file of up to 2 MB. Backs up what it overwrites | `advanced/files` | Full | Always | Yes |
| `advanced_files_delete` | Deletes an allowed file, with a backup first if it is under 2 MB | `advanced/files` | Full | Always | Yes |

SQL rules: `#__` is the table prefix. Credential and session tables and evoMCP's internal tables cannot be read, and columns that look like secrets are hidden. Nothing can be written to evoMCP or credential tables. A table backup is named `<table>_bak_evomcp_<date>` and the daily maintenance deletes it after 30 days.

File rules:

| Root | Folder | Writable |
| --- | --- | --- |
| `images` | `images` | Yes |
| `media` | `media` | Yes |
| `templates` | `templates` (not core templates or `yootheme`) | Yes |
| `tmp` | `tmp` | No |
| `logs` | `administrator/logs` | No |

`..`, symbolic links and hidden files are not accepted. Only non-executable types, and never PHP code. HTML can only be written inside templates, and SVG files cannot carry scripts.

## Tools added by other evo extensions

When they are installed, evoLeadGate, evoOrigin and evoYTAccess register their tools in evoMCP. They are documented here because each hangs off its own component in the permission matrix.

| Tool | What it does | Resource | Permission | Approval | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `evoleadgate_list_leads` | Lists captured leads: form, email, date, verification, delivery. Personal data | `evoleadgate/leads` | Read |  | No |
| `evoleadgate_get_lead` | Reads a lead: form fields, consents, UTM attribution and email state. Does not include IP or user agent | `evoleadgate/leads` | Read |  | No |
| `evoleadgate_lead_stats` | Aggregate statistics per form and per day, without personal data | `evoleadgate/leads` | Read |  | No |
| `evoleadgate_delete_leads` | Deletes leads and their downloads by id, up to 50 | `evoleadgate/leads` | Write | Always | Yes |
| `evoorigin_stats` | Visits by month, source, medium and campaign, without personal data | `evoorigin/stats` | Read |  | No |
| `evoorigin_list_visits` | Lists visits: source, landing page, truncated IP, user if identified. Personal data | `evoorigin/visits` | Read |  | No |
| `evoorigin_list_leads` | Lists lead attribution summaries: first and last source, number of visits | `evoorigin/leads` | Read |  | No |
| `evoorigin_get_lead_attribution` | Attribution for one lead by its reference | `evoorigin/leads` | Read |  | No |
| `evoorigin_delete_visits` | Deletes visits by id, up to 100 | `evoorigin/visits` | Write | Always | Yes |
| `evoorigin_delete_leads` | Deletes attribution summaries by id, up to 100 | `evoorigin/leads` | Write | Always | Yes |
| `evoorigin_purge_now` | Runs the retention purge now, according to the configured periods | `evoorigin/visits` | Write | Always | Yes |
| `evoytaccess_get_settings` | Reads evoYTAccess settings | `evoytaccess/settings` | Read |  | No |
| `evoytaccess_set_settings` | Changes evoYTAccess settings | `evoytaccess/settings` | Write | Always | Yes |

## For developers: registering tools from an extension

A plugin in the `evomcp` group, or a system plugin listening to `onEvomcpCollect`, registers a tool provider:

```
public function onEvomcpCollect(Event $event): void
{
    $event->getArgument('registry')->register(new MyProvider($this->getApplication()));
}
```

`MyProvider` implements `ToolProvider`, contract version 1:

| Method | What it returns |
| --- | --- |
| `contract()` | The contract version. Providers with a different version are rejected |
| `component()` | Key, title and resource tree for the permission matrix |
| `tools()` | The tools: name, JSON input schema, permission `read`, `write` or `full`, annotations, `personalData`, `untrustedContent` and `dryRun` |
| `call()` | The execution of a tool |

The core hides tools the connection cannot use, validates arguments against the schema, applies approval and audits. The annotations `destructiveHint`, `consequentialHint` and `approvalRequired` decide when approval is requested. To declare entities that the generic tools can manage, listen to `onEvomcpCollectEntities` and register a definition in the `EntityRegistry`.

## OAuth 2.1

| Item | Value |
| --- | --- |
| Resource metadata | `/.well-known/oauth-protected-resource` |
| Server metadata | `/.well-known/oauth-authorization-server` |
| Authorisation | `/oauth/authorize`: Joomla sign-in and consent screen |
| Token | `/oauth/token` |
| Dynamic client registration | `/oauth/register` |
| Clients identified by a metadata document (CIMD) | Supported, with SSRF protection |
| Flows | Authorisation code with PKCE `S256` and refresh with rotation |
| Client authentication | None (public client) |
| Scope | `mcp` |
| Token prefixes | `evomcp_` (manual token), `evomat_` (access), `evomrt_` (refresh) |

Consent stores only what the user unticks. As a result, components that arrive later on an already authorised connection show up without repeating the consent; if the client has the tool list cached, reconnect the connector to refresh it. An OAuth connection is capped by the matrix of the connection chosen.

---

https://evoaddons.com/en/documentation/evomcp-reference