Bridging Drupal and AI: A Developer’s Guide to the Model Context Protocol (MCP)

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, 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 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.

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

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.

• 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:

• 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.

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.

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.