MCPIO

MCPIO turns Drupal into a native MCP (Model Context Protocol) server, letting AI clients such as Claude Desktop, Cursor, or OpenCode inspect and operate your site through a single secure JSON-RPC endpoint: POST /api/mcp.

Instead of exposing dozens of REST routes, MCPIO exposes just two MCP tools — search and execute. AI clients use them to discover available actions and invoke them with validated arguments. Actions run in-process through the Drupal Tool API, so there is no extra HTTP API surface to maintain or secure.

Current release: 1.0.0-alpha1 — the initial MCP server release. Requires Drupal 10.5+ or 11.x. The two-tool interface is stable; feedback on the exposed capabilities is welcome in the issue queue as work continues toward a stable release.

Features

• Single endpoint — one JSON-RPC 2.0 route implementing initialize, tools/list, tools/call, and ping, with structured error codes. Minimal attack surface.
• Two tools — search discovers actions by keyword, tag, or id (with argument hints and machine-readable input schemas); execute runs an action with arguments.
• Capabilities out of the box — System & Health (status, cron, cache flush, security updates, AI-powered Watchdog log analysis), Content (types, search, read, create as draft, revisioned updates with diffs, publish/unpublish, audit), User (identity, listing), and AI (providers, agents).
• Built on the Tool API — native #[Tool] plugins, MCPIO action derivatives, and tools contributed by MCP Tools submodules share one discovery and execution path, with argument validation, permission checks, scopes, and read-only policies enforced by the contributed executor.
• Zero-config AI — Watchdog log analysis inherits the site's default chat provider and model from the AI module, and degrades gracefully when none is usable.
• Secure authentication — per-user API keys via Key Auth (recommended) or HTTP Basic, gated by a dedicated permission.
• Extensible — add a Tool API plugin and it is automatically discovered and exposed; no routing, services, or controller changes needed.

Requirements

• Drupal 10.5+ or 11.x, PHP 8.3+
• AI module
• Tool API
• MCP Tools

Recommended: Key Auth 2.x for API keys, and core Database Logging, Update Manager, and Node modules to unlock log analysis, update checks, and content actions.

Connecting an AI client

The easiest way to install MCPIO into your coding agent is add-mcp. One command writes the endpoint and API key into Codex, Claude Code, Cursor, or VS Code — just change --agent to match your tool:

npx add-mcp https://example.com/api/mcp \
  --transport http \
  --header "api-key: YOUR_KEY" \
  --agent codex \
  --yes

Use a key belonging to a Drupal account with the access mcpio endpoint permission, and avoid committing generated agent configuration files or exposing the key in shell history or source control.

You can also connect manually — MCPIO is an HTTP JSON-RPC endpoint, not stdio. Any MCP client that supports an HTTP/JSON-RPC transport points at:

URL     : https://example.com/api/mcp
Header  : api-key: YOUR_KEY
Method  : POST
Content : application/json (JSON-RPC 2.0 bodies)

For stdio-only clients such as Claude Desktop, bridge with a small wrapper that posts each JSON-RPC message to /api/mcp and pipes the response back to stdout.

MCPIO uses stateless JSON-RPC request/response HTTP (protocol version 2024-11-05); SSE streaming, sessions, and server-initiated messages are not yet provided, so clients requiring the newer Streamable HTTP behavior are not guaranteed to work. Once connected, discover actions with search and call them with execute, e.g. read a node:

{"name": "execute", "arguments": {"action": "content/read", "arguments": {"id": 3}}}

Configuration

Configure at Configuration → Web services → MCPIO (/admin/config/services/mcpio): choose the AI provider and model (or inherit the site default), enable or disable capability groups, and control whether contributed MCP Tools plugins are exposed. Access is governed by the access mcpio endpoint permission.