MCP troubleshooting

• 404 on /mcp or on /.well-known/...
• 401 with WWW-Authenticate: Bearer
• invalid_scope or the consent page shows no permissions
• The client connects but a tool is missing
• The redirect fails for Claude Code or another local client
• Wrong URLs in OAuth metadata behind a proxy
• isError: true with "Tool failed"
• -32601, -32700, HTTP 405
• Still stuck?

404 on /mcp or on /.well-known/...

The MCP server is off. Tick Enable MCP server in Administration → Plugins → Redmine Agent → Configure and restart nothing: the routes appear at once.

401 with WWW-Authenticate: Bearer

• The token is missing, expired or revoked: reconnect the client.
• The REST web service is off: enable it in Administration → Settings → API. Core Redmine accepts OAuth tokens and API keys only when it is on.
• An API key was used but Allow MCP access with API key is off.
• Send the key in the header (Authorization: Bearer or X-Redmine-API-Key), never in the query string.

invalid_scope or the consent page shows no permissions

Use the server URL (https://your-redmine.example.com/mcp) in the client so that it discovers the /mcp/authorize endpoint, which narrows the requested scopes to the ones ticked in the application. Opening /oauth/authorize directly with scopes the application does not allow answers invalid_scope. Tick the needed scopes in Administration → Applications.

The client connects but a tool is missing

The tool needs a permission that the token scopes or the user's roles do not give. Check the ticked scopes of the application, the role of the user in the project, and re-authorize the client after changing scopes. Tools of other plugins appear only when those plugins are installed and enabled.

The redirect fails for Claude Code or another local client

Use 127.0.0.1 or a fixed callback port with localhost and register exactly that address as the redirect URI of the application.

Wrong URLs in OAuth metadata behind a proxy

Metadata URLs are built from Host name and path and Protocol in Administration → Settings → General. Set them to the public address, with HTTPS.

isError: true with "Tool failed"

An unexpected error in the handler: internals are not shown to the client. Look at the Rails log (Agent hook and exception lines).

-32601, -32700, HTTP 405

-32700: invalid JSON; -32601: unknown method; GET /mcp answers 405 because the server does not open a server-to-client stream. Send JSON-RPC with POST.

Still stuck?

Contact support with the Redmine and plugin version, the client name and the failing request.