MCP integration

The module provides a protected read-only channel between AVE.cms and an MCP client. It cannot change documents, settings, or files.

Available now

inspect a public page by URL or document ID;
read fields and their actual values;
inspect the template, block, navigation, and module component chain;
diagnose missing templates, required fields, and broken references;
explain why a document is included in or excluded from a saved request;
retrieve machine-readable contracts and input schemas.

The module includes a separate Streamable HTTP transport. It converts MCP calls to protected JSON bridge requests without direct database, configuration, or filesystem access. It supports MCP 2026-07-28 and stateless 2025 clients.

Setup and permissions

Install and enable MCP integration under Modules.
Grant module view or management access under Roles and permissions.
Open Modules → MCP integration.
Create a separate connection for one client.
Copy the secret token. It is shown only once.

Only a SHA-256 token hash is stored. A connection can be revoked immediately. Uninstalling the module removes its connection tokens.

Both token scopes and user permissions are required:

scopes content.read and structure.read;
user permissions view_documents and view_public_site;
the module must be installed and enabled.

Starting the MCP endpoint

The transport requires Node.js 20 or newer. The module page shows a ready-to-use command:

AVE_MCP_SITE_URL=https://example.org \
node modules/mcp/transport/dist/server.mjs

By default it listens on 127.0.0.1:3090 and exposes:

http://127.0.0.1:3090/mcp

Publish remote access through an HTTPS reverse proxy instead of exposing the Node.js port directly. Add the public hostname to the allowlists:

AVE_MCP_SITE_URL=https://example.org \
AVE_MCP_ALLOWED_HOSTS=mcp.example.org \
AVE_MCP_ALLOWED_ORIGINS=mcp.example.org \
node modules/mcp/transport/dist/server.mjs

After a connection is created, the panel shows client JSON containing the URL and Authorization header. AVE.cms validates the token and its owner on every bridge call.

Tools and resource

The first version intentionally exposes a small surface:

diagnose.page explains which documents, fields, templates, blocks, navigation entries, and modules compose a public page;
requests.explain explains why a document matches or does not match a saved request;
ave://introspection/contracts describes the available read-only contracts.

Both tools are declared read-only, non-destructive, and idempotent. Save, publish, SQL, PHP, shell, and filesystem operations are not registered.

Routes

All responses are marked read-only and contain a request_id.

GET /api/internal/v1/introspection/contracts
GET /api/internal/v1/introspection/page?target=/news/example
GET /api/internal/v1/introspection/request?request_id=2&document_id=42

Public page parameters can be provided as a query string or a JSON object.

curl -H "Authorization: Bearer <token>" \
  "https://example.org/api/internal/v1/introspection/page?target=/news/example"

An external trace identifier can be provided through X-Request-ID.

Security limits

GET only;
60 requests per minute per connection;
1 MB maximum response;
up to 50 page parameters and 10 KB input;
a browser-supplied Origin must match the site;
sensitive fields are redacted before the response is built;
template source, SQL, stack traces, and absolute paths are not returned;
PHP, arbitrary SQL, shell, and filesystem tools are not exposed.

Audit

Actual tool calls are visible under System → Events. The audit entry stores the connection, tool, outcome, duration, and request ID. It does not store the token, document contents, or the full inspected URL.

3.8 KiB Raw Blame History