Pushing the design system into Figma over MCP

The Figma target reuses the design-system inventory described in the OpenPencil note. A builder script converts that inventory into a Figma-shaped canvas payload: a README and table of contents, the token and variable hierarchy, shadcn component variants and states, the custom site and article components, and full-length snapshots of eleven pages captured from the running Next.js app. The snapshots are pre-sliced into segments so each image stays within Figma's fill size limits.

Three write paths were tested. First, the standalone remote path: npx mcp-remote pointed at https://mcp.figma.com/mcp, driven by the sync script's push flag. Second, the Figma MCP tools already registered inside Codex. Third, a local development plugin in designs/figma-canvas-plugin that reads the generated payload and writes native Figma pages, frames, and snapshot fills directly inside the file.

# rebuild the Figma payload alongside the OpenPencil canvas
npm run agentic:figma:build

# attempt the remote MCP push (currently blocked at OAuth)
npm run agentic:sync:once:push

# inspect the dated result
npm run agentic:sync:status

The blocker first, because it is the most useful finding. The standalone mcp-remote client is rejected before tool listing: the remote endpoint returns HTTP 403 during OAuth client registration in this environment, and the connection closes with MCP error -32000. The status file records this honestly as external-mcp-remote-blocked. Nothing in the payload or the script is at fault — the failure is at the authentication boundary, which is exactly where most 'agent writes to vendor SaaS' workflows currently break.

The two workarounds both shipped. The Figma MCP tools registered through Codex authenticate fine: the latest check confirms whoami, read access to the target file, and an 'Agentic canvas sync' page containing twenty top-level nodes including the Figma library frame and the article-artifacts frame. And the local plugin is the reliable writer: import it once as a development plugin, point it at the generated payload, and it creates the native frames and places the sliced page snapshots without any remote endpoint involved.

• Generated payload: 133 visual artifacts, 151 code blocks, 11 page snapshots, rebuilt by the same watch loop as OpenPencil.
• Remote mcp-remote path: blocked at OAuth registration (HTTP 403, connection closed before tool listing).
• Codex-registered Figma MCP: authenticated, verified read access, used for inspection and targeted writes.
• Local development plugin: the dependable write path for full canvas refreshes today.

Two lessons travel beyond this repository. First, design-to-canvas sync is mostly a payload problem, not a tool problem: once the design system exists as machine-readable JSON, retargeting it from OpenPencil to Figma was a renderer change, not a rethink. Second, plan for the authentication boundary to be the weakest link. Enterprise admin settings, OAuth client registration, and connector allowlists will block the elegant remote path more often than the API will — so keep a local writer (a plugin, a file import, a CLI) as the boring fallback that always works, and record every failure in a dated status file so the next attempt starts from evidence instead of memory.