MCP Server Key Auth

MCP Server Key Auth adds per-user API key authentication to the MCP Server HTTP endpoint using Key Auth. AI assistants and automation clients send a user's API key in a request header and operate with that user's Drupal permissions.

Use this module with MCP clients that support manually configured HTTP headers, when you want a simple API key connection without setting up an OAuth authorization server.

Features

• Reuses Key Auth for user API key generation, rotation and revocation.
• Requires header credentials on every MCP request, including requests carrying a session ID. Supports custom header names.
• Rejects query-string keys, cookie-only logins and session-ID-only requests at the MCP endpoint, without changing global Key Auth settings.
• Retains MCP Server endpoint permissions and tool-specific access checks.
• Isolates MCP session storage by the acting Drupal user.
• Returns JSON-RPC authentication errors with HTTP 401/403 status codes.
• Works without Tool Bridge, Tool API or an AI provider dependency.

Post-installation

1. Enable this module and its dependencies.
2. At /admin/config/services/key-auth, enable Header detection. The default header name is api-key.
3. Grant the intended account Access MCP server and Use key authentication, plus the permissions needed by its tools.
4. Generate a user key at /user/{uid}/key-auth. Grant the own-key management permissions if users should manage their keys.
5. Configure the MCP client with https://example.com/mcp and an api-key header. Send the header on every request and use HTTPS remotely.

Requirements

• Drupal 11 and PHP 8.3 or later within PHP 8.x.
• MCP Server 2.x, version 2.0.0-beta6 or later.
• Key Auth 2.2.4 or later in the 2.x series.

Related projects and authentication policy

MCP Server OAuth provides OAuth authentication and tool scope checks. Choose it when clients require an OAuth login/discovery flow. While MCP Server Key Auth is enabled, the MCP HTTP endpoint is key-only; cookie and OAuth authentication do not authorize that endpoint. Other routes and STDIO authentication are unchanged.

Enabling or uninstalling this module changes session storage IDs. Reconnect clients to initialize fresh sessions. See the repository README for installation, configuration, session behavior and testing instructions.