Build a Governed Drupal AI Assistant with MCP, OAuth and Tool API

Tim Rabbetts | October 6, 2026

Drupal’s AI conversation has moved quickly from generation and search towards a more consequential idea: external assistants that can act on a Drupal site. Following DrupalCon Rotterdam in September 2026, the Drupal community is demonstrating AI assistants that can inspect content, prepare changes, find media and trigger site operations through Drupal’s own permission and revision systems. The important development is not simply that an assistant can call an API. It is that Drupal can become a governed action surface rather than an unprotected collection of endpoints. ([drupal.org](https://www.drupal.org/blog/proof-not-promises-watch-the-six-demos-from-the-driesnote-rotterdam?utm_source=openai))

That distinction matters to agencies, public-sector teams and enterprise site owners. A tool that can create or modify content is potentially useful, but it is also a privileged integration. It needs a real identity, narrowly scoped capabilities, predictable input validation, visible drafts, reviewable changes and an audit trail. This article shows how to approach that architecture using the recently published Agent Access recipe, MCP Server, Simple OAuth and Tool API, while being clear about what is production-ready and what remains experimental.

What has changed in Drupal’s AI architecture?

Drupal’s current AI direction has two related sides. “Inside AI” brings assistance into Drupal for editors and site builders. “Outside AI” allows an external assistant, agent or developer tool to connect to Drupal and use capabilities exposed by the site. The latter is the focus here: the assistant is outside Drupal, while Drupal remains responsible for identity, access control, content rules and the final state of the site. ([drupal.org](https://www.drupal.org/about/ai/initiatives/blog/drupal-ai-initiative-introducing-inside-ai-and-outside-ai?utm_source=openai))

The recent DrupalCon demonstrations showed this model in practical terms. An editor could ask an assistant to restore selected translated content while leaving the English version untouched. The result was recorded as a Drupal revision under the editor’s identity rather than silently overwriting data. Another demonstration exposed a custom photo library to more than one interface, reinforcing the “describe once, use in multiple places” principle. ([drupal.org](https://www.drupal.org/blog/proof-not-promises-watch-the-six-demos-from-the-driesnote-rotterdam?utm_source=openai))

There are four layers in the emerging architecture:

  • Identity: an OAuth-authenticated Drupal user connects the assistant.
  • Capabilities: Tool API defines what operations exist and what inputs they accept.
  • Transport: MCP Server exposes selected capabilities to compatible clients.
  • Governance: Drupal permissions, moderation, revisions, validation and logging remain authoritative.

This is materially safer than giving an AI system a database connection, an unrestricted JSON:API client or a shared administrator token. The assistant can only do what the connected Drupal account and the exposed toolset allow it to do.

Understand the maturity level before you install it

The Agent Access project is a Drupal recipe that combines Simple OAuth, Tool API and MCP Server. Its project page currently describes it as an alpha release, and the project is not covered by Drupal’s security advisory policy. That makes it useful for evaluation and controlled development, but it should not be treated as a finished, risk-free production feature simply because the installation process is straightforward. ([drupal.org](https://www.drupal.org/project/agent_access?utm_source=openai))

Tool API itself is also on the road to a stable 1.0 release. Its current design provides typed inputs and outputs, validation, access checks, generated schemas and reusable tools that can be consumed by AI agents, MCP clients, ECA, Drush or PHP code. However, its maintainers explicitly warn that APIs may change between beta releases. ([drupal.org](https://www.drupal.org/project/tool?utm_source=openai))

Use the integration in one of these modes:

  • Local development: learn the tool discovery and authentication flow against disposable content.
  • Internal staging: test with realistic roles and content, but keep the endpoint inaccessible to the public internet if possible.
  • Limited production pilot: expose only read operations or draft-only writes to a small group of named users, with monitoring and a rollback plan.

Do not begin by connecting a general-purpose assistant to a production administrator account. The first success criterion is not “the assistant changed a node”. It is “the assistant attempted a change, Drupal applied the correct access rules, the result remained reviewable, and the organisation can explain exactly what happened”.

Prerequisites for the Agent Access recipe

The documented recipe requires Drupal 11.4 or later, a project created with drupal/recommended-project and a current Composer 2 release. Drupal 11.4 introduced the experimental extensible vendor/bin/dr command, which is used by the recipe installation instructions. ([drupal.org](https://www.drupal.org/project/agent_access?utm_source=openai))

Before changing a site, create a branch and take a database backup. Confirm that your deployment process can rebuild the same Composer lock file and export configuration. You should also have HTTPS working on the environment that will host the MCP endpoint. Simple OAuth’s own guidance recommends using SSL for bearer-token authentication. ([drupal.org](https://www.drupal.org/project/simple_oauth?utm_source=openai))

From the Drupal project root, the documented dependency installation is:

composer require \
  'drupal/tool:^1.0@beta' \
  'drupal/tool_belt:^1.0@alpha' \
  'drupal/mcp_server:^2.0.0-beta2@beta' \
  'drupal/mcp_server_tool_bridge-mcp_server_tool_bridge:^1.0@beta' \
  'drupal/mcp_server_oauth-mcp_server_oauth:^1.0@alpha' \
  'drupal/agent_access:^1.0@alpha'

Apply the recipe with your site’s HTTPS URL:

vendor/bin/dr recipe ../recipes/agent_access \
  --url=https://your-site.example

Do not paste the example URL into a real deployment. Replace it with the canonical HTTPS origin that the assistant will use. If your site is behind a reverse proxy or load balancer, verify that Drupal correctly detects HTTPS and generates the expected absolute URLs. Incorrect proxy configuration can produce OAuth callback or endpoint URLs that work internally but fail from the client.

What each component contributes

Simple OAuth provides identity

Simple OAuth implements the OAuth 2.0 framework for Drupal. In this design, the person connecting the assistant uses their own Drupal account. That is preferable to a single shared “AI user” because the resulting permissions and accountability map to an identifiable principal. The Agent Access project explicitly describes this user-centred model: the connected user’s existing Drupal permissions should apply. ([drupal.org](https://www.drupal.org/project/agent_access?utm_source=openai))

That does not eliminate the need for access design. OAuth proves who the client is and allows it to obtain a token; it does not decide which content the user ought to edit. Drupal roles, permissions, entity access and moderation rules still need to be configured deliberately.

Tool API provides the contract

Tool API is not just a list of PHP callbacks. A tool declares inputs, outputs, validation and access behaviour. Those definitions can be represented as schemas for consumers such as MCP clients. The same tool can also be used by non-AI consumers, which avoids implementing a different business rule for every interface. ([drupal.org](https://www.drupal.org/project/tool?utm_source=openai))

This is a useful design constraint. A tool should express a business operation, not expose arbitrary internal storage. “Prepare a revision of an event summary” is a better capability than “update field values on any node”. The former can enforce bundle restrictions, moderation state, language rules and editorial policy in one place.

MCP Server provides the connection boundary

MCP is the protocol boundary between a compatible external client and the Drupal tools that have been made available. MCP Server deliberately separates the transport and discovery layer from the tools themselves. The Tool Bridge can expose Tool API tools, while OAuth support protects the connection. The MCP Server UI project also describes configuration as ordinary Drupal configuration that can be exported and deployed, although the UI and related modules remain early-stage. ([drupal.org](https://www.drupal.org/project/mcp_server_ui?utm_source=openai))

Start with a read-only toolset

The safest first deployment is read-only. Install the integration in a development environment, connect a test account and inspect which tools are visible. Tool API provides commands for discovering and inspecting tools, while the Tool Explorer can show their schemas and permissions.

drush tool:list
drush tool:search content
drush tool:info tool_belt:system_status

The exact tool names available on a site depend on the installed tool collections and their versions. Treat the output of tool:list as authoritative rather than copying names from an article. Tool API deliberately ships the framework separately from collections of tools, so a fresh installation does not automatically expose every possible Drupal operation. ([drupal.org](https://www.drupal.org/project/tool?utm_source=openai))

For a read-only pilot, allow operations such as:

  • finding published content by title, type or taxonomy;
  • reading selected field values;
  • locating media that an editor already has permission to use;
  • checking metadata or translation status;
  • reporting content that matches a defined review condition.

Avoid enabling broad administrative tools merely because they appear in discovery. Discovery is not a security boundary. A tool should be unavailable to the account unless it is needed for the workflow, and the endpoint should not expose sensitive tool descriptions to unauthorised users.

Design writes as drafts, not direct publication

For most editorial workflows, the first write capability should create a draft or revision. Publishing should remain a separate operation requiring a human role, a moderation transition or an explicit approval step. This is the pattern demonstrated by the Northmoor University AI demo: the assistant can prepare changes across multiple pages, but the changes remain drafts until an editor reviews them. ([drupal.org](https://www.drupal.org/about/ai/initiatives/blog/drupal-ai-after-the-driesnote-rotterdam-what-you-can-use-today-and-what-comes-next?utm_source=openai))

A practical permission model might contain these roles:

  • AI reviewer: can read approved content and create unpublished revisions, but cannot publish.
  • Senior editor: can review, amend and publish content within assigned editorial areas.
  • Site administrator: can manage integrations and tool exposure, but is not used for routine assistant activity.

Use content moderation and revisions to make the state transition visible. If your content type has a workflow such as Draft, Needs Review and Published, ensure the assistant’s account can only move content into the intended intermediate state. Do not assume that a natural-language instruction such as “publish this” can be safely interpreted by the model. The permission system must make an unsafe transition impossible.

For bulk changes, prefer a two-phase operation:

  1. Search and return a bounded list of candidate entities.
  2. Prepare explicit revisions for selected entity IDs.
  3. Return a summary of proposed changes.
  4. Require a human to review and publish.

This makes the workflow inspectable and reduces the blast radius of a misunderstood prompt. It also gives editors a chance to reject changes that are technically valid but editorially inappropriate.

Control what the assistant can see

Permissions are necessary but not sufficient. An assistant may have permission to read a content type while still receiving more information than the workflow requires. Review the fields and entities returned by every exposed tool. Private notes, internal contact details, unpublished campaign plans and personal data should not be included simply because the connected account can access them in the normal Drupal UI.

Use separate test accounts for separate purposes. An assistant used for public-content review should not share credentials with an assistant used for internal knowledge management. If you need two workflows, give them two roles and expose two toolsets. Narrow identities are easier to monitor and revoke.

Be particularly careful with media and file operations. A tool that can upload files or alter media metadata may have consequences outside the content item the editor thinks they are changing. Restrict allowed file extensions, validate MIME types, enforce file schemes and keep private files on private storage. Never allow an assistant to choose an arbitrary server path.

Keep the MCP endpoint out of the general attack surface

An MCP endpoint is an application interface, not a magic trusted tunnel. Apply the same operational controls you would use for an administrative API:

  • enforce HTTPS and redirect HTTP to HTTPS;
  • use strong, rotated OAuth keys and keep private keys outside the document root;
  • avoid sharing client secrets through chat, tickets or repository files;
  • restrict administrative configuration to a small number of trusted users;
  • apply rate limits at the reverse proxy or application edge;
  • monitor authentication failures and unusual tool-call volume;
  • disable or remove the integration when the pilot ends.

Do not place bearer tokens in prompts, browser local storage or issue descriptions. Treat them like passwords. If an external assistant vendor stores conversation history, consider whether prompts and tool results could contain personal, confidential or commercially sensitive Drupal data.

The Agent Access project is explicitly marked as not covered by Drupal’s security advisory policy. That status should affect deployment decisions: pin versions, review changes before updating, test backups and maintain a documented disable procedure. ([drupal.org](https://www.drupal.org/project/agent_access?utm_source=openai))

Prompt injection is an application security problem

Content is untrusted input, even when it is stored inside your own Drupal database. A malicious or merely confusing paragraph can instruct an assistant to ignore its task, reveal hidden information or invoke a different tool. This is prompt injection, but the mitigation is not just a better system prompt.

Build the workflow so that a successful injection still cannot exceed the account’s permissions. Keep tools narrow, separate read and write operations, require explicit entity identifiers for changes and make publication a distinct permission-gated step. Avoid tools that accept free-form instructions and then execute arbitrary Drupal operations.

For high-impact actions, add deterministic checks outside the model:

  • allow only particular content types and languages;
  • reject updates to fields outside an approved list;
  • limit the number of entities changed in one invocation;
  • reject publication unless a required moderation state is present;
  • require a human approval event before external side effects.

The principle is simple: an assistant may propose intent, but Drupal must enforce the resulting operation.

Logging and auditability

Every pilot should answer five questions for each tool call:

  1. Which Drupal user authorised the request?
  2. Which external client or integration initiated it?
  3. Which tool was called, with which validated inputs?
  4. Which entities or configuration objects were affected?
  5. What was the resulting revision, moderation state or error?

Drupal’s revision history is valuable, but it is not the entire audit trail. Record enough structured information to correlate an assistant request with the Drupal revision and the surrounding application logs. Do not log access tokens, full prompts containing personal data or unrestricted tool output.

Set alert thresholds for unusual patterns: repeated failed authentication, sudden increases in tool calls, attempts to access unpublished content, large batches of revisions or calls outside normal working hours. Observability should be part of the first pilot rather than an improvement scheduled after an incident.

Common failure modes

The recipe installs but the endpoint cannot be reached

Check the site’s canonical URL, reverse-proxy HTTPS detection, firewall rules and web-server routing. Confirm that the environment can serve the expected Drupal routes and that the client is not being redirected to an internal hostname.

The assistant sees no useful tools

Inspect the installed collections with drush tool:list. Tool API supplies the framework, not every operation. Confirm that the Tool Bridge is installed and that the connected Drupal account can access the selected tools. Also check whether the tool is intentionally hidden by configuration or unavailable because of permissions.

A tool works in the explorer but fails through MCP

Compare the authenticated account and input schema. The Tool Explorer may be running as an administrator, while the MCP client is using a restricted editorial account. Test the same operation with the least-privileged account and inspect validation errors rather than weakening permissions.

Updates break the integration

Beta APIs can change. Keep the Composer lock file under version control, update in staging and read release notes before changing Tool API, MCP Server or Agent Access versions. Run a small smoke-test suite that authenticates, lists permitted tools, reads a known entity and creates a non-published test revision.

A sensible adoption path

For most Drupal teams, the right sequence is incremental:

  1. Read the current Drupal AI and Agent Access documentation.
  2. Build a disposable Drupal 11.4 or later site.
  3. Install the recipe and inspect the tools without connecting production data.
  4. Create a dedicated test role with read-only access.
  5. Test content lookup and logging.
  6. Add one narrowly scoped draft-only write operation.
  7. Test prompt injection, token revocation, rate limits and rollback.
  8. Run a small internal pilot with named users.
  9. Review the security posture before considering production content.

Do not measure success by how autonomous the assistant becomes. Measure whether it reduces repetitive work while preserving editorial ownership, predictable permissions and a reliable record of every change.

Conclusion

Drupal’s recent MCP and Agent Access work is significant because it treats AI integration as an extension of Drupal’s existing governance model rather than a reason to bypass it. The combination of OAuth identity, Tool API contracts, MCP transport, revisions and moderation can produce useful assistant workflows without handing an opaque system unrestricted control of a site. ([drupal.org](https://www.drupal.org/blog/proof-not-promises-watch-the-six-demos-from-the-driesnote-rotterdam?utm_source=openai))

It is still early technology. Agent Access and several underlying components are alpha or beta projects, and the security responsibility currently sits heavily with the implementer. The practical approach is therefore conservative: start read-only, expose a small toolset, create drafts instead of publishing, use real Drupal permissions, log every operation and keep a tested escape hatch.

That discipline is what makes the architecture valuable. The assistant can become another interface to Drupal, but Drupal remains the system that decides what is allowed, what is validated and what finally reaches the public.