SNiPI MCP Server for October CMS — Documentation

What this plugin does

This plugin turns an October CMS website into a Model Context Protocol (MCP) server. Once installed, an external AI agent — Claude, Cursor, or any MCP-capable client — can connect to the site over a single authenticated web endpoint and manage its content: create and edit pages, manage reusable content and theme assets, define and migrate Tailor content structures, work with the media library, create and duplicate themes, and administer backend users.

In short, it lets you point an AI agent at your site and say "build a landing page for the spring workshop" or "add a registrations content type and list this week's sign-ups," and the agent carries it out through well-defined tools rather than by touching the server directly.

The plugin is content-management-shaped: every capability maps to a real October concept (a CMS page, a Tailor blueprint, a theme, a media file), so the operations an agent can perform are the operations that make sense for a CMS.

How it works

The endpoint

The plugin registers one public route, POST /mcp, that speaks JSON-RPC 2.0 over HTTP — the "Streamable HTTP" transport that remote MCP clients use. The route is deliberately stateless: it sits outside October's web middleware group, so there is no session or CSRF handling, only bearer-token authentication and a request throttle. A GET /mcp returns 405, since this server is request/response only and does not push server-initiated messages.

The protocol layer

Incoming requests are handled by a small, self-contained MCP implementation (McpServer). It implements the handshake and the tools capability, which is all an agent needs to discover and call actions:

• initialize — returns the protocol version, capabilities, server info, and an instructions string that orients the agent (see below).
• tools/list — returns the catalog of available tools with their JSON-Schema input definitions.
• tools/call — runs a named tool with arguments and returns its result.
• ping and the standard notifications are handled as well.

Because the protocol layer is hand-written rather than dependent on a version-locked package, the plugin runs on both October v3 (Laravel 9/10) and October v4 (Laravel 12) without change. If richer MCP features are wanted later (resources, prompts, sessions), the protocol layer can be swapped for the php-mcp/server package without disturbing the tools.

Tools and the registry

Each capability is a Tool: a name, a description, a JSON-Schema for its arguments, and a handler. Tools are grouped into provider classes by domain (pages, content, themes, assets, Tailor, blueprints, site, media, backend users). On every request a ToolRegistry assembles the full set, filters it against the connecting client's permissions, and dispatches calls. Every tool call is wrapped so that an error becomes a readable message returned to the agent rather than a server crash.

Other plugins can contribute their own tools by listening to the snipi.mcp.registerTools event, so the surface can be extended without modifying this plugin.

Agent instructions

The initialize response includes an instructions string that most MCP clients feed to the model automatically. It describes the tool map and — importantly — the cross-tool workflows that individual tool descriptions cannot express: how to target a specific site's theme, the blueprint-then-migrate flow, the fact that the PHP code section may be gated, and the guidance to ask the user when information is missing. The code-section line is tailored per client, so a restricted token is told the code section is disabled for it while a trusted token is told it is accepted.

Installation

1. Copy the plugin to plugins/snipi/mcp in your October project.
2. Run migrations: php artisan october:up (the migrations are idempotent, so re-running is safe).
3. Issue a client token (see below).

The endpoint is then live at https://your-site.com/mcp.

Client tokens

Access is controlled by per-client bearer tokens. Only a SHA-256 hash of each token is stored, never the plaintext, so a token is shown exactly once at creation.

There are two ways to issue one:

• Backend: go to MCP → Clients → New Client, set a label and permissions, and save. The next screen reveals the token once, with a Copy button and a Download mcp.json button that produces a ready-to-use client config. Grab it there — it cannot be shown again.
• CLI: php artisan mcp:issue-token "My Agent" prints the token once. Add --tools=name (repeatable) to restrict it.

To revoke a token, disable or delete the client in the backend. A disabled client's token stops working immediately.

Permissions model

Two controls sit on each client, both reflecting the reality that writing to a CMS is powerful.

Allowed tools is a checkbox list, all-checked by default. Uncheck any tool to deny it for that client. Leaving everything checked (or a console token with no restriction) means full access; to switch a client off entirely, use the Enabled toggle rather than unchecking everything. For an agent you don't fully trust, leave only the list_* and get_* tools checked to make the token effectively read-only.

Allow PHP in templates is a switch, off by default. October CMS pages have a PHP code section that executes on the server, so a client that can write pages can, in principle, run arbitrary server-side code. While this switch is off, the page tools reject any code section. It is a meaningful mitigation, not a complete sandbox (Twig and components still have some reach), so turn it on only for a fully trusted client.

