mcp_server

Built by a human using an AI assistant: 🤖 ➕ 🧠

A lot of the code in this module has been created using an AI assistant using the AI Task Manager for improved Drupal code generation.

Overview

Built on the Tool API module, MCP Server provides a configuration-driven approach to exposing Drupal capabilities to AI systems.

This module supports both the STDIO transport, as well as the HTTP transport.

Key Capabilities

No-code MCP tools

Any Tool API plugin becomes an MCP tool through configuration.

OAuth 2.1 authentication

Secure API access using the latest OAuth 2.1 protocol via Simple OAuth 2.1.

Dual transport

STDIO for CLI integration, HTTP for web-based clients.

Admin UI - Full CRUD interface for managing tool configurations at /admin/config/services/mcp-server/tools
Dynamic discovery - Tools are discovered from configuration entities, not hardcoded attributes

FULL protocol support

Thanks to the Official PHP MCP SDK, this module provides full support of the MCP protocol.

Support for MCP resources Support for saved prompts Support for LLM sampling Support for authentication

Architecture

This module provides an integrated, configuration-driven architecture, using:

Official SDK integration - Built on modelcontextprotocol/php-sdk, a collaboration between the PHP Foundation and Symfony project
Tool API foundation - Leverages Tool API for plugin discovery and execution
Configuration entities - MCP tools are managed through Drupal's configuration system, not PHP attributes
Modern authentication - OAuth 2.1 protocol implementation for secure API access

OAuth 2.1 Integration

MCP Server implements granular authentication controls using Simple OAuth 2.1, providing secure, token-based API access. Each tool configuration supports two authentication modes:

Required - OAuth2 Bearer token with specified scopes is mandatory (HTTP 401 without auth, HTTP 403 with insufficient scopes)
Disabled - No authentication checks (use only for public, read-only tools)

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

Note: The author of MCP Server also authored and maintains Simple OAuth and Simple OAuth 2.1, ensuring deep integration between these systems.

Quick Start

STDIO Transport (Command-line)

Configure your AI assistant to use the Drush command.

Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "drupal": {
      "command": "vendor/bin/drush",
      "args": ["mcp:server"],
      "cwd": "/path/to/your/drupal/site"
    }
  }
}

Test using Claude Desktop, or the MCP Inspector:

npx @modelcontextprotocol/inspector vendor/bin/drush mcp:server

HTTP Transport (Web-based)

The HTTP endpoint is available at https://your-drupal-site.com/_mcp.

Configure your MCP client:

{
  "mcpServers": {
    "drupal-http": {
      "url": "https://your-drupal-site.com/_mcp",
      "transport": "http"
    }
  }
}

Test using Claude Code:

claude mcp add drupal-mcp http://your-drupal-site.com/_mcp --transport http --scope project

Creating MCP Tools

MCP Server selects Tool plugins, in order to create MCP tools.

Workflow

Create a Tool API plugin in your custom module (see Tool API documentation, or install tools from the Tool Belt module.
Navigate to /admin/config/services/mcp-server/tools
Add an MCP Tool Configuration:
- Enter the MCP tool name and machine name
- Select Tool API tool ID (autocomplete)
- Configure authentication mode and OAuth scopes
The tool is now available to AI assistants via MCP protocol

Screenshots

MCP Tool Configuration List

The admin interface at /admin/config/services/mcp-server/tools provides a complete overview of configured MCP tools, including status, Tool API source, and authentication settings.

Tool Configuration Form

Configuration form with Tool API autocomplete, authentication mode selection, and OAuth scope configuration.

MCP Inspector Integration

Testing MCP tools using the official MCP Inspector (npx @modelcontextprotocol/inspector).

Requirements

Tool API module (installed automatically as dependency)
Drush 12.x or higher (for STDIO transport)
(e0ipso/simple_oauth_21) Simple OAuth 2.1 (optional, for OAuth authentication)

Related Projects

Tool API - Foundation for exposing tools to MCP
Simple OAuth 2.1 - OAuth 2.1 protocol implementation for Drupal

Resources

Model Context Protocol Documentation
Official MCP PHP SDK
MCP Specification
Symfony MCP Bundle (inspiration for this module)

Contributing

Submit issues and patches through the issue queue. Contributions are welcome.

Credits

This module integrates the official MCP PHP SDK, a collaboration between the PHP Foundation and the Symfony project. Architectural inspiration from the Symfony MCP Bundle.