AI agents meet Drupal:
the MCP endpoint & the Tool API

Tutorial: Managing Multilingual Content & Revisions in Drupal via AI Agents and the Drupal MCP Endpoint

Based on the DrupalCon Keynote Demonstration featuring the Western Lakes University implementation.

Overview

In this showcase from DrupalCon, Drupal demonstrates direct integration with external AI agent platforms using a Drupal MCP (Model Context Protocol) endpoint.

This workflow allows content editors to delegate editorial and administrative tasks—such as auditing translations, inspecting revision diffs, and reverting content—using natural language inside everyday AI chat interfaces while preserving Drupal’s permission model, workflow states, and revision histories.

+---------------------------------------------------------------------------------+
|                                 AI INTERFACES                                   |
|  ChatGPT · Claude · Mistral · Gemini · OpenClaw · Copilot · Slack · Jira · etc. |
+---------------------------------------------------------------------------------+
                                      │
                                      ▼ [OAuth Authentication & Permissions]
+---------------------------------------------------------------------------------+
|                            DRUPAL MCP ENDPOINT                                  |
|   - Content Read / View Permissions                                             |
|   - Workflow-State Enforcement                                                  |
|   - Revision Access & Restoration Controls                                      |
+---------------------------------------------------------------------------------+
                                      │
                                      ▼
+---------------------------------------------------------------------------------+
|                               DRUPAL BACKEND                                    |
|   - Node Translations (English / Dutch)                                         |
|   - Granular Revision System (Full Audit Trail & Attribution)                   |
+---------------------------------------------------------------------------------+

Scenario: Premature Translation Release

The Problem

• Site: Western Lakes
• Content: Membership pricing pages
• Status:
  • English (Membership): Correctly displaying the active rate of €120.
  • Dutch (Lidmaatschap & Gezinslidmaatschap): Erroneously displaying next week’s upcoming rate of €180.
• Goal: Revert only the Dutch translation revisions back to the active rate (€120) without modifying or unpublishing the English source node.

Step 1: Connecting the AI Agent to the Drupal Site

Before issuing commands, the AI agent must authenticate against the Drupal site using the user's specific Drupal account credentials and roles.

1. Launch the Integration

Inside the AI workspace (e.g., ChatGPT running GPT-5.6 Sol Light), open the site tool:

• Tool: Western Lakes
• Description: Manage Western Lakes with your existing Drupal account and permissions.
• Click Try in chat.

  View source diagram

  +---------------------------------------------------------------+
  |  (☁) Western Lakes                                  [...]     |
  |      Manage Western Lakes with your existing                  |
  |      Drupal account and permissions.              [Try in chat]|
  +---------------------------------------------------------------+

2. Authenticate

A secure Drupal OAuth login prompt opens:

• Username: Maya
• Password: •••••••••••••••••••••
• Click Log in.

3. Grant Authorized Permissions

The authentication screen explicitly scopes what the AI model is permitted to do on behalf of the logged-in user:

+--------------------------------------------------------------------------------+
|  You are allowing 'ChatGPT' to:                                                |
|                                                                                |
|  • Read content your Drupal account may view                                   |
|  • View your own unpublished content when your Drupal account permits it       |
|  • Connect to this Drupal MCP endpoint                                         |
|  • Edit pricing pages your Drupal account may edit                             |
|  • Publish pricing pages through the configured workflow when your Drupal    |
|    account permits it                                                          |
|  • Restore pricing revisions your Drupal account may restore                   |
|  • View pricing revisions your Drupal account may view                         |
|                                                                                |
|                 [ Allow ]                     [ Deny ]                         |
+--------------------------------------------------------------------------------+

Click Allow to bind the session.

Step 2: Prompting the Agent

Once connected, prompt the agent with natural language instructions. You do not need to provide node IDs or database revision numbers; specify the intent and business constraints.

User Prompt

Western Lakes Next week's prices have gone live early on the Dutch membership pages. Can you restore the previous versions and leave English as it is?

Step 3: Agent Execution & Tool Invocation

The agent leverages the MCP connection to query node metadata, audit recent revision history, isolate language-specific changes, and invoke the reversion action.

Agent Execution Trace

