brandon/nextcloud-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add ADR-004 - MCP Server as OAuth Client for Offline Access

Browse Source 
- Supersedes ADR-002 which fundamentally misunderstood MCP protocol constraints
- Introduces "Sign-in with Nextcloud" architecture pattern
- MCP server becomes OAuth client to enable offline/background operations
- Implements full token rotation with reuse detection for security
- Includes comprehensive implementation details and migration strategy

Key architectural shift:
- From: Pass-through authentication (stateless, no offline access)
- To: MCP server as OAuth client (stateful, full offline capabilities)

The solution enables background workers to operate independently of MCP
sessions by storing and rotating refresh tokens securely.

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
2025-11-02 23:31:39 +01:00
parent 7cb616c7ce
commit f2af5a39a8
3 changed files with 862 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ADR-002-vector-sync-authentication.md
+6 -1
View File
@@ -1,7 +1,12 @@
# ADR-002: Vector Database Background Sync Authentication
> **⚠️ DEPRECATED**: This ADR has been superseded by [ADR-004: MCP Server as OAuth Client for Offline Access](./ADR-004-mcp-application-oauth.md).
>
> **Reason for Deprecation**: This ADR fundamentally misunderstood the MCP protocol's authentication architecture. The MCP server receives tokens from clients but cannot initiate OAuth flows or store refresh tokens, making the proposed solutions ineffective for true offline access. ADR-004 provides the correct architectural pattern where the MCP server acts as its own OAuth client.
## Status
Accepted - Tier 2 (Token Exchange with Delegation) Implemented
~~Accepted - Tier 2 (Token Exchange with Delegation) Implemented~~
**Superseded by ADR-004** - The token exchange implementation exists but doesn't solve the offline access problem.
**Important**: Service account tokens (old Tier 1) have been rejected as they violate OAuth "act on-behalf-of" principles by creating Nextcloud user accounts for the MCP server.