Model Context Protocol
Implements the Model Context Protocol (MCP) to enable Drupal sites to act as MCP servers, allowing AI applications like Claude to interact with Drupal content and tools.
mcp
Install
composer require 'drupal/mcp:^1.2'
Overview
The Model Context Protocol (MCP) module transforms your Drupal site into an MCP-compliant server, enabling seamless integration with AI-powered applications such as Claude Desktop, Claude Code, and Cursor IDE. MCP is an open protocol by Anthropic that allows large language models (LLMs) to dynamically extend their context using data sources and executable tools.
This module provides a foundational layer that exposes Drupal content as resources and Drupal functionality as tools that AI applications can access. It includes a plugin-based architecture allowing developers to create custom MCP plugins that expose additional resources and tools.
Built-in plugins provide access to site information, content search, JSON:API integration, Drush commands (for development), and integration with the AI module's function calling and agent capabilities. The module supports multiple authentication methods including token-based auth, basic auth, and OAuth.
Features
- Implements Model Context Protocol (MCP) specification version 2025-03-26 for Drupal
- Plugin-based architecture for extensible MCP functionality with automatic plugin discovery
- Multiple built-in MCP plugins: General (site info/status), Content (search/resources), JSON:API, Drush Commands, AI Function Calling, AI Agent Calling, and Tool API integration
- Configurable authentication supporting token-based auth, basic auth, and OAuth
- Role-based access control at both plugin and individual tool levels
- Support for both HTTP transport (direct endpoint) and STDIO transport (via Docker container)
- Connection configuration examples for Claude Desktop, Claude Code, and Cursor IDE
- Tool annotations support for hints about tool behavior (read-only, idempotent, destructive, open-world)
- Custom tool descriptions to override default descriptions for LLM optimization
- Drush generator command for scaffolding new MCP plugins
- JSON-RPC 2.0 protocol compliance via the jsonrpc module
- Flood protection for authentication to prevent brute-force attacks
- MCP Studio submodule for creating tools without coding using text, JSON, or Twig templates
Use Cases
AI-Powered Content Management
Connect Claude Desktop or Cursor IDE to your Drupal site to enable AI-assisted content management. The AI can search content, read articles, and understand your site structure through MCP tools and resources.
Development Automation
Use the Drush Commands plugin (with appropriate security considerations) to allow AI assistants to execute Drush commands, such as clearing caches, running updates, or generating code during development.
Custom AI Workflows
Create custom MCP plugins that expose your site's specific functionality as tools. For example, expose a product inventory system, user management functions, or custom business logic as MCP tools.
Content Search and Retrieval
Use the JSON:API plugin to allow AI applications to search and retrieve content with advanced filtering, sorting, and relationship includes, enabling contextual AI responses based on your site content.
AI Agent Integration
When using the AI module ecosystem, expose AI agents as MCP tools, allowing external AI applications like Claude to trigger and interact with Drupal-hosted AI agents.
Rapid Tool Prototyping
Use MCP Studio submodule to quickly create and test MCP tools without writing code. Define input schemas, output templates (with TWIG support), and test your tools before implementing them as proper plugins.
Tips
- Start with the General MCP plugin enabled to test basic connectivity before enabling more complex plugins.
- Use the Connection Info page (/admin/config/mcp/connection) to get ready-to-use configuration snippets for your MCP client.
- For development, use the MCP Studio submodule to quickly prototype tools before implementing them as proper plugins.
- When using the Drush Commands plugin, enable only specific commands that are needed and disable the plugin in production.
- Use tool-level role restrictions to provide fine-grained access control when different users need access to different tools.
- Custom tool descriptions can be used to provide more context or examples to the LLM about how to use specific tools.
- The JSON:API plugin with JSON:API Schema provides the best experience for content retrieval as LLMs can understand the schema before querying.
Technical Details
Admin Pages 4
/admin/config/mcp
Configure authentication settings for the MCP server. This page allows you to enable authentication and configure the available authentication methods.
/admin/config/mcp/plugins
View and manage all available MCP plugins. This page displays the list of plugins with their status (enabled/disabled/requirements not met) and provides access to individual plugin configuration.
/admin/config/mcp/plugins/{plugin}/settings
Configure individual MCP plugin settings including enabling/disabling the plugin, setting allowed roles, configuring custom plugin options, and managing individual tool settings.
/admin/config/mcp/connection
Displays MCP server connection information and configuration examples for various MCP clients including Claude Desktop, Claude Code, and Cursor. Includes copy buttons for easy configuration.
Permissions 2
Drush Commands 1
drush generate mcp:plugin
Generates a new MCP plugin with scaffolded code including the plugin class with getTools() and executeTool() methods.
Troubleshooting 5
The module implements flood protection. Wait for the flood window to expire (configured in user.flood settings) or clear the flood entries from the database.
Check the plugin's requirements. For example, the Content plugin requires the Node module, JSON:API plugin requires the JSON:API module, and AI plugins require the respective AI modules to be installed and configured.
Ensure the plugin is enabled, the specific tools are enabled in the plugin configuration, and the authenticated user has the appropriate role permissions.
Verify the STDIO transport configuration is correct, ensure Docker is running, and check that the Drupal site is accessible from the Docker container (use --network=host for local development).
Check both plugin-level and tool-level role configurations. Ensure the authenticated user has the 'use mcp server' permission and appropriate roles.
Security Notes 7
- The Drush Commands plugin should only be enabled in development environments due to the powerful nature of Drush commands.
- Always enable authentication in production environments to prevent unauthorized access to MCP tools.
- Use the Key module to securely store authentication tokens rather than hardcoding them.
- Review and restrict plugin and tool access by role to follow the principle of least privilege.
- The module implements flood protection for authentication to prevent brute-force attacks.
- Token authentication uses a single user context - consider using basic auth with individual user accounts for better audit trails.
- Be cautious when exposing content through MCP - consider what data should be accessible to AI applications.