Execution Log:
  Time Elapsed: 2m 2s
  
  Step 1: Planning
    "I'll locate the Dutch membership pages, compare their current and prior 
     revisions to identify the premature price update, then restore only those 
     Dutch translations. English will remain untouched."

  Step 2: MCP Tool Call - Metadata Inspection
    Action: Retrieved Western Lakes metadata and Dutch pricing revision details
    Findings:
      - Identified affected Dutch page 1: Lidmaatschap (Current: €180 | Target: €120)
      - Identified affected Dutch page 2: Gezinslidmaatschap (Current: €180 | Target: €120)
      - Observation: Preceding published Dutch revisions show €120 with identical visitor-guide copy.

  Step 3: MCP Tool Call - Revision Reversion
    Action: Restoring Dutch Translation Revision
    Status: Reverting Dutch revisions while preserving English node tree.

Agent Final Response

Restored both Dutch membership pages to the previous published price of €120:
• Lidmaatschap
• Gezinslidmaatschap

Both remain published. The English translations and shared content were left unchanged.

Step 4: Verification of Results

1. Frontend Page Display

• English Page (/membership):
  • Title: Membership
  • Author/Date: By Maya, 17 September 2026
  • Body: Annual membership: €120. Includes the new visitor guide. (Remains untouched)
• Dutch Page (/lidmaatschap):
  • Title: Lidmaatschap
  • Author/Date: By Maya, 17 September 2026
  • Body: Jaarlidmaatschap: € 120. Inclusief de nieuwe bezoekersgids. (Successfully restored to €120)

2. Drupal Revision Log & Audit Trail

Drupal maintains attribution and accountability: each automated action is recorded under the authenticated user's name (Maya), with full rollback history intact.

Step 5: Multi-Platform Agent Ecosystem

The keynote emphasizes that the Drupal MCP endpoint is not limited to ChatGPT. Because it sits directly on Drupal's API and permission layer, any MCP-compatible AI agent, development environment, or productivity tool can be connected:

                                  ┌──────────────────────────┐
                                  │      DRUPAL CORE         │
                                  │ (Nodes, Translations,    │
                                  │  Permissions, Revisions) │
                                  └─────────────┬────────────┘
                                                │
                                  ┌─────────────┴────────────┐
                                  │   DRUPAL MCP ENDPOINT    │
                                  └─────────────┬────────────┘
         ┌──────────────────────────────┬───────┴──────────────────────────────┐
         ▼                              ▼                                      ▼
┌──────────────────┐          ┌──────────────────┐                   ┌──────────────────┐
│  General LLM /   │          │  Team Workspace  │                   │ Developer IDEs & │
│  Chat Interfaces │          │   Integrations   │                   │ App Environments │
├──────────────────┤          ├──────────────────┤                   ├──────────────────┤
│ • ChatGPT        │          │ • Slackbot       │                   │ • Cursor         │
│ • Claude Cowork  │          │ • Jira (Rovo)    │                   │ • VS Code Copilot│
│ • Mistral Vibe   │          │ • MS Copilot     │                   │ • PhpStorm Copilot│
│ • Gemini         │          │ • Notion Agent   │                   │ • Replit         │
│ • OpenClaw       │          │ • Acquia AI      │                   │ • Figma Make     │
│ • LibreChat      │          │                  │                   │ • v0 by Vercel   │
│                  │          │                  │                   │ • Lovable        │
│                  │          │                  │                   │ • Custom Web App │
└──────────────────┘          └──────────────────┘                   └──────────────────┘

Highlights of Integrated Ecosystem Tools

1. Conversational & Collaborative Agents:
   • ChatGPT: Natural language administrative and editorial control.
   • Claude (Cowork): Task delegation and app syncing inside connected team workspaces.
   • Mistral (Vibe Work) & Gemini: Cross-model verification and task handling.
   • OpenClaw: Dedicated local/gateway assistant management.
2. Operational Workspaces:
   • Slack (Slackbot): Direct-message assistant inside Slack channels.
   • Jira (Rovo): Reviewing and updating website copy linked to ticket boards.
   • Microsoft Copilot: Integrated into Microsoft Teams for summarizing site changes and drafting updates.
   • Notion Agent: Syncing draft announcements and checking tuition/fees or event states.
