notion-mcp-remote

Remote MCP server that brings Notion to claude.ai (and any MCP-over-HTTPS client) via Notion's OAuth 2.0 flow. A user grants the app access to their workspace once; the server then handles per-request workspace isolation via a ContextVar-based NotionClient so one deployment can serve many workspaces without token bleed.

Vision

Deliver a production-deployed, SOP-compliant notion-mcp-remote service that the operator can paste as a public URL into claude.ai's MCP settings, complete OAuth, and immediately use all 26 Notion tools in chat — no local stdio server, no integration-token juggling, no per-workspace redeploys. Success = OAuth round-trip under 60s and a search tool call returns live results from the authorized workspace on first try.

User Stories

Key	Story Note	Role	Success Metric
claude-ai-connect	story-notion-mcp-remote-claude-ai-connect	claude.ai user (Lucas)	Paste URL, complete OAuth in <60s, Notion tool works first try
multi-workspace-safety	story-notion-mcp-remote-multi-workspace-safety	Operator	Zero cross-tenant incidents; concurrency test returns workspace-correct results 100%
ops-deploy-gitops	story-notion-mcp-remote-ops-deploy-gitops	Operator	pre-deploy-validation checklist 100% green; zero manual kubectl edits post-deploy

Architecture

1. arch-domain-notion-mcp-remote — entities: DynamicClient, AuthCode, AccessToken, NotionWorkspace, User (erDiagram)
2. arch-dataflow-notion-mcp-remote — DCR, OAuth handshake, tool-call sequence with ContextVar injection (sequenceDiagram)
3. arch-deployment-notion-mcp-remote — Tailscale Funnel → ingress → pod, Harbor/Woodpecker/ArgoCD GitOps chain (graph TB)

Board

Primary kanban: board-notion-mcp-remote.

Columns: Backlog → Todo (review gate) → Next Up → In Progress → Done. Each ticket carries story:{key} and arch:{component} labels for traceability.

Status

• Local dev: working; .venv installs deps, make run serves on :8000, OAuth tested end-to-end locally.
• CI / k8s manifests: merged (commits 455b62c, 837e2f2, cb91a12). Woodpecker pipeline registry URL now points at internal cluster Harbor (harbor-core.harbor.svc.cluster.local) per service-onboarding-sop. Pipeline activation still pending (ticket #1048).
• Prod deploy: PRs MERGED (services #72, overlay #138, both 2026-05-01). Local k3s.tfvars updated with the new entry. tofu plan ran 2026-05-03 — paused at operator review: 7 expected new resources cleanly identified, but 14 unrelated drift items surfaced (pre-existing label drift on harbor_creds across 7 namespaces + provider write-only attr migration). Per PR #72 test plan, escalated rather than auto-applied. See pal-e-platform#296 comment for full plan output + 3 decision options.
• claude.ai integration: not yet; blocked on public URL (#1049 is the E2E verification ticket).
• Discovered scope: spike #11 — auto-bump remote-base ?ref= SHA via Woodpecker (mirroring Image Updater pattern). Plus 2 doc updates queued for next /update-docs cycle: convention-kustomize-overlay Remote Base Variant section and sop-validation 3-PR merge-order documentation. Plus 1 platform-board ticket pending: audit + reconcile pal-e-services drift (14 items).

Milestones

• No milestones yet. Target M1: first prod deploy with public URL reachable from claude.ai (drives all three user stories).

Repos

Repo	Platform	Role	Status
notion-mcp-remote	Forgejo	the service — FastMCP app, OAuth proxy, k8s manifests	active
mcp-remote-auth	Forgejo	shared OAuth infrastructure (consumed as mcp-remote-auth-ldraney)	active, v0.1.0 on public PyPI
notion-mcp	Forgejo / PyPI	upstream tool surface (consumed as notion-mcp-ldraney)	active, v0.1.13
pal-e-services	Forgejo	terraform service registration (var.services)	pending PR
pal-e-deployments	Forgejo	kustomize overlay for prod	pending PR