Achhina's Digital Garden

2026-06-21 Remote Obsidian MCP Tutorial Artifact

3 min read

2026-06-21 Remote Obsidian MCP Tutorial Artifact

What I set out to do

Turn yesterday’s remote Obsidian MCP build into a shareable, interactive tutorial / Claude spec — an HTML artifact that explains how the setup works to someone else looking to replicate it. Scope deliberately narrowed: show the Streamable-HTTP MCP, the Cloudflare Tunnel, and the GCP OAuth2 handshake. Explicitly omit the nix/home-manager layer so the guide is portable to any process manager.

What I actually did

Built a single-file HTML artifact (remote-obsidian-mcp.html, ~30KB, no external deps).

Design. Treated the subject’s own world — the request path and its trust boundaries — as the visual vocabulary instead of a generic diagram. Token system: deep ink background, parchment for “inside the vault,” signal-amber for the request in flight, tunnel-violet for the encrypted hop, guard-green that only appears once auth passes. The signature element is a live request-trace player: press play and a packet animates Claude app → Cloudflare edge → Mac, lighting the Access checkpoint (green only after OAuth clears) and dashing the tunnel line. Three labeled zones under the nodes encode the trust boundaries (untrusted public / checkpoint / loopback-only private).

Structure (6 sections).

  1. Why a custom connector is harder than a local server — the cloud connects to you, so it must be public + Streamable HTTP + OAuth.
  2. The interactive end-to-end trace.
  3. The three components as cards (bridge / tunnel / Access+OAuth), with the all-interfaces-binding hole called out.
  4. The OAuth2 handshake as a numbered sequence, with the empty allowed_uris → DCR-rejection failure flagged in red as “the crux.”
  5. Copy-ready config skeletons (mcp-proxy bridge, cloudflared ingress, Access policy, connector URL) with working copy buttons and placeholder values.
  6. Three verification checks to confirm it’s actually sealed.

Carried over the hard-won lessons from the build journal — loopback binding, token/secret rotation, disabling DCR localhost redirects, and the “dead connection looks identical to a dead server” note — since those are the parts most likely to bite a replicator.

What was striking

  • The most useful thing to visualize wasn’t the topology but the trust boundary crossings — where a request leaves the public internet and where it gets checked. The zone labels did more explanatory work than the node icons.
  • The OAuth crux (empty allowed_uris rejecting DCR) is invisible in a static topology diagram but is the single most likely thing to make a replicator fail — so it earned its own highlighted step rather than a footnote.
  • Stripping nix out actually improved the tutorial: process-manager-agnostic config skeletons are more legible than the declarative module and don’t assume the reader’s toolchain.

Top 3 tomorrow

  1. Decide whether to publish this (e.g. a gist or achhina.dev page) or keep it private as a personal spec.
  2. If publishing: double-check no real hostnames/emails leaked — currently all placeholders (obsidian-mcp.you.com, :8788, you@gmail.com).
  3. Consider folding a trimmed version back into the vault as an Atlas reference note, not just a journal mention.

Graph View