mcp-nextcloud/docs/oauth-troubleshooting.md

# OAuth Troubleshooting

This guide covers OAuth-specific issues and solutions for the Nextcloud MCP server.

For general troubleshooting, see [Troubleshooting Guide](troubleshooting.md).

## Quick Diagnosis

Start here to identify your issue:

| Symptom | Likely Cause | Quick Fix Link |
|---------|--------------|----------------|
| "OAuth mode requires NEXTCLOUD_HOST" | Missing environment variable | [Missing NEXTCLOUD_HOST](#missing-nextcloud_host) |
| "OAuth mode requires client credentials OR dynamic registration" | OIDC apps not configured | [Missing OIDC Apps](#missing-or-misconfigured-oidc-apps) |
| "PKCE support validation failed" | OIDC app doesn't advertise PKCE | [PKCE Not Advertised](#pkce-not-advertised) |
| "Stored client has expired" | Dynamic client expired | [Client Expired](#client-expired) |
| Only seeing Notes tools (7 instead of 90+) | Limited OAuth scopes granted | [Limited Scopes](#limited-scopes---only-seeing-notes-tools) |
| HTTP 401 for Notes API | Bearer token patch missing | [Bearer Token Auth Fails](#bearer-token-authentication-fails) |
| "OIDC discovery failed" | Network or configuration issue | [Discovery Failed](#oidc-discovery-failed) |
| "Database error" on OAuth client storage | Database permissions issue | [Database Permission Error](#database-permission-error) |

## Configuration Issues

### Missing NEXTCLOUD_HOST

**Error Message**:
```
OAuth mode requires NEXTCLOUD_HOST environment variable
```

**Cause**: The `NEXTCLOUD_HOST` environment variable is not set or empty.

**Solution**:

1. Add to your `.env` file:
   ```bash
   NEXTCLOUD_HOST=https://your.nextcloud.instance.com
   ```

2. Reload environment variables:
   ```bash
   export $(grep -v '^#' .env | xargs)
   ```

3. Verify it's set:
   ```bash
   echo $NEXTCLOUD_HOST
   # Should output: https://your.nextcloud.instance.com
   ```

---

### Missing or Misconfigured OIDC Apps

**Error Message**:
```
OAuth mode requires either client credentials OR dynamic client registration
```

**Cause**: The required Nextcloud OIDC apps are either:
- Not installed
- Not enabled
- Missing configuration

**Solution**:

**Step 1**: Verify both apps are installed:

```bash
# Check installed apps
php occ app:list | grep -E "oidc|user_oidc"

# Should show:
#  - oidc: enabled
#  - user_oidc: enabled
```

If not installed:
1. Open Nextcloud as administrator
2. Navigate to **Apps** → **Security**
3. Install **"OIDC"** (OIDC Identity Provider)
4. Install **"OpenID Connect user backend"** (user_oidc)
5. Enable both apps

**Step 2**: Enable dynamic client registration:

1. Go to **Settings** → **OIDC** (Administration)
2. Enable **"Allow dynamic client registration"**

**Step 3**: Configure Bearer token validation:

```bash
php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
```

**Step 4**: Verify discovery endpoint:

```bash
curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '.registration_endpoint'

# Should output:
# "https://your.nextcloud.instance.com/apps/oidc/register"
```

**Alternative**: Use pre-configured client credentials:

```bash
# Register client via CLI
php occ oidc:create \
  --name="Nextcloud MCP Server" \
  --type=confidential \
  --redirect-uri="http://localhost:8000/oauth/callback"

# Add to .env
echo "NEXTCLOUD_OIDC_CLIENT_ID=<client-id>" >> .env
echo "NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>" >> .env
```

---

### Client Expired

**Error Message**:
```
Stored client has expired
```

**Cause**: Dynamically registered OAuth clients expire (default: 1 hour).

**Solution**:

**Option 1: Restart the Server** (Automatic re-registration)

```bash
uv run nextcloud-mcp-server --oauth
# Server automatically re-registers if credentials expired
```

**Option 2: Use Pre-configured Credentials** (Recommended for production)

```bash
# Register permanent client via Nextcloud CLI
php occ oidc:create \
  --name="Nextcloud MCP Server" \
  --type=confidential \
  --redirect-uri="http://localhost:8000/oauth/callback"

# Add to .env
NEXTCLOUD_OIDC_CLIENT_ID=<from-output>
NEXTCLOUD_OIDC_CLIENT_SECRET=<from-output>
```

Pre-configured clients don't expire.

**Option 3: Increase Expiration Time**

```bash
# Via Nextcloud CLI (default: 3600 seconds = 1 hour)
php occ config:app:set oidc expire_time --value "86400"  # 24 hours
```

---

### Database Permission Error

**Error Message**:
```
Permission denied when accessing SQLite database
Database is locked
```

**Cause**: The server cannot access the SQLite database file.

**Solution**:

```bash
# Check database directory permissions
ls -la /app/data/

# Ensure directory is writable
chmod 755 /app/data

# Check if database file exists and has correct permissions
ls -la /app/data/tokens.db
chmod 644 /app/data/tokens.db

# If running in Docker, ensure volume is mounted correctly
docker compose logs mcp-oauth | grep -i "database\|sqlite"
```

**For Docker deployments**:
Ensure the data directory is properly mounted as a volume:
```yaml
volumes:
  - ./data:/app/data  # Persistent storage for SQLite database
```

---

## Discovery and Connection Issues

### OIDC Discovery Failed

**Error Message**:
```
OIDC discovery failed
Cannot reach OIDC discovery endpoint
```

**Cause**: The server cannot reach the Nextcloud OIDC discovery endpoint.

**Solution**:

**Step 1**: Verify Nextcloud URL is correct:

```bash
echo $NEXTCLOUD_HOST
# Should be full URL: https://your.nextcloud.instance.com
```

**Step 2**: Test discovery endpoint manually:

```bash
curl https://your.nextcloud.instance.com/.well-known/openid-configuration

# Should return JSON with OIDC configuration
# {
#   "issuer": "https://your.nextcloud.instance.com",
#   "authorization_endpoint": "https://your.nextcloud.instance.com/apps/oidc/authorize",
#   ...
# }
```

**Step 3**: Check network connectivity:

```bash
# Test basic connectivity
ping your.nextcloud.instance.com

# Test HTTPS
curl -I https://your.nextcloud.instance.com
```

**Step 4**: Verify both OIDC apps are enabled:

```bash
php occ app:list | grep -E "oidc|user_oidc"
```

**Step 5**: Check firewall rules (if using Docker):

```bash
# Check if MCP server can reach Nextcloud
docker exec nextcloud-mcp-server curl https://your.nextcloud.instance.com/.well-known/openid-configuration
```

---

## Authentication Issues

### Bearer Token Authentication Fails

**Error Message**:
```
HTTP 401 Unauthorized when calling Nextcloud APIs
```

**Symptoms**:
- OCS APIs work (`/ocs/v2.php/cloud/capabilities`)
- App APIs fail (`/apps/notes/api/`, `/apps/calendar/`, etc.)

**Cause**: The `user_oidc` app's CORS middleware interferes with Bearer token authentication for non-OCS endpoints.

**Solution**: Apply the Bearer token patch to `user_oidc` app.

See [Upstream Status](oauth-upstream-status.md#1-bearer-token-support-for-non-ocs-endpoints) for details.

**Quick Patch**:

```bash
# SSH into Nextcloud server
cd /path/to/nextcloud/apps/user_oidc

# Edit lib/User/Backend.php
# Add this line before each return statement in getCurrentUserId() method:
$this->session->set('app_api', true);

# Lines to modify: ~243, ~310, ~315, ~337
```

**Test the fix**:

```bash
# Get an OAuth token (from MCP client or test)
TOKEN="your_access_token"

# Test Notes API
curl -H "Authorization: Bearer $TOKEN" \
  https://your.nextcloud.instance.com/apps/notes/api/v1/notes

# Should return notes JSON (not 401)
```

---

### PKCE Not Advertised

**Error Message**:
```
ERROR: OIDC CONFIGURATION ERROR - Missing PKCE Support Advertisement
⚠️  MCP clients (like Claude Code) WILL REJECT this provider!
```

**Cause**: The OIDC discovery endpoint doesn't include `code_challenge_methods_supported` field.

**Impact**:
- Some MCP clients may refuse to connect
- Standards compliance issue (RFC 8414)
- **Functionality still works** (PKCE is accepted, just not advertised)

**Solution**:

**Short-term**: The MCP server logs a warning but continues. OAuth flow still works.

**Long-term**: Update the `oidc` app to advertise PKCE support.

See [Upstream Status](oauth-upstream-status.md#2-pkce-support-advertisement-in-discovery) for tracking.

**Verify**:

```bash
curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '.code_challenge_methods_supported'

# Should return:
# ["S256", "plain"]

# If null, PKCE isn't advertised (but still works)
```

---

## Runtime Issues

### MCP Client Can't Authenticate

**Symptoms**:
- Client connects but OAuth flow fails
- Authorization redirects don't work
- Token exchange fails

**Diagnosis**:

**Step 1**: Verify OAuth is configured correctly:

```bash
uv run nextcloud-mcp-server --oauth --log-level debug
```

Look for:
```
INFO     OAuth initialization complete
INFO     MCP server ready at http://127.0.0.1:8000
```

**Step 2**: Check OIDC discovery:

```bash
curl https://your.nextcloud.instance.com/.well-known/openid-configuration
```

**Step 3**: Verify MCP server URL matches client expectations:

```bash
echo $NEXTCLOUD_MCP_SERVER_URL
# Should match the URL clients use to connect
# Default: http://localhost:8000
```

If MCP server is on a different host/port, update:
```bash
NEXTCLOUD_MCP_SERVER_URL=http://actual-host:actual-port
```

**Step 4**: Check redirect URI configuration:

For pre-configured clients, ensure redirect URI matches:
```bash
# Client redirect URI should be:
http://your-mcp-server-url/oauth/callback

# Example for local server:
http://localhost:8000/oauth/callback
```

---

### Tools Return 401 Errors

**Symptoms**:
- OAuth flow completes successfully
- Token is valid
- MCP tools return 401 errors

**Cause**: Bearer token not working with Nextcloud APIs.

**Solution**: See [Bearer Token Authentication Fails](#bearer-token-authentication-fails) above.

---

### Limited Scopes - Only Seeing Notes Tools

**Symptoms**:
- MCP client (e.g., Claude Code) successfully connects via OAuth
- Only Notes tools are available (7 tools instead of 90+)
- Token scopes show only `mcp:notes.read` and `mcp:notes.write`

**Cause**: During the OAuth consent flow, the user only granted access to Notes scopes, or the client only requested those scopes.

**Diagnosis**:

Check what scopes the client has been granted:

```bash
# View registered clients and their allowed scopes
php occ oidc:list | jq '.[] | select(.name | contains("Claude Code")) | {name, allowed_scopes}'
```

Look for the client's `allowed_scopes` field. If it's empty or only contains notes scopes, that's the issue.

**Solution**:

**Option 1: Delete Client and Reconnect** (Recommended for MCP clients)

```bash
# Find the client ID
php occ oidc:list | jq '.[] | select(.name | contains("Claude Code")) | {name, client_id}'

# Delete the client
php occ oidc:delete <client_id>

# Reconnect from Claude Code
# This will trigger a new OAuth flow where you can grant all scopes
```

When reconnecting, you'll see a consent screen listing all available scopes. Make sure to approve all the scopes you want the client to access.

**Option 2: Update Client Scopes via CLI**

```bash
# Update allowed scopes for an existing client
php occ oidc:update <client_id> \
  --allowed-scopes "openid profile email mcp:notes.read mcp:notes.write mcp:calendar.read mcp:calendar.write mcp:contacts.read mcp:contacts.write mcp:cookbook.read mcp:cookbook.write mcp:deck.read mcp:deck.write mcp:tables.read mcp:tables.write mcp:files.read mcp:files.write mcp:sharing.read mcp:sharing.write"

# User will need to reconnect to get new token with updated scopes
```

**Verify Available Scopes**:

Check what scopes the MCP server advertises:

```bash
curl http://localhost:8001/.well-known/oauth-protected-resource | jq '.scopes_supported'

# Should show all 16 scope categories:
# - openid
# - mcp:notes.read, mcp:notes.write
# - mcp:calendar.read, mcp:calendar.write
# - mcp:contacts.read, mcp:contacts.write
# - mcp:cookbook.read, mcp:cookbook.write
# - mcp:deck.read, mcp:deck.write
# - mcp:tables.read, mcp:tables.write
# - mcp:files.read, mcp:files.write
# - mcp:sharing.read, mcp:sharing.write
```

**Understanding Scope Filtering**:

The MCP server dynamically filters tools based on the scopes in your access token:
- Check server logs for: `✂️ JWT scope filtering: X/90 tools available for scopes: {...}`
- This shows how many tools are visible vs total available
- Each tool requires specific scopes (read and/or write)

**Available Scope Categories**:

| Scope Prefix | Nextcloud App | Read Operations | Write Operations |
|--------------|---------------|-----------------|------------------|
| `mcp:notes:*` | Notes | Get, search, list | Create, update, delete, append |
| `mcp:calendar:*` | Calendar (CalDAV) | Get events, todos, calendars | Create/update/delete events, todos |
| `mcp:contacts:*` | Contacts (CardDAV) | Get contacts, address books | Create/update/delete contacts |
| `mcp:cookbook:*` | Cookbook | Get recipes, search | Create/update recipes |
| `mcp:deck:*` | Deck | Get boards, cards | Create/update boards, cards |
| `mcp:tables:*` | Tables | Get rows, tables | Create/update/delete rows |
| `mcp:files:*` | Files (WebDAV) | List, read files | Upload, delete, move files |
| `mcp:sharing:*` | Sharing | Get shares | Create/update shares |

---

## Switching Authentication Modes

### From BasicAuth to OAuth

```bash
# 1. Remove or comment out USERNAME/PASSWORD in .env
sed -i 's/^NEXTCLOUD_USERNAME/#NEXTCLOUD_USERNAME/' .env
sed -i 's/^NEXTCLOUD_PASSWORD/#NEXTCLOUD_PASSWORD/' .env

# 2. Ensure NEXTCLOUD_HOST is set
grep NEXTCLOUD_HOST .env

# 3. Restart server with OAuth
export $(grep -v '^#' .env | xargs)
uv run nextcloud-mcp-server --oauth
```

### From OAuth to BasicAuth

```bash
# 1. Add USERNAME/PASSWORD to .env
echo "NEXTCLOUD_USERNAME=your-username" >> .env
echo "NEXTCLOUD_PASSWORD=your-password" >> .env

# 2. Restart server (BasicAuth auto-detected)
export $(grep -v '^#' .env | xargs)
uv run nextcloud-mcp-server --no-oauth
```

---

## Advanced Debugging

### Enable Debug Logging

```bash
uv run nextcloud-mcp-server --oauth --log-level debug
```

Look for:
- OIDC discovery details
- Client registration attempts
- Token validation logs
- API request/response details

### Test Discovery Endpoint

```bash
# Full discovery response
curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq

# Check specific fields
curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '{
  issuer,
  authorization_endpoint,
  token_endpoint,
  userinfo_endpoint,
  registration_endpoint,
  code_challenge_methods_supported
}'
```

### Test Token Validation

```bash
# Get userinfo with token
curl -H "Authorization: Bearer $TOKEN" \
  https://your.nextcloud.instance.com/apps/oidc/userinfo

# Should return user info:
# {
#   "sub": "username",
#   "preferred_username": "username",
#   "name": "Display Name",
#   ...
# }
```

### Test Nextcloud API Access

```bash
# Test OCS API (should work)
curl -H "Authorization: Bearer $TOKEN" \
  "$NEXTCLOUD_HOST/ocs/v2.php/cloud/capabilities?format=json" \
  -H "OCS-APIRequest: true"

# Test app API (requires patch)
curl -H "Authorization: Bearer $TOKEN" \
  "$NEXTCLOUD_HOST/apps/notes/api/v1/notes"
```

---

## Getting Help

If you continue to experience issues:

### 1. Collect Diagnostic Information

```bash
# Server version
uv run nextcloud-mcp-server --version

# Python version
python3 --version

# Server logs with debug
uv run nextcloud-mcp-server --oauth --log-level debug 2>&1 | tee mcp-server.log

# OIDC discovery
curl https://your.nextcloud.instance.com/.well-known/openid-configuration > oidc-discovery.json

# Nextcloud version
# Check in Nextcloud admin panel or:
php occ -V
```

### 2. Check Documentation

- [OAuth Architecture](oauth-architecture.md) - How OAuth works
- [OAuth Setup Guide](oauth-setup.md) - Configuration steps
- [Upstream Status](oauth-upstream-status.md) - Required patches
- [Configuration](configuration.md) - Environment variables

### 3. Open an Issue

If problems persist, [open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) with:

- **Error messages** (full text)
- **Server logs** (with `--log-level debug`)
- **OIDC discovery response** (from curl command above)
- **Nextcloud version**
- **OIDC app versions** (`oidc` and `user_oidc`)
- **Steps to reproduce**
- **Environment details** (OS, Python version, Docker vs local)

---

## See Also

- [OAuth Quick Start](quickstart-oauth.md) - Get started quickly
- [OAuth Setup Guide](oauth-setup.md) - Detailed configuration
- [OAuth Architecture](oauth-architecture.md) - Technical details
- [Upstream Status](oauth-upstream-status.md) - Required patches
- [General Troubleshooting](troubleshooting.md) - Non-OAuth issues