Configure MCP for PagibleAI

PagibleAI CMS provides an MCP server with tools for managing pages, shared content elements, media files, and AI-powered content operations. Any MCP-compatible client (ChatGPT, Claude, Codex, VS Code Copilot, etc.) can connect and manage your CMS content.

With the MCP server, you can ask your AI assistant to create new pages, update existing content, upload and manage media files, reorganize your site structure, translate content into other languages, and refine text — all through natural language conversation. No need to open the admin panel for routine content tasks.

Key Concepts

Draft/Publish workflow: Creating or updating pages, elements, and files always produces a draft version first. Nothing goes live until you explicitly use the publish-* tools. This gives you a chance to review changes before they are visible to visitors. Scheduled publishing is supported via the at parameter (ISO 8601 datetime), e.g. to publish a blog post at a specific date and time.

Permissions: Each tool requires a specific permission (e.g. page:view, page:add, file:publish). Permissions are controlled by the cmsperms JSON column on the User model. Assign roles like admin, publisher, editor, or viewer to control what each user can do via MCP.

Multi-tenancy: All operations are scoped to the authenticated user's tenant. Content from other tenants is never visible or modifiable, ensuring complete data isolation between tenants.

Version history: Every change creates a new version. You can retrieve past versions with get-page-history and restore any previous state. This means you can safely experiment — nothing is permanently lost until a page is force-deleted.

Content structure: Page content is an ordered array of typed elements (heading, text, image, code, etc.). Use get-schemas to discover available element types and their fields. Each element belongs to a layout group (typically main) and has a unique ID that is preserved across updates.

Server Setup

Setting up the MCP server requires three steps: installing authentication UI, configuring OAuth for secure API access, and registering the MCP routes. You will need shell access to your Laravel application and composer installed.

Laravel Breeze for authentication

Laravel Breeze provides the login and registration pages needed for the OAuth authorization flow. When an MCP client connects, the user is redirected to your application's login page to grant access.

composer require laravel/breeze
php artisan breeze:install blade --dark

Important: CSS/JS builds are not added to Git by default when using version control. Use:

git add -f ./public/build/

OAuth with Laravel Passport

MCP clients authenticate via OAuth 2.0. Laravel Passport handles token issuance and validation, so each MCP session runs with the permissions of the authenticated user.

php artisan install:api --passport

Update User model

Update ./app/Models/User.php to implement the OAuthenticatable interface and add the HasApiTokens trait:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable implements OAuthenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

Add API guard

In ./config/auth.php, add a api guard that uses the Passport driver. This tells Laravel to validate API requests using OAuth tokens:

'guards' => [
        'web' => [
            'driver' => 'session',
            'provider' => 'users',
        ],
        'api' => [
            'driver' => 'passport',
            'provider' => 'users',
        ],
    ],

Add Passport keys

Passport uses RSA key pairs to sign and verify OAuth tokens. Generate the keys and then add them to your environment:

php artisan passport:keys

Add the generated keys to your .env file:

PASSPORT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
<private key here>
-----END RSA PRIVATE KEY-----"

PASSPORT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
<public key here>
-----END PUBLIC KEY-----"

For Kubernetes deployments, store the keys as secrets rather than in environment files directly:

kubectl create secret generic pagible-oauth-private --from-file=oauth-private=storage/oauth-private.key -n <namespace>
kubectl create secret generic pagible-oauth-public --from-file=oauth-public=storage/oauth-public.key -n <namespace>

Reference the secrets in your Kubernetes deployment YAML:

- name: PASSPORT_PRIVATE_KEY
          valueFrom:
            secretKeyRef:
              name: pagible-dev-oauth-private
              key: oauth-private
        - name: PASSPORT_PUBLIC_KEY
          valueFrom:
            secretKeyRef:
              name: pagible-dev-oauth-public
              key: oauth-public

Install Laravel MCP

Publish the MCP server configuration and register the CMS routes. The MCP endpoint is protected by both OAuth authentication and rate limiting.

