[BUG] Oauth Failing on /mcp/authorize with "Not Found"

[dandomin]

📋 Bug Description

When trying to use the new OAUTH feature, FastMCP is responding with a "Not Found" error when clients try to go to https://url/mcp/authorize

🔄 Steps to Reproduce

1. Setup tunnel through CloudFlare
2. Run MCP_BASE_URL=https://URLFROMABOVE/mcp uvx --from ha-mcp@latest ha-mcp-oauth
3. Attempt to connect in either Claude or ChatGPT - both fail with the Not Found error
4. Even going direct to the /mcp/authorize URL locally results in same failure, so it's definitely not related to the cloudflare tunnel

✅ Expected vs ❌ Actual Behavior

Expected:
Oauth page loads to authorize access for MCP to HA

Actual:
"Not Found" returned in both Claude and ChatGPT

---

🔧 Environment

• **ha-mcp Version:**6.3.1
• Installation Method: UV
• Platform: MacOS
• Python Version:
• Home Assistant Version: 2026.1
• Connection Status:
• Entity Count:

---

🚨 Error Messages

<!-- Paste error messages here -->
INFO:     160.79.106.0:0 - "GET /.well-known/oauth-authorization-server HTTP/1.1" 200 OK
INFO:     67.183.172.88:0 - "GET /mcp/authorize?response_type=code&client_id=https%3A%2F%2Fclaude.ai&redirect_uri=https%3A%2F%2Fclaude.ai%2Fapi%2Fmcp%2Fauth_callback&code_challenge=uUQ99rjoawsz7KQMjiPrJcWfCqy_liyIh4OcsdF_uxE&code_challenge_method=S256&state=zZ6q_j3HRtuindWVlJqMbJ9iLSFUX4jDRCocaykzmuk&scope=homeassistant+mcp HTTP/1.1" 404 Not Found

---

---

🚀 Startup Logs (if relevant)

Click to expand startup logs

bash-3.2$ MCP_BASE_URL=https://nuke-semi-recordings-keyword.trycloudflare.com/mcp uvx --from ha-mcp@6.3.1 ha-mcp-oauth
2026-01-21 20:52:32,651 ha_mcp.__main__ INFO: ✅ OAuth mode logging configured at INFO level
2026-01-21 20:52:32,652 ha_mcp.auth.provider WARNING: No OAUTH_ENCRYPTION_KEY set - generated temporary key. Tokens will be invalid after server restart. Set OAUTH_ENCRYPTION_KEY for persistence.
2026-01-21 20:52:32,652 ha_mcp.auth.provider INFO: HomeAssistantOAuthProvider initialized with base_url=https://old-words-removed.trycloudflare.com/mcp
2026-01-21 20:52:32,717 ha_mcp.tools.registry INFO: Auto-discovery registered tools from 33 modules
2026-01-21 20:52:32,717 ha_mcp.__main__ INFO: ✅ Server created with OAuthProxyClient
2026-01-21 20:52:32,717 ha_mcp.__main__ INFO: Starting OAuth-enabled MCP server with 100 tools on https://old-words-removed.trycloudflare.com/mcp/mcp


[01/21/26 20:52:32] INFO     Starting MCP server 'ha-mcp' with    server.py:2585
                             transport 'streamable-http' on                     
                             http://0.0.0.0:8086/mcp                            
INFO:     Started server process [66008]
INFO:     Waiting for application startup.
2026-01-21 20:52:32,762 docket.worker INFO: Starting worker 'Daniels-Mac-mini.local#66008' with the following tasks:
2026-01-21 20:52:32,763 docket.worker INFO: * trace(message: str, ...)
2026-01-21 20:52:32,763 docket.worker INFO: * fail(message: str, ...)
2026-01-21 20:52:32,763 docket.worker INFO: * sleep(seconds: float, ...)
2026-01-21 20:52:32,763 mcp.server.streamable_http_manager INFO: StreamableHTTP session manager started
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8086 (Press CTRL+C to quit)

---

💡 Additional Context

---

Privacy reminder: Please review and anonymize sensitive information (tokens, IPs, personal names) before submitting.

[julienld]

Root Cause Identified

I've successfully reproduced this issue. The problem is incorrect MCP_BASE_URL configuration.

The Issue

When you set:

MCP_BASE_URL=https://nuke-semi-recordings-keyword.trycloudflare.com/mcp

You're including the /mcp path in the base URL, which causes 404 errors.

Solution

Don't include /mcp in your MCP_BASE_URL:

# ✅ Correct
MCP_BASE_URL=https://nuke-semi-recordings-keyword.trycloudflare.com
uvx ha-mcp@latest ha-mcp-oauth

# ❌ Wrong
MCP_BASE_URL=https://nuke-semi-recordings-keyword.trycloudflare.com/mcp
uvx ha-mcp@latest ha-mcp-oauth

Then use https://nuke-semi-recordings-keyword.trycloudflare.com/mcp as the connector URL in Claude.ai.

Documentation Updates

While investigating this, I discovered OAuth documentation wasn't clearly positioned. I've created PR #487 which:

1. Moves OAuth to separate guide - docs/OAUTH.md
2. Focuses main docs on private URL method - the stable, recommended approach
3. Adds comprehensive OAuth troubleshooting including this 404 error

The new OAuth guide includes complete setup instructions, troubleshooting, and explains when to use OAuth vs the private URL method.

[github-actions]

This issue is stale because it has been open for 30 days with no activity.

[kingpanther13]

@julienld since the new oauth changes are out with 7.0 and tou updated documentation, is this issue still relevant or can it be closed? I'm just trying to go thru and close some old issues to prune the list