3. App Builders & Custom UI:
   • v0 by Vercel & Lovable: Rapid building of editorial tools directly hooked into Drupal backend services.
   • Your Own Application: Standalone custom editorial interfaces (e.g., Western Lakes Editorial Assistant with pages, revisions, and custom chat panels).
4. Developer IDEs:
   • Cursor, VS Code (GitHub Copilot), PhpStorm, Replit: Code-level understanding of site schemas, configs, and MCP actions.

Tutorial: Connecting AI Assistants to Drupal as a Next-Generation Interface

Based on the DrupalCon keynote presentation, this tutorial explores how AI assistants can be connected directly to Drupal to perform complex content operations while preserving enterprise governance, and what architectural components make this possible today and in the near future.

1. Overview & Key Philosophy

Connecting AI assistants directly to Drupal introduces a fundamental paradigm shift in how users interact with content management systems:

+-----------------------------------------------------------------------+
|  "Get Drupal's power without the learning curve."                     |
|  REVISIONS  •  MODERATION  •  PERMISSIONS                             |
+-----------------------------------------------------------------------+

Core Takeaways:

1. Zero Learning Curve for End Users: Users do not need to learn Drupal's administrative menu trees, where to click, or the technical mechanics behind revisions, moderation states, and permission matrices. Content operations are simplified through natural language interaction.
2. Enterprise Governance Behind the Scenes: While the user experience is drastically simplified, Drupal continues to enforce strict governance, revision histories, workflow moderation, access control, and observability in the background.

2. Architecture: Connecting an Assistant to Drupal Today

You can connect an AI assistant to a Drupal site today using an official recipe and foundational modules.

+------------------------------------+          +--------------------+
|            DRUPAL SITE             |          |                    |
|  +------------------------------+  |          |                    |
|  | Simple OAuth                 |  |  <====>  |    AI ASSISTANT    |
|  | MCP Server                   |  |          |                    |
|  | Tool module                  |  |          |                    |
|  +------------------------------+  |          |                    |
+------------------------------------+          +--------------------+

The Recipe

• Drupal Recipe Project: drupal.org/project/agent_access

Key Architectural Components

3. Extending Capabilities: Exposing Module Functionality as "Tools"

Connecting an assistant via OAuth and MCP provides the communication pipeline, but it does not automatically make every Drupal feature accessible.

+-------------------------------------------------------------------+
|                           DRUPAL SITE                             |
|                                                                   |
|   +-----------------------------------------------------------+   |
|   | Simple OAuth  +  MCP Server  +  Tool                      |   |
|   +-----------------------------------------------------------+   |
|   | [ Code that exposes module capabilities as "Tools" ]      |   |
|   +-----------------------------------------------------------+   |
+-------------------------------------------------------------------+
                                  |
                                  | (Exposes available tools)
                                  v
                        +--------------------+
                        |    AI ASSISTANT    |
                        +--------------------+

Crucial Rule: "Exposing module capabilities as tools takes code."

To allow an AI assistant to perform actions within specific subsystems, developers must write dedicated bridge code that registers those actions as invokable tools. This requirement applies across all layers of the Drupal ecosystem:

• Drupal Core Modules
• Contributed Modules
• Custom Site Modules

4. Deep-Dive Example: The Multi-Layered Translation Problem

To understand why exposing tools is powerful, consider a typical multilingual content management challenge.

The Scenario

A content editor views a page primarily rendered in Dutch (Taal: Nederlands), but with three remaining English interface strings:

+------------------------------------------------------------------------------------+
|  [OOO] Taal: Nederlands                                                            |
|  +------------------------------------------------------------------------------+  |
|  | [ Welcome     ]  ----------------------------------------------------------  |  |
|  | [ Latest news ]  ----------------------------------------------------------  |  |
|  | [ Read more   ]  ----------------------------------------------------------  |  |
|  +------------------------------------------------------------------------------+  |
+------------------------------------------------------------------------------------+

The User Prompt

Instead of navigating Drupal's admin interface, the user enters a single prompt:

"TRANSLATE THE REMAINING ENGLISH ON THIS PAGE TO DUTCH"

The Reality Under the Hood in Drupal

An end user typically does not realize that these three identical-looking strings belong to three entirely separate administrative workflows and database structures:

