Add oauth 2.1 documentation (#460)

* docs: add comprehensive OAuth 2.1 documentation

- Update Claude.ai client docs with full OAuth setup guide
  - Two authentication methods: OAuth (recommended) vs token-based
  - Step-by-step OAuth server setup (Docker, uvx)
  - Environment variables documentation
  - Claude.ai connector setup instructions

- Update Docker deployment docs with OAuth mode
  - New "For Remote Access (OAuth Mode)" section
  - OAuth environment variables table
  - Encryption key generation instructions
  - Server mode comparison table

- Update FAQ with OAuth troubleshooting
  - OAuth vs token-based comparison
  - Common OAuth errors and solutions
  - OAuth environment variables reference

- Update README with OAuth feature mention

Closes #245

* docs: add port clarification and add-on OAuth notes

- Clarify HA port (8123) vs ha-mcp port (8086/9583)
- Document that add-on does not support OAuth mode yet
- Add HAOS Docker workaround for OAuth users

* docs: fix HAOS Docker instructions (not possible)

HAOS does not allow direct Docker CLI access. Updated
documentation with accurate alternatives:
- Separate device on network (Pi, NAS, PC)
- Cloud/VPS deployment
- HA Container installation (has Docker access)

* docs: clarify OAuth vs token provides same API permissions

Add note explaining that both authentication methods provide
identical Home Assistant API access. Switching auth methods
won't resolve API errors like 405 - those are HA Core issues.

* test: add HACS availability check before install tests

Add pre-flight HACS availability check using ha_hacs_info before
attempting HACS install operations. This prevents flaky test failures
when HACS is rate-limited or temporarily unavailable.

Affects:
- test_install_mcp_tools_basic
- test_install_mcp_tools_idempotent
- test_check_mcp_tools_in_hacs

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: kingpanther13

README.md

@@ -108,6 +108,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **🔧 Manage** | Automations, scripts, helpers, dashboards, areas, zones, groups, calendars, blueprints |
 | **📊 Monitor** | History, statistics, camera snapshots, automation traces, ZHA devices |
 | **💾 System** | Backup/restore, updates, add-ons, device registry |
+| **🔐 Auth** | OAuth 2.1 with DCR for secure multi-user access (Claude.ai), token-based for local clients |
 
 <details>
 <summary><b>🛠️ Complete Tool List (82 tools)</b></summary>

docs/FAQ.md

@@ -26,6 +26,28 @@ You can also use ha-mcp with other AI clients. See the [Setup Wizard](https://ho
 
 Built-in = operate devices. ha-mcp = administer your system.
 
+### What's the difference between OAuth and token-based authentication?
+
+| Feature | Token-Based | OAuth 2.1 |
+|---------|-------------|-----------|
+| **Setup** | Configure token in server environment | Users enter credentials via consent form |
+| **Best for** | Single user, local clients (Claude Desktop) | Multi-user, remote clients (Claude.ai) |
+| **Credentials stored** | In server config | Encrypted in user's session token |
+| **Server command** | `ha-mcp` or `ha-mcp-web` | `ha-mcp-oauth` |
+| **HTTPS required** | No (but recommended) | Yes (for production) |
+
+**When to use OAuth:**
+- Hosting ha-mcp for multiple users
+- Using Claude.ai (web) as your client
+- Exposing ha-mcp over the internet
+
+**When to use token-based:**
+- Single-user setup
+- Local/LAN access only
+- Claude Desktop or other local clients
+
+> **Note:** Both methods provide **identical API permissions**. OAuth is about *how* you authenticate, not *what* you can do. The underlying Home Assistant REST API access is the same. If you encounter API errors (like 405 Method Not Allowed), switching auth methods won't help - the issue is with the HA API itself, not the authentication.
+
 ---
 
 ## Try Without Your Own Home Assistant
@@ -129,16 +151,108 @@ source ~/.zshrc
 
 ---
 
+## OAuth Troubleshooting
+
+### OAuth consent form not loading
+
+1. **Check MCP_BASE_URL** - Must be set to your public HTTPS URL
+2. **Verify HTTPS** - OAuth requires HTTPS in production
+3. **Check tunnel** - Ensure Cloudflare Tunnel or similar is running
+
+### "Invalid credentials" on consent form
+
+1. **Verify Home Assistant URL:**
+   - Include protocol: `http://` or `https://`
+   - Include port if not default: `:8123`
+   - Don't include trailing slash
+   - Example: `http://homeassistant.local:8123`
+
+2. **Verify Long-Lived Access Token:**
+   - Generate a fresh token in HA → Profile → Security → Long-lived access tokens
+   - Copy the full token (it's long!)
+   - Token is validated against HA's `/api/config` endpoint
+
+3. **Check network connectivity:**
+   - The ha-mcp server must be able to reach your Home Assistant
+   - If using Docker, ensure HA is accessible from the container
+
+### OAuth session expired / logged out unexpectedly
+
+1. **Check OAUTH_ENCRYPTION_KEY:**
+   - If not set, tokens are invalidated on server restart
+   - Generate a persistent key:
+     ```bash
+     python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+     ```
+   - Add to your environment: `OAUTH_ENCRYPTION_KEY=your-generated-key`
+
+2. **Token expiration times:**
+   - Access tokens: 1 hour (auto-refresh)
+   - Refresh tokens: 7 days
+   - Re-authenticate if refresh token expires
+
+### OAuth redirect loop or "invalid_grant" error
+
+1. **Clear browser cookies** for your ha-mcp domain
+2. **Check MCP_BASE_URL matches your actual URL** (including https://)
+3. **Verify no URL path mismatch** between MCP_BASE_URL and tunnel config
+
+### Claude.ai shows "401 Unauthorized"
+
+1. **Ensure you're using OAuth mode:** Server should run `ha-mcp-oauth`
+2. **Check the connector URL in Claude.ai** ends with `/mcp`
+3. **Try removing and re-adding the connector**
+
+### Understanding the ports (HA vs ha-mcp)
+
+There are **two different services** with different ports:
+
+| Service | Default Port | Purpose |
+|---------|--------------|---------|
+| **Home Assistant** | 8123 | HA web UI and REST API |
+| **ha-mcp server** | 8086 (Docker/uvx) or 9583 (add-on) | MCP server for AI clients |
+
+- In the **OAuth consent form**, you enter your **Home Assistant URL** (port 8123)
+- In **Claude.ai connector settings**, you enter the **ha-mcp server URL** (via HTTPS tunnel)
+
+### Can I use OAuth with the Home Assistant add-on?
+
+**Not currently.** The ha-mcp Home Assistant add-on runs in token mode only, using the Supervisor API for authentication.
+
+**Important:** HAOS does not allow running custom Docker containers directly - there's no `docker` CLI access. To use OAuth mode with HAOS, you need to run ha-mcp on a separate device:
+
+**Alternatives for HAOS users:**
+
+1. **Separate device on your network** - Run ha-mcp OAuth on a Raspberry Pi, NAS, or always-on PC that has Docker installed
+2. **Cloud/VPS** - Deploy ha-mcp OAuth on a cloud server with HTTPS
+3. **Switch to HA Container** - If you use [Home Assistant Container](https://www.home-assistant.io/installation/linux#docker-compose) instead of HAOS, you have full Docker access
+
+In all cases, the ha-mcp OAuth server needs network access to your Home Assistant instance to validate credentials.
+
+---
+
 ## Configuration Options
 
-### Environment Variables
+### Environment Variables (Token Mode)
 
 | Variable | Description | Default | Required |
 |----------|-------------|---------|----------|
 | `HOMEASSISTANT_URL` | Your Home Assistant URL | - | Yes |
 | `HOMEASSISTANT_TOKEN` | Long-lived access token (or `demo` for demo env) | - | Yes |
 | `BACKUP_HINT` | Backup recommendation level | `normal` | No |
 
+### Environment Variables (OAuth Mode)
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `MCP_BASE_URL` | Public HTTPS URL of your server | `http://localhost:8086` | Yes (production) |
+| `MCP_PORT` | Server port | `8086` | No |
+| `MCP_SECRET_PATH` | MCP endpoint path | `/mcp` | No |
+| `OAUTH_ENCRYPTION_KEY` | 32-byte base64 key for token encryption | Auto-generated | Recommended |
+| `LOG_LEVEL` | Logging verbosity (DEBUG, INFO, WARNING, ERROR) | `INFO` | No |
+
+> **Note:** In OAuth mode, `HOMEASSISTANT_URL` and `HOMEASSISTANT_TOKEN` are NOT required - users provide credentials via the consent form.
+
 ### Backup Hint Modes
 
 | Mode | Behavior |

site/src/content/clients/claude-ai.md

@@ -9,38 +9,171 @@ order: 8
 httpNote: Requires HTTPS - Remote deployment required
 ---
 
-## Configuration
+## Overview
 
-Claude.ai (web interface) supports MCP servers via the Connectors feature.
+Claude.ai (web interface) supports MCP servers via the Connectors feature. **ha-mcp supports OAuth 2.1 authentication**, providing a seamless zero-config experience for Claude.ai users.
 
 **Requirements:**
 - HTTPS URL (HTTP not supported)
 - Claude Pro, Max, Team, or Enterprise subscription
 - Remote server with secure tunnel
 
-### Setup Steps
+## Authentication Methods
+
+| Method | Best For | Credentials Stored |
+|--------|----------|-------------------|
+| **OAuth 2.1** (Recommended) | Multiple users, secure access | Per-user, via consent form |
+| **Pre-configured Token** | Single user, simpler setup | In server environment |
+
+---
+
+## Option 1: OAuth Mode (Recommended)
+
+OAuth mode provides **secure, zero-config authentication**. Users enter their Home Assistant credentials via a consent form when connecting.
+
+### How OAuth Works
+
+1. You add ha-mcp as a connector in Claude.ai
+2. Claude.ai redirects to the ha-mcp consent form
+3. You enter your Home Assistant URL and Long-Lived Access Token
+4. Credentials are validated against your HA instance
+5. You're connected! Credentials are encrypted in your session token
+
+### Server Setup
+
+**Using Docker:**
+
+```bash
+docker run -d --name ha-mcp-oauth \
+  -p 8086:8086 \
+  -e MCP_BASE_URL=https://your-public-url.com \
+  -e OAUTH_ENCRYPTION_KEY=your-32-byte-base64-key \
+  ghcr.io/homeassistant-ai/ha-mcp:latest \
+  ha-mcp-oauth
+```
+
+**Using uvx:**
+
+```bash
+MCP_BASE_URL=https://your-public-url.com \
+OAUTH_ENCRYPTION_KEY=your-32-byte-base64-key \
+uvx ha-mcp@latest ha-mcp-oauth
+```
+
+### Environment Variables for OAuth
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `MCP_BASE_URL` | Public HTTPS URL of your server | `http://localhost:8086` | **Yes** (for production) |
+| `MCP_PORT` | Server port | `8086` | No |
+| `MCP_SECRET_PATH` | MCP endpoint path | `/mcp` | No |
+| `OAUTH_ENCRYPTION_KEY` | 32-byte base64 key for token encryption | Auto-generated | **Recommended** |
+| `LOG_LEVEL` | Logging verbosity | `INFO` | No |
+
+> **Note:** If `OAUTH_ENCRYPTION_KEY` is not set, a temporary key is generated. Tokens will be invalidated on server restart. For production, generate a persistent key:
+> ```bash
+> python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+> ```
+
+### Expose Server with HTTPS
+
+Claude.ai requires HTTPS. Use a secure tunnel:
+
+**Quick Tunnel (Testing):**
+```bash
+cloudflared tunnel --url http://localhost:8086
+# Gives you: https://random-words.trycloudflare.com
+# MCP URL: https://random-words.trycloudflare.com/mcp
+```
+
+**Persistent Tunnel:** See [Cloudflare Tunnel documentation](/setup?connection=remote&deployment=cloudflared)
+
+### Connect in Claude.ai
 
 1. Open [Claude.ai](https://claude.ai)
 2. Go to **Settings** → **Connectors**
 3. Click **Add custom connector**
 4. Enter:
    - **Name:** Home Assistant
-   - **URL:** `{{MCP_SERVER_URL}}` (must be HTTPS)
+   - **URL:** `https://your-public-url.com/mcp`
 5. Click **Add**
-6. Authenticate if OAuth is required
+6. You'll be redirected to the ha-mcp consent form
+7. Enter your Home Assistant URL (e.g., `http://homeassistant.local:8123`)
+8. Enter your Long-Lived Access Token ([How to get a token](/faq#token-invalid-or-authentication-errors))
+9. Click **Authorize**
+10. You're connected!
+
+### Understanding the Ports
+
+When using OAuth, there are **two different services** with different ports:
 
-### Important
+| Service | Default Port | What You Enter |
+|---------|--------------|----------------|
+| **Home Assistant** | 8123 | In the OAuth consent form (your HA URL) |
+| **ha-mcp server** | 8086 | In Claude.ai connector settings (via HTTPS tunnel) |
 
-Claude.ai **only supports HTTPS** - you cannot use HTTP URLs. You'll need to set up a secure tunnel (see Remote deployment options).
+The consent form asks for your **Home Assistant URL** (port 8123) - this is where ha-mcp makes API calls to control your smart home. The ha-mcp server itself runs on port 8086 (or custom).
+
+### Home Assistant Add-on Note
+
+> **Important:** The ha-mcp Home Assistant add-on does **not currently support OAuth mode**. The add-on runs in token mode using the Supervisor API for authentication.
+>
+> **Note:** HAOS does not allow running custom Docker containers directly (no `docker` CLI access). To use OAuth mode, you'll need one of these alternatives:
+>
+> **Option A: Separate device on your network**
+> Run ha-mcp OAuth on another device (Raspberry Pi, NAS, always-on PC):
+> ```bash
+> docker run -d --name ha-mcp-oauth \
+>   -p 8086:8086 \
+>   -e MCP_BASE_URL=https://your-cloudflare-tunnel.com \
+>   -e OAUTH_ENCRYPTION_KEY=your-key \
+>   ghcr.io/homeassistant-ai/ha-mcp:latest \
+>   ha-mcp-oauth
+> ```
+>
+> **Option B: Cloud/VPS**
+> Deploy ha-mcp OAuth on a cloud server (AWS, DigitalOcean, etc.) with HTTPS.
+>
+> **Option C: Home Assistant Container installation**
+> If you're using [HA Container](https://www.home-assistant.io/installation/linux#docker-compose) (not HAOS), you have full Docker access and can run ha-mcp OAuth alongside HA.
+>
+> In all cases, the ha-mcp OAuth server needs network access to your Home Assistant instance.
+
+---
+
+## Option 2: Pre-configured Token Mode
+
+For single-user setups where you want to skip the OAuth consent form.
+
+### Server Setup
+
+```bash
+docker run -d --name ha-mcp \
+  -p 8086:8086 \
+  -e HOMEASSISTANT_URL=http://homeassistant.local:8123 \
+  -e HOMEASSISTANT_TOKEN=your_long_lived_token \
+  ghcr.io/homeassistant-ai/ha-mcp:latest \
+  ha-mcp-web
+```
+
+### Connect in Claude.ai
+
+1. Expose with HTTPS (see above)
+2. Add connector with URL: `https://your-public-url.com/mcp`
+3. No OAuth flow - connects directly using pre-configured credentials
+
+---
 
 ## Supported Transports
 
+- **Streamable HTTP** - Supported (recommended, used by OAuth mode)
 - **SSE (Server-Sent Events)** - Supported
-- **Streamable HTTP** - Supported (recommended)
 
 ## Notes
 
 - Web-based configuration only (no config file)
-- Requires HTTPS endpoint (Remote deployment required)
+- Requires HTTPS endpoint (remote deployment required)
 - Remote MCP Connectors are currently in beta
 - Use the "Search and tools" button in chat to enable/disable specific tools
+- OAuth tokens expire after 1 hour (auto-refresh supported)
+- Refresh tokens valid for 7 days