README

Agent Access for Drupal is an experimental, opinionated way for external AI agents to connect through a person's existing Drupal account. It is part of the Drupal AI Initiative's Outside AI work: establishing a clear Drupal approach to agent authentication and access that sites and client developers can test, improve, and build on.

Drupal remains the authority. Requests run as the connected account and are limited by that account's existing permissions and approved access. This first implementation brings together Simple OAuth, Tool API, and MCP Server.

Current status

This is an experimental 1.0.x development release and is not covered by Drupal's security advisory policy. Some required modules are alpha or beta releases. Use it to evaluate the approach on a non-production site while the dependency stack and connection lifecycle mature. See SECURITY.md for the current safety boundary.

Install

Use a current Composer 2 release. From the root of a Drupal 11.4 project created from drupal/recommended-project, run these as two separate commands. The first is currently needed because some dependencies have not reached stable releases.

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

composer require 'drupal/agent_access:1.0.x-dev@dev'

Copy the package names exactly; the two doubled names are the packages published by the standalone Drupal.org projects. Then apply the recipe:

vendor/bin/dr recipe ../recipes/agent_access

With DDEV, use ddev exec vendor/bin/dr recipe ../recipes/agent_access.

If Drupal says a newly installed extension "is not a known module or theme," rebuild caches and apply the recipe again. This is tracked in Drupal core issue #3501858.

Connect and try it

The recipe cannot generate site secrets or decide which existing roles may connect:

Open /admin/config/people/simple_oauth, select Generate keys, choose a directory outside the web root that the web server can write, generate the keys, and save the settings. The form fills the public and private key paths for you.

If Drush is already installed, you can do the same from the project root:

mkdir -p /path/outside/webroot/oauth-keys
vendor/bin/drush simple-oauth:generate-keys /path/outside/webroot/oauth-keys
vendor/bin/drush config:set simple_oauth.settings public_key /path/outside/webroot/oauth-keys/public.key -y
vendor/bin/drush config:set simple_oauth.settings private_key /path/outside/webroot/oauth-keys/private.key -y

Grant grant simple_oauth codes and access mcp server to the existing role used by your test account. Do not grant them broadly to authenticated.
Choose the automatic-registration or manually configured Consumer path in CONNECTING.md. For a quick interoperability test, an external agent that supports authenticated remote servers and dynamic client registration can start with this connection address:
```
https://your-site.example/mcp
```
Use the manual Consumer path when you need Drupal to require PKCE, configure the client for S256, and disable remembered approval explicitly.
The client should open Drupal in your browser. Sign in with the test account, review the two requested scopes, approve the connection, and return to the agent.
Confirm that the agent sees exactly these two starter tools:
- tool_api__entity_list — List entities
- tool_api__entity_metadata — Get entity metadata

Try this first prompt:

List up to five Drupal node entities I am allowed to access, then show the metadata for the first result. Do not make any changes.

See CONNECTING.md for client requirements, the controlled manual Consumer path, troubleshooting, and cleanup.

What it adds

The recipe enables the required Simple OAuth, Tool API and Tool Belt, and MCP Server modules. It adds two scopes mapped to permissions Drupal already has:

Scope	Existing Drupal permission
`drupal:mcp:connect`	`access mcp server`
`drupal:content:read`	`access content`

The starter catalog maps the Tool API IDs tool_belt:entity_list and tool_belt:entity_metadata to the two client-visible names above. It has no write tools. Sites can add compatible tools, but each added tool needs its own access and behavior review. Do not enable tool_belt:entity_field_values or tool_belt:entity_load_by_id on the current tested stack. The current entity_list implementation also has known aggregate, pagination, and referenced-label access limitations, so evaluate it only with data you can safely expose.

Update a development install

Recipes are apply-time configuration, so updating the Composer package alone does not update active configuration. Earlier development installs must update the packages, run the bundled development migration recipe, and then apply the main recipe again. The migration prepares the two retained tool configs for strict comparison and disables the third tool shipped by the earlier public development revision.

Because 1.0.x-dev can change between commits, back up the site and read UPGRADING.md before updating.

Report a problem

Use the Agent Access issue queue for recipe, installation, documentation, and integration problems. If investigation identifies a defect in an underlying module, report it in that module's project and link it from the Agent Access issue. Remove credentials and tokens before sharing logs.

License

GPL-2.0-or-later. See LICENSE.

drupal / agent_access

Maintainers

Package info

Statistics

Security