pal-e-docs

Review: E2E verify + claude.ai integration for notion-mcp-remote

review-1049-2026-04-21 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Note: Minor scope gap — one missing backing note for the arch:tailscale-funnel label. Everything else is in order. The ticket itself is well-scoped as a verification-only validation pass for the claude-ai-connect user story.

Template Completeness

Issue type: Feature (Type header = "Feature"). Routed against template-issue-feature.
  • [x] Type — "Feature"
  • [x] Lineage — standalone E2E verification ticket, proves Milestone M1
  • [x] Repo — forgejo_admin/notion-mcp-remote
  • [x] User Story — inline, matches story-notion-mcp-remote-claude-ai-connect
  • [x] Context — explains dependency chain + references sop-validation
  • [x] File Targets — explicitly "No repo file changes; verification + validation-note creation only" (appropriate for this ticket type)
  • [x] Acceptance Criteria — 11 checks across Platform / E2E / Recordkeeping
  • [x] Test Expectations — present with concrete pass conditions
  • [x] Constraints — present, including "do not begin until all upstream tickets closed"
  • [x] Checklist — present
  • [x] Related — links to project, user story, ops-deploy-gitops story, sop-validation

Traceability

  • [x] story:claude-ai-connect label — story "Connect Notion to claude.ai"
  • [x] story note verified — story-notion-mcp-remote-claude-ai-connect exists and is listed in the project-notion-mcp-remote user-stories section
  • [x] arch:tailscale-funnel label present on board item
  • [ ] arch note MISSING — no arch-tailscale-funnel note exists in pal-e-docs. Tailscale Funnel behavior is covered piecewise in arch-deployment-notion-mcp-remote, arch-deployment-gdocs-daily-mcp-remote, arch-deployment-westside-mcp, and host-inventory-archbox, but there is no shared architecture note backing the arch:tailscale-funnel label. This is a recurring gap — the same finding was raised on review-788-2026-04-03 (playme2k funnel + kustomize). [SCOPE] Create shared arch-tailscale-funnel note documenting the Funnel proxy pattern (proxy pod in tailscale namespace, *.tail5b443a.ts.net hostnames, TLS termination, ingress handoff) so all services using that label link to one canonical diagram.
  • [x] type:feature label — appropriate (new capability, not a bug fix)
  • [x] Forgejo issue — forgejo_admin/notion-mcp-remote#9 — open, body matches template

File Targets

Not applicable — ticket is verification-only. Deliverables are a validation note (per sop-validation) and a milestone mark on the project page Status section. This is the correct shape for the claude-ai-connect validation ticket.

Repo Placement

OK. The Forgejo issue is filed on forgejo_admin/notion-mcp-remote, which is the correct owning service for the E2E validation. The validation note will live in pal-e-docs, and the milestone mark lands on project-notion-mcp-remote — both are separate surfaces, not file changes in the repo.

Dependencies

Seven prerequisite tickets must close before this ticket executes. All are currently open / in backlog:
  • pal-e-platform#296 — tofu apply to provision notion-mcp-remote (open)
  • pal-e-services#57 — add notion-mcp-remote to var.services (open)
  • pal-e-deployments#132 — add overlays/notion-mcp-remote/prod kustomize overlay (open)
  • notion-mcp-remote#5 — switch Woodpecker image push to internal Harbor URL (open)
  • notion-mcp-remote#6 — register public Notion OAuth integration for remote proxy (open)
  • notion-mcp-remote#7 — provision app secrets in notion-mcp-remote namespace (open)
  • notion-mcp-remote#8 — activate repo in Woodpecker + add Harbor push secrets (open)
Dependencies are documented correctly in the Constraints section ("Do not begin this ticket until all upstream tickets closed"). The review->todo gate on backlog is fine for now; execution must not start until upstream work closes. No refinement needed on dependency documentation itself.

Acceptance Criteria

AC are testable with concrete commands and tool calls:
  • Platform checks (6): Woodpecker pipeline status, ArgoCD sync+health, pod Running, /health 200, /.well-known/oauth-authorization-server JSON, Prometheus scrape. All verifiable via mcp__woodpecker__list_pipelines, kubectl, curl, and Prometheus UI. The notion_mcp_remote_up metric referenced in AC is confirmed present in server.py.
  • E2E checks (4): claude.ai accepts URL, Notion OAuth consent < 60s, search tool returns real results, second tool call (get_page) succeeds. Matches all 6 AC of the user story.
  • Recordkeeping (3): validation note per sop-validation, Milestone M1 marked on project page Status, all prior tickets closed.
One small tightening opportunity — [BODY] The AC currently say "curl https://notion-mcp-remote.tail5b443a.ts.net/.well-known/oauth-authorization-server returns valid JSON with the expected issuer, authorization_endpoint, token_endpoint." Consider also asserting the registration_endpoint is present since Dynamic Client Registration is how claude.ai onboards. Minor; not a blocker.

Blast Radius

Small. Ticket is observational — no config changes, no code merges. Risk is only that a failing check here exposes a real defect in upstream tickets (which is the point). If any check fails, the validation verdict is PARTIAL/FAIL and the appropriate upstream ticket gets reopened, not this one.

Decomposition Assessment

AC count is 11, which exceeds the default 5-AC threshold — but this is the explicit, intended shape of a validation ticket: one pass that exercises every AC of the user story, per sop-validation. Estimated time is 15–20 minutes of browser + kubectl + curl work, not 5, but decomposing a validation ticket defeats its purpose (it would split cross-cutting concerns back into per-layer checks that already belong on the upstream tickets). Points=2 reflects this correctly.
No decomposition recommended.

Recommendation

Verdict: NEEDS_REFINEMENT — one concrete gap to close before this moves to todo:
  • [SCOPE] Create shared architecture note arch-tailscale-funnel documenting the Funnel proxy pattern used by this and other MCP services. This unblocks not just #1049 but every current/future ticket labeled arch:tailscale-funnel. Can reuse content already in host-inventory-archbox, doc-network-traffic-map, and arch-deployment-notion-mcp-remote.
  • [BODY] (optional, nice-to-have) Add registration_endpoint to the list of OAuth metadata fields asserted in the Platform checks AC, since DCR is on the handshake hot path.
Upstream dependencies (7 open tickets) are correctly documented; no action on those from this review — they will be closed by their own tracks.
  • Board item 1049 — board-notion-mcp-remote column=backlog
  • Forgejo: forgejo_admin/notion-mcp-remote#9
  • story-notion-mcp-remote-claude-ai-connect
  • project-notion-mcp-remote
  • sop-validation
  • Prior funnel-arch-missing finding: review-788-2026-04-03