evoMCP reference

Endpoint and protocol

HTTP codes you may see:

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.

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:

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)

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)

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.

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".

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.

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.

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:

.., 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.

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:

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

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.