Prompt: "TRANSLATE THE REMAINING ENGLISH ON THIS PAGE TO DUTCH"
  │
  ├──► String 1: "Welcome"
  │     ├── Underlying System: CONTENT BLOCK FIELD
  │     └── Required Workflow: Content Translation
  │
  ├──► String 2: "Latest news"
  │     ├── Underlying System: VIEW TITLE
  │     └── Required Workflow: Configuration Translation
  │
  └──► String 3: "Read more"
        ├── Underlying System: UI STRING
        └── Required Workflow: Interface Translation

Comparison of User Workflows

┌─────────────────────────────────────────────────────────────────────────────┐
│ TRADITIONAL DRUPAL ADMIN UI                                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 1. User must learn Drupal jargon (Content vs. Configuration vs. Interface). │
│ 2. Navigate to Content -> Blocks -> Edit Block -> Translate tab ("Welcome").│
│ 3. Navigate to Structure -> Views -> Edit View -> Translate ("Latest news").│
│ 4. Navigate to Configuration -> Regional -> Translate interface ("Read more")│
│ 5. Save and deploy three isolated forms.                                    │
└─────────────────────────────────────────────────────────────────────────────┘
                                      vs.
┌─────────────────────────────────────────────────────────────────────────────┐
│ AI ASSISTANT + EXPOSED DRUPAL TOOLS                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│ 1. User says: "Translate the remaining English on this page to Dutch".      │
│ 2. The AI assistant maps the strings to the exposed tool definitions.       │
│ 3. The assistant traverses all 3 underlying paths automatically.             │
│ 4. Revisions, moderation, and permissions are respected under the hood.     │
└─────────────────────────────────────────────────────────────────────────────┘

(Note: In current Drupal versions, this specific multilingual translation demo represents a mock-up vision. The code exposing all translation subsystems as tools to the AI assistant is the next frontier of development).

5. Architectural Principle: "Agents Are Another Interface to Drupal"

+-----------------------------------------------------------------------+
|                AGENTS ARE ANOTHER INTERFACE TO DRUPAL.                |
+-----------------------------------------------------------------------+

What this means:

• Addition, Not Replacement: AI agents do not replace the existing Drupal administrative interface; they serve as an alternative, parallel interface.
• Expanding Accessibility: It provides site builders and end users a choice in how they manage their digital experience platform.
• User Expectations: Just as software developers increasingly adopt CLI-based coding agents, content editors who experience assistant-driven operations will expect AI assistants to assist with day-to-day administrative tasks. Drupal’s structured architecture positions it uniquely to fulfill this demand while ensuring complete governance and accountability.

Building MCP-Ready Drupal Modules: Tool API & Workflow Orchestration Tutorial

This tutorial provides a comprehensive guide to exposing Drupal modules to AI assistants and workflow engines using MCP (Model Context Protocol), the experimental Tool API / Tool Module Prototype, and visual orchestration with FlowDrop.

Table of Contents

1. The Problem: Why Modules Need a Standard Capability Layer
2. The Architecture: "Describe Once, Use in Multiple Places"
3. Step-by-Step Code Tutorial: Exposing PHP Methods via Tool Attributes
   • Step 1: Baseline PHP Function
   • Step 2: Describing Function Capabilities with #[ToolDescription]
   • Step 3: Defining Input Arguments with #[ToolInput]
   • Step 4: Specifying Return Types via Standard Docblocks
   • Step 5: Distinguishing Data Semantics with #[ToolProperty]
   • Summary: ~1,000 Lines vs. ~20 Attributes
4. Deployment Target 1: Interacting via AI Assistants (Claude / MCP)
5. Deployment Target 2: Workflow Orchestration with FlowDrop
   • The dri.es MCP Server Definition
   • Pathway A: No AI (Deterministic Form Execution in < 1s)
   • Pathway B: With AI (Autonomous ReAct Agent)
6. Ecosystem Synergy: ECA, Maestro, and Drupal AI

1. The Problem: Why Modules Need a Standard Capability Layer

Drupal sites contain extensive structured information—from content nodes and taxonomy terms to custom entities and media assets. In his personal website (dri.es), Dries Buytaert maintains over 10,603 photos collected over decades.

