Skip to content

MCP Authentication

The MCP endpoint uses the standard Easy8 API authentication model.

  • POST /mcp accepts API authentication
  • API-key authentication requires the Easy8 REST API to be enabled
  • use an Easy8 API key in X-Redmine-API-Key, X-Easy8-API-Key, or Authorization: Bearer <api-key>
  • ?key=<api-key> is also accepted, but headers are preferred
  • use an Easy8 OAuth access token in Authorization: Bearer <access-token>
  • HTTP Basic credentials are not accepted by /mcp
  • permissions are still enforced by Easy8 visibility and authorization rules

Example:

POST /mcp HTTP/1.1
Host: your-easy8.example.com
Content-Type: application/json
X-Easy8-API-Key: <your-api-key>

Equivalent alternatives:

X-Redmine-API-Key: <your-api-key>

Authorization: Bearer <your-api-key>

Authorization: Bearer <oauth-access-token>

If the API credential is missing or invalid, the endpoint returns 401 Unauthorized.

OAuth discovery metadata

Easy8 also publishes OAuth discovery metadata for agents that need to discover how MCP authentication should work:

  • /.well-known/oauth-authorization-server - OAuth authorization server metadata
  • /.well-known/oauth-protected-resource - OAuth protected resource metadata for the MCP resource
  • /.well-known/oauth-protected-resource/mcp - path-specific protected resource metadata for /mcp
  • /.well-known/jwks.json - JSON Web Key Set endpoint; currently empty because Easy8 OAuth access tokens are opaque tokens
  • /auth.md - agent-facing registration instructions
  • /oauth2/register - OAuth Dynamic Client Registration endpoint

When POST /mcp receives an unauthenticated request, it includes a WWW-Authenticate challenge with the protected resource metadata URL:

WWW-Authenticate: Bearer resource_metadata="https://your-easy8.example.com/.well-known/oauth-protected-resource", scope="mcp"

The metadata advertises OAuth Dynamic Client Registration, manual OAuth client registration, and S256 PKCE for authorization-code clients.

User identity

MCP tools use the effective Easy8 API user as me.

  • with a personal API key, me is the owner of that key
  • with an OAuth access token, me is the user who authorized the OAuth client
  • with an admin API key and no X-Redmine-Switch-User header, me is the admin
  • with an admin API key and X-Redmine-Switch-User, me is the switched active user
  • Setting.sys_api_key is not used for MCP authentication

Use easy8_users_me when the client needs to inspect the effective user explicitly.

Example admin switch-user request:

POST /mcp HTTP/1.1
Host: your-easy8.example.com
Content-Type: application/json
X-Easy8-API-Key: <admin-api-key>
X-Redmine-Switch-User: <user-login>

Permission model

The API key only identifies the effective user. It does not bypass Easy8 permissions.

  • visibility checks use standard Easy8 visibility rules
  • tool actions respect regular Easy8 permissions such as issue creation and editing
  • project-specific workflow restrictions and required custom fields still apply
  • read-only API keys can call read tools, but write tools return a tool-level Permission denied error