php artisan vendor:publish --provider=Laravel\\Mcp\\Server\\McpServiceProvider

In ./routes/ai.php, register the OAuth routes and the MCP endpoint:

Mcp::oauthRoutes();
Mcp::web('/mcp/cms', \Aimeos\Cms\Mcp\CmsServer::class)->middleware(['auth:api', 'throttle:cms-admin']);

Publish the MCP authorization view so Passport can display the OAuth consent screen:

php artisan vendor:publish --tag=mcp-views

In ./app/Providers/AppServiceProvider.php, tell Passport to use the published MCP authorization view:

use Laravel\Passport\Passport;

public function boot(): void
{
    Passport::authorizationView(function ($parameters) {
        return view('mcp.authorize', $parameters);
    });
}

Client Configuration

Once the server is set up, connect your preferred AI client. The MCP server URL follows the pattern https://yourdomain.com/mcp/cms/. Replace with your actual domain. On first connection, you will be redirected to your application's login page to authorize access.

ChatGPT

In ChatGPT, go to Settings → Apps → Create. Enter a name (e.g. "Pagible") and paste the MCP server URL. Available on Pro, Team, Enterprise, and Edu plans.

Claude.ai

In Claude.ai, go to Settings → Connectors → Add custom connector. Paste the MCP server URL and complete the OAuth flow. Available on Free (1 connector), Pro, Max, Team, and Enterprise plans.

Claude Code (CLI)

Add the MCP server with a single command. The --scope user flag makes it available across all your projects:

claude mcp add --transport http --scope user pagible https://example.com/mcp/cms/

Claude Desktop

Add the server to claude_desktop_config.json. The file is located at ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows:

{
  "mcpServers": {
    "pagible": {
      "type": "http",
      "url": "https://example.com/mcp/cms/"
    }
  }
}

OpenAI Codex CLI

Add the server in ~/.codex/config.toml (global) or .codex/config.toml (project-scoped):

[mcp_servers.pagible]
url = "https://example.com/mcp/cms/"

Then authenticate via OAuth:

codex mcp login pagible

VS Code / GitHub Copilot

Create a .vscode/mcp.json file in your project root. VS Code will detect it automatically and the server becomes available in GitHub Copilot's agent mode:

{
  "servers": {
    "pagible": {
      "type": "http",
      "url": "https://example.com/mcp/cms/"
    }
  }
}

Available Tools

The MCP server exposes 30+ tools organized by resource type. You don't need to memorize these — your AI client will discover them automatically. This reference helps you understand what operations are possible.

Discovery

get-locales returns the available languages configured in your CMS. get-schemas returns the content element types (text, heading, image, code, etc.) and their field definitions — use this to understand what structures are valid when creating or updating page content.

Pages

search-pages finds pages by keyword, language, status, or type. get-page retrieves a single page with its full content. get-page-tree returns the hierarchical page structure. add-page creates a new page, save-page updates an existing one, publish-page makes a draft version live, drop-page soft-deletes a page, restore-page recovers it, and move-page repositions it in the tree. get-page-history shows past versions and get-page-metrics returns page analytics.

Shared Elements

Shared elements are reusable content blocks (e.g. a call-to-action or footer) that can appear on multiple pages. search-elements and get-element read them. add-element, save-element, publish-element, drop-element, and restore-element manage their lifecycle. When a shared element is updated and published, the change is reflected everywhere it is referenced.

Files

Files represent media assets — images, videos, audio, and documents. search-files and get-file retrieve them. add-file uploads a new file (provide a public URL and it will be downloaded and stored), save-file updates metadata, publish-file makes changes live, drop-file soft-deletes, and restore-file recovers.

AI-Powered Tools

When the pagible-ai package is installed, two additional tools become available: refine-content rewrites or improves text content using an LLM, and translate-content translates content into another language. These tools require an AI provider (OpenAI, Google Gemini, Mistral, etc.) to be configured.