Domain Model: notion-mcp-remote

arch-domain-notion-mcp-remote Architecture

architecture active

Project

Component	Purpose	Notes
DynamicClient	An MCP client registered via Dynamic Client Registration (e.g., claude.ai)	Persisted by TokenStore; one per MCP client instance
AuthCode	Short-lived code issued during authorize, exchanged for an access token	Standard OAuth authz code flow
AccessToken	Long-lived (1 yr) MCP access token; wraps the upstream Notion token and workspace identity	PR #20; lifetime = 31536000s
NotionWorkspace	The workspace an AccessToken grants access to	Bound at OAuth consent time; 1:1 with the integration install
User	The Notion user who granted consent	Extracted via <code>extract_identity_from_token_response</code>

AccessToken owns an upstream notion_token — MCP token and Notion OAuth token are distinct. MCP token is the client's key; the notion_token is consumed server-side. Lets us rotate MCP tokens without re-auth against Notion.
1-year access token lifetime — PR #20. Chosen so claude.ai users rarely re-auth. No refresh tokens because Notion OAuth does not issue them for integrations.
File-backed TokenStore — JSON on PVC today. Moving to a DB or cluster Secret is future work if multi-replica or HA becomes necessary.