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

Agent Access 1.0.x is experimental and currently available as an alpha release. It 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.

The project is also drafting a provider-neutral foundation for a future major release. The proposed Agent Access contract defines the shared Drupal authority boundary. Its managed personal profile, interoperability profile, and conformance suite define additional claims independently. Publishing these drafts does not make the current 1.0.x recipe conformant.

Install

Use a current Composer 2 release. From the root of a Drupal 11.4 project created from drupal/recommended-project, run:

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'

The prerelease dependencies must remain explicit root requirements because Composer ignores transitive stability flags. Copy the package names exactly; the two doubled names are the packages published by the standalone Drupal.org projects. The MCP Server beta2 floor is intentional: it allows a fresh install to resolve MCP SDK 0.7.1 instead of the earlier 0.6 line. Existing development installs should follow UPGRADING.md so their lock files are refreshed. 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," run vendor/bin/dr cache:rebuild and apply the recipe again. With DDEV, prefix both commands with ddev exec. 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

Applying the recipe with Drupal's CLI without --url can record http://localhost/oauth/register. Clear that saved value so OAuth metadata derives the registration endpoint from each HTTPS request. If project-local Drush is installed, run:
```
vendor/bin/drush config:delete simple_oauth_server_metadata.settings registration_endpoint -y
vendor/bin/drush cache:rebuild
```
With DDEV, use ddev drush config:delete simple_oauth_server_metadata.settings registration_endpoint -y followed by ddev drush cache:rebuild. Without project-local Drush or DDEV, open /admin/config/people/simple_oauth/oauth-21/server-metadata, clear Client Registration Endpoint, save the form, and run vendor/bin/dr cache:rebuild.

Before connecting, open https://your-site.example/.well-known/oauth-authorization-server and confirm that registration_endpoint is https://your-site.example/oauth/register, not localhost or an old hostname. The underlying absolute-URL behavior is tracked in Simple OAuth 2.1 issue #21.
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 an existing install

Recipes are apply-time configuration, so updating the Composer package alone does not update active configuration. Existing installs must update the packages and apply the main recipe again. After updating the packages, an install made from an earlier 1.0.x-dev revision must run the bundled development migration before the main recipe. The migration prepares the two retained tool configs for strict comparison and disables the third tool shipped by the earlier public development revision.

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

Package info

Security

Statistics