+-------------------------------------------------------------------+
| dri.es: Photos Archive                                            |
| Total: 10,603 Photos                                              |
| Albums: Albacete, Boston, Chemung, East Coast, Grand Canyon, ...   |
+-------------------------------------------------------------------+

When users or family members ask real-world questions such as:

"Do you have that photo of Oma wearing her sunglasses?"

Locating that exact asset manually requires sifting through thousands of records. Exposing module capabilities to an AI assistant via the Model Context Protocol (MCP) enables models to interact directly with site tools.

The Initial Challenge

Manually adapting a single custom module to support the Tool API / MCP previously required ~1,000 lines of boilerplate code. With thousands of contributed and custom Drupal modules, scaling this integration requires a declarative approach.

2. The Architecture: "Describe Once, Use in Multiple Places"

By standardizing integration code through PHP attributes, a module's PHP methods are defined once and reused across both AI and non-AI consumer targets:

                      +-----------------------------+
                      |     Module's PHP Method     |
                      |        findImage()          |
                      +--------------+--------------+
                                     |
                                     v
                      +-----------------------------+
                      |   Shared Integration Code   |
                      |    (Tool API Attributes)    |
                      +--------------+--------------+
                                     |
         +---------------------------+---------------------------+
         |                           |                           |
         v                           v                           v
+------------------+       +-------------------+       +-------------------+
|   AI Assistant   |       |   ECA / FlowDrop  |       |   OpenAPI / JSON  |
|      (Tool)      |       |  Workflow Action  |       |   Schema for IDEs |
|                  |       |    (No AI / Human)|       |   & Components    |
+------------------+       +-------------------+       +-------------------+

The Architectural Benefits

1. AI Assistant Tooling: Models call methods to fetch structured site content.
2. Deterministic Human Workflows: Run modules inside visual workflow builders (FlowDrop, ECA, Maestro) without AI overhead.
3. OpenAPI Schema Generation: Automatically outputs standardized API definitions (15-year-old industry standard).
4. JavaScript Tooling & IDE Autocomplete: Provides JSON schemas for front-end component integration.

3. Step-by-Step Code Tutorial: Exposing PHP Methods via Tool Attributes

This implementation is based on the Tool Module Research Prototype developed by Dries Buytaert, Matt Glaman, and Michal Lander (author of the Tool module).

Step 1: Baseline PHP Function

Start with an existing method in your Drupal module:

public function findImage(string $query): array

Step 2: Describing Function Capabilities with #[ToolDescription]

AI models and workflow engines require a semantic description of what the function performs:

#[ToolDescription('Finds photos by their name, alt-text or caption.')]
public function findImage(string $word): array

Step 3: Defining Input Arguments with #[ToolInput]

Parameters need clear boundaries, descriptions, and examples to guide tool callers:

#[ToolDescription('Finds photos by their name, alt-text or caption.')]
public function findImages(
  #[ToolInput('One word or phrase.', example: 'Oma sunglasses')]
  string $query,
): array

Step 4: Specifying Return Types via Standard Docblocks

Instead of requiring custom schema wrappers, the Tool API automatically reads standard PHP docblocks:

/**
 * @return \Drupal\album\Image[]
 */
#[ToolDescription('Finds photos by their name, alt-text or caption.')]
public function findImages(
  #[ToolInput('One word or phrase.', example: 'Oma sunglasses')]
  string $query,
): array

Step 5: Distinguishing Data Semantics with #[ToolProperty]

In vanilla PHP, title, caption, and url are all primitive string types. However, external consumers require distinct formatting semantics:

• Title → Plain text
• Caption → HTML
• URL → Link / URI

Use #[ToolProperty] on class properties and accessor methods to designate media types:

class Image {
  public function __construct(
    #[ToolProperty(description: 'The title of the photo.', media_type: 'text/plain')]
    public readonly string $title,

    #[ToolProperty(description: 'Formatted caption.', media_type: 'text/html')]
    public readonly string $caption,
  ) {}

  #[ToolProperty(name: 'url', description: 'Full web address to the photo.', data_type: 'uri')]
  public function getUrl(): string {
    // Returns image URL
  }
}

Summary: ~1,000 Lines vs. ~20 Attributes

BEFORE:
[ 1,000 Lines of Integration Code ]