---
title: "Bridging Drupal and AI: A Developer’s Guide to the Model Context Protocol (MCP)"
date: "2026-03-12T04:31:42+00:00"
summary:
image:
type: "article"
url: "/acquia-cloud-platform/help/96496-bridging-drupal-and-ai-developers-guide-model-context-protocol-mcp"
id: "e1aecce8-c5e4-4dc0-b1fd-fce4f022df43"
---

As AI agents become more prevalent, the challenge shifts from "how do I chat with an LLM?" to "how does the LLM access my data safely?" The **Model Context Protocol (MCP)** is the open standard answer. By turning Drupal into an MCP Server, you expose your nodes, views, and Drush commands as "Tools" and "Resources" that an AI can understand.

**High-Level Architecture**
---------------------------

Drupal’s implementation of MCP typically follows a client-server model. The **MCP Host** uses an **MCP Client** (eg. VSCode) to connect to your **Drupal MCP Server** via either **STDIO** (for local dev) or **HTTP/SSE** (for remote production).

###   
Core Components

*   **Official SDK integration** - Built on [modelcontextprotocol/php-sdk](https://github.com/modelcontextprotocol/php-sdk), a collaboration between the PHP Foundation and Symfony project
*   **MCP Server Module:** The foundation that implements the JSON-RPC 2.0 protocol.
*   **Tool API:** The underlying Drupal engine that converts Drupal actions into executable tools for the AI. Leverages [Tool API](https://www.drupal.org/project/tool) for plugin discovery and execution. MCP tools are managed through Drupal's configuration system, not PHP attributes
*   **Modern authentication** - OAuth 2.1 protocol implementation for secure API access
*   **Transport Layer:**
    *   **STDIO:** Used by local tools (Claude Desktop) to communicate with Drupal via a CLI process.
    *   **HTTP (SSE):** Used for remote integrations where the AI client connects over the web using Server-Sent Events.

![Diagram showing "Model Context Protocol" connecting Anthropic Claude and OpenAI to tools like REST, Salesforce Apps, and AWS Storage.](https://acquia.widen.net/content/25b20ce1-73ad-4784-ab64-ecf19307a748/web/6b8ae_mcp_anthropic.webp?w=720&itok=VCkhaVEt)

This implementation uses the Simple OAuth 2.1 module, which provides full OAuth 2.1 protocol support in Drupal. The OAuth integration enables:

*   Per-tool scope requirements
*   Token-based authentication for HTTP transport
*   Graceful handling of anonymous protocol requests (e.g., initialize)
*   Integration with Drupal's authentication system

### HTTP Transport vs STDIO Transport

Aspect

STDIO Transport

HTTP Transport

Deployment

Local machine / dev laptop

Any web server (Acquia Cloud, etc.)

Access scope

Same machine only

Anywhere over the network

Latency

Very low (no network)

Higher (network round-trips)

Multi-client

Usually single / one process

Multiple simultaneous clients

Authentication

Limited / local trust

Full Drupal / OAuth / headers

Best for

Local dev, CLI tools, testing

Production, team use, remote AI agents

In short: if you're running Drupal on Acquia (or any hosted environment) and want your site to act as a live, remote MCP server that AI tools can connect to directly — HTTP transport is basically the only practical choice. STDIO is kept in the module for local/dev convenience, but it's not viable for cloud-hosted production use.

**Setting Up Your Drupal MCP Server**
-------------------------------------

To get started, you’ll need a Drupal 10.3+ or 11 instance.

### Installation

Use Composer to pull in the necessary modules:

    composer require 'drupal/mcp:^1.2'
    composer require 'e0ipso/simple_oauth_21'

Use Drush to enable the modules and the related addon's:

    drush pm:enable simple_oauth_21 simple_oauth_device_flow simple_oauth_pkce simple_oauth_native_apps simple_oauth_server_metadata simple_oauth_client_registration
    drush pm:enable mcp

###   
Post-Installation

Run a Cache clear for the changes to take effect.

    drush cache:rebuild

###   
MCP Configuration

*   **Hardening the Gates: Authentication:**
    
    By default, an MCP server might allow anonymous access—which is a major "no" for production. Navigate to `/admin/config/mcp` to define who (or what) can talk to your site.  
    Enable authentication for the MCP server. If disabled, the server will allow clients to connect with anonymous permissions.
    
    **OAuth Integration:** If you followed our previous guide on Simple OAuth, your MCP clients can authenticate automatically using those secure tokens. This is the most robust method for remote access.
    
    **Token Authentication:** Ideal for specific service-to-service connections where you want the agent to act as a predefined user.
    
    **Basic Auth:** Uses standard Drupal username/password credentials. While simple, it enforces **Role-Based Access Control (RBAC)**, ensuring the agent only sees what that specific user role allows.
    

**Security Check**

Always ensure your service accounts have the **“Use MCP server”** and **“Use JSON-RPC services”** permissions enabled under the Drupal permissions headers.

![MCP Configuration page showing authentication options, including enabling auth, token auth, basic auth, and OAuth authentication details.](https://acquia.widen.net/content/390adde6-baf7-4a96-8f7d-aacc804ddceb/web/2a8be_MCP_1.png)

*   **The Toolbox: MCP Plugins**
    
    Plugins define _what_ your MCP server can actually do. You can toggle these at `/admin/config/mcp/plugins` depending on your project needs:
    

**Plugin**

**Purpose**

**Best Use Case**

**Content**

Integrates fields and content.

Enabling an AI to "Search Content" on your site.

**JSON:API**

Exposes Drupal's core API structure.

Complex data retrieval and filtering.

**AI Function Calling**

Bridges MCP with LLM capabilities.

Allowing an AI to trigger specific logic.

**MCP Studio**

Low-code tool creation.

Building custom tools without writing PHP.

**Drush Commands**

Executes terminal commands.

**Development only.** Never enable this in production.

Advanced Intelligence: Agents and Tools

To make your Drupal site truly "smart," you can enable specialized plugins that go beyond simple data fetching:

*   **Tool API:** Requires the [Tools API](https://www.drupal.org/project/tool) module. It allows you to expose specific Drupal functions as callable "tools" for an LLM.
*   **AI Agent Calling:** Specifically designed for agentic workflows where one AI needs to delegate tasks to your Drupal system.
*   **General MCP:** Provides the "heartbeat" of your connection, including general info and server status.

![Table listing MCP plugins with names, descriptions, statuses, and configuration options. Some plugins are enabled, others are disabled.](https://acquia.widen.net/content/a493e941-ce5b-45f1-a7be-ed7d2f2fb5b9/web/dc793_MCP_2.png)

*   **Establishing the Link: Connection Code**
    
    Once your auth is set and your plugins are active, you need to "plug in" your client (like Claude Desktop or a custom AI agent).
    
    ### **Path:** `/admin/config/mcp/connection`
    
    **Action:** This page provides the specific **Connection Code** required by your MCP Client to handshake with the Drupal server. Copy this carefully—it’s the "secret sauce" that makes the remote connection possible.
    

![Interface showing connection info for Drupal MCP, with options for HTTP Transport and STDIO Transport methods under client configuration examples.](https://acquia.widen.net/content/77c28d33-986f-4616-b841-ac74cfb6dd2f/web/06c3b_MCP_3.png)

Testing Your Integration: The "Moment of Truth"
-----------------------------------------------

Once your authentication is hardened and your plugins are active, it’s time to see your Drupal site through the eyes of an AI. The most efficient way to do this is via **VS Code** or the **MCP Inspector**.

### Configuring VS Code

To allow VS Code to "see" your Drupal MCP server, you’ll need to add a small configuration snippet. Create or edit your `.vscode/mcp.json` file with the following structure:

    {
      "mcpServers": {
        "drupal-mcp-server": {
          "url": "https://your-drupal-site.com/mcp/post",
          "type": "http"
        }
      }
    }

###   
The Authentication Handshake

When you initialize the connection or start your MCP client, a few things will happen:

1.  **The Trigger:** Your client (like Claude or VS Code) will attempt to reach the `/mcp/post` endpoint.
2.  **The Popup:** Because we enabled **OAuth 2.1** or **Token Auth** in the previous steps, a browser window or popup will appear.
3.  **Granting Access:** You will be prompted to log in to your Drupal site (if not already) and authorize the MCP client to access your data.

### Verifying Your Tools

Once the handshake is successful, your client will "discover" the capabilities of your site. Depending on which plugins you enabled (JSON:API, Content, AI Agent Calling, etc.), you should see a list of active tools ready for use.

Note

**Check the Dashboard:** If you don't see your tools immediately, revisit the **Connection** page (`/admin/config/mcp/connection`) to ensure your service account permissions are properly synced.

![Screenshot of a code editor displaying a list of Drupal tools and descriptions under "General" and "Content Management" categories.](https://acquia.widen.net/content/3e1c3290-da85-4743-830e-df0e57d808bf/web/ecd90_VSCodeTest.png)

Final Thoughts
--------------

By combining **OAuth 2.1** for security and the **MCP Server** for connectivity, you’ve transformed your Drupal site from a static CMS into an intelligent, API-driven data hub. Whether you’re building custom AI agents or just want to query your content via natural language in your IDE, you now have the foundation to do it securely.