The practical takeaway: the real security boundary is read versus write, not which individual write tool is enabled. Treat any write-capable token like an administrator password.

Connecting an AI agent

Native MCP clients that support remote servers can point straight at the URL with an Authorization: Bearer <token> header. For clients that speak only the local transport, the mcp-remote bridge works:

{
  "mcpServers": {
    "october": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-site.com/mcp",
        "--header", "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

The Download mcp.json button in the backend produces exactly this file for the token you just created. After connecting, ask the agent to, for example, "list the CMS pages" or "create a page at /pricing with three plan cards."

Tool catalog

Orientation

CMS pages

Reusable content and theme templates

Themes

Theme assets

Tailor structured content

Media library

Backend users

Every theme-scoped tool (pages, content, layouts, partials, assets) accepts an optional theme argument — see below.

Multisite: which site do edits affect?

Theme-scoped tools act on a theme, and a theme is a directory, not a site. With no theme argument they use the theme the request's host resolves to, so on a multisite install an agent would otherwise only ever touch that one site's theme.

To target a specific site, the agent passes the optional theme argument — the theme's directory name. It maps a site to its theme with list_sites (each entry reports its theme) and enumerates theme directories with list_themes. If two sites share one theme, editing it changes both; duplicate_theme splits them, after which the copy is assigned to one site in the backend under Settings → Sites. Per-site theme assignment is left to the backend because how that mapping is stored varies across October versions.

Tailor: defining content structures

The typical flow for a new content type:

1. The agent writes a blueprint with upsert_blueprint, passing the full YAML. A uuid is generated and injected automatically if omitted, since Tailor tracks blueprints by uuid.
2. It applies the blueprint with migrate_blueprints (or passes migrate: true to upsert_blueprint to do both at once), which runs tailor:migrate to create or update the database tables.

Relations between content types use a field of type entries with a source of the related blueprint's handle — for example a Registration blueprint linking to a Workshop. Records are then queried and created with the *_tailor_entries tools using the blueprint handle.

Security summary

• Serve over HTTPS. Tokens travel in the Authorization header.
• Writing templates is effectively code execution. Scope untrusted clients to read-only tools, and keep "Allow PHP in templates" off unless fully trusted.
• Writing JS/CSS assets is a client-side risk. Scripts written to a theme run in your visitors' browsers, so an asset-writing token can inject site-wide code (stored XSS / defacement). Grant those tools only to trusted clients.
• Blueprint and delete tools can drop data. migrate_blueprints performs DDL; confirm destructive actions.
• create_backend_user grants admin access. Treat any token that can call it like an admin password.
• Turn off debug in production so error responses don't leak details to unauthenticated callers.

Extending the plugin

Add tools from any plugin by listening to the registration event:

Event::listen('snipi.mcp.registerTools', function ($registry) {
    $registry->add(new \SNiPI\Mcp\Classes\Tool(
        'publish_post',
        'Publish a blog post by id.',
        ['type' => 'object', 'properties' => ['id' => ['type' => 'integer']], 'required' => ['id']],
        function (array $args) {
            // ... your logic ...
            return \SNiPI\Mcp\Classes\Result::text("Published #{$args['id']}");
        }
    ));
});

New tools automatically appear in tools/list, are governed by the same per-client permission checkboxes, and show up in the backend's Allowed-tools list.

What to expect — and current limitations

The plugin gives an agent broad, honest control over a site's content, with a permission model that reflects the real risks. A few things are worth setting expectations on:

• Tailor file/image fields. create_tailor_entry fills scalar fields (text, numbers, dropdowns, relations). It cannot yet populate fileupload (image) fields — attaching images to an entry needs a dedicated step that is not yet built. So an agent can create, for example, a workshop registration with all its text and measurement data, but not push the photos through the API today.
• Per-site theme assignment is done in the backend, not via a tool, for the version-compatibility reason noted above.
• Client behaviour varies. Most MCP clients surface the server's instructions to the model and re-list tools on reconnect; a few ignore instructions (the per-tool descriptions still carry the essentials), and most need a full restart to pick up newly added tools.
• Environment-specific verification. A handful of operations depend on October APIs whose exact behaviour can differ slightly across versions (Tailor blueprint field types, media library calls, backend user role assignment). These are coded against the standard APIs and fail into readable error messages rather than crashes, so any mismatch is visible and fixable rather than silent.

Used within those bounds, the plugin lets a person manage an October CMS site conversationally through an AI agent, while keeping the site owner in control of exactly what each connected agent is allowed to do.