figma-mcp-auth 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 figma-mcp-auth contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# figma-mcp-auth
+
+**Connect any MCP client to Figma's remote MCP server — even clients Figma doesn't officially support.**
+
+```
+npx figma-mcp-auth all
+```
+
+## The problem
+
+Figma's remote MCP server (`https://mcp.figma.com/mcp`) is OAuth-only, and its
+OAuth server rejects [RFC 7591 dynamic client registration](https://datatracker.ietf.org/doc/html/rfc7591)
+from every client that isn't on Figma's catalog:
+
+> *Only clients listed in the Figma MCP Catalog like VS Code, Cursor, or Claude Code can connect.*
+> — [Figma docs](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/)
+
+If your agent isn't in that list (ZCode, Windsurf, Trae, Cline, a home-grown
+agent, anything new), its login fails deterministically:
+
+```
+Dynamic Client Registration rejected (HTTP 403): Forbidden
+MCP authorization was not completed or timed out. Authorize again.
+```
+
+Personal access tokens don't help either — Figma's remote server accepts
+**OAuth only** (no `X-Figma-Token` header, no PATs).
+
+## The fix
+
+This tool mints a Figma MCP token **through a client Figma does accept** (the
+Codex CLI, or Claude Code), then injects it into your agent's MCP config as a
+static `Authorization: Bearer` header. Figma's server is perfectly happy serving
+tools to any client that presents a valid token — it just won't *register*
+unknown clients.
+
+```
+┌─────────────┐  codex mcp login (allow-listed)   ┌────────────┐
+│ codex CLI   │ ──── browser → you click Allow ──▶│   Figma    │
+│ (isolated   │ ◀── token stored in OS keyring ───│  OAuth     │
+│  home)      │                                   └────────────┘
+└──────┬──────┘
+       │ figma-mcp-auth reads the keyring
+       ▼
+┌─────────────┐  Authorization: Bearer figu_…     ┌────────────┐
+│ your agent  │ ◀── HTTP 200, tools available ───▶│   Figma    │
+└─────────────┘                                   │ MCP server │
+                                                  └────────────┘
+```
+
+What it does **not** do: touch your existing Codex or Claude setup (Codex runs
+in a throwaway `CODEX_HOME`), send your token anywhere except api.figma.com /
+mcp.figma.com, or store it anywhere but `~/.figma-mcp-auth/token.json` and the
+agent configs you explicitly inject into.
+
+## Usage
+
+```bash
+npx figma-mcp-auth all          # diagnose → mint (browser approval) → inject
+```
+
+Step by step:
+
+| Command | What it does |
+|---|---|
+| `figma-mcp-auth doctor` | Checks the endpoint, the stored token (live handshake), the DCR allow-list gate, and every known agent config |
+| `figma-mcp-auth mint` | Runs `codex mcp login figma` in an isolated home; you approve in the browser; token lands in `~/.figma-mcp-auth/token.json` |
+| `figma-mcp-auth inject --target zcode` | Writes the `Authorization` header into `~/.zcode/cli/config.json` (also: `--target claude`, `--target cursor`, or any JSON file via `--config`) |
+| `figma-mcp-auth refresh` | Exchanges the stored refresh token for a fresh access token and updates every config previously injected |
+| `figma-mcp-auth all` | doctor → mint (only if needed) → inject |
+
+Supported config shapes (auto-detected):
+
+```jsonc
+// ZCode (~/.zcode/cli/config.json) — nested
+{ "mcp": { "servers": { "figma": { "type": "http", "url": "https://mcp.figma.com/mcp",
+    "headers": { "Authorization": "Bearer figu_…" } } } } }
+
+// Claude Code / Cursor / .mcp.json — flat
+{ "mcpServers": { "figma": { "type": "http", "url": "https://mcp.figma.com/mcp",
+    "headers": { "Authorization": "Bearer figu_…" } } } }
+```
+
+After injecting, **restart the agent** (MCP servers connect at session start).
+
+## Requirements
+
+- Node ≥ 18
+- For `mint`: the [Codex CLI](https://developers.openai.com/codex) installed and
+  on PATH (Windows, macOS, Linux). Alternative without Codex: `--client claude`,
+  which prints the two-step Claude Code flow and then adopts the token from
+  `~/.claude/.credentials.json`.
+- A Figma account, and one click of **Allow** in the browser.
+
+## Token lifetime
+
+Figma's MCP access tokens last **90 days** (`expires_in: 7776000`). Note:
+`figma-mcp-auth refresh` only succeeds if the store contains the OAuth
+`client_secret` — Figma's token endpoint demands it for refresh and the Codex
+CLI does not retain it in its keyring blob. In practice, renewal means running
+`figma-mcp-auth mint` again (one browser click, roughly once per 90 days); the
+tool's `refresh` command detects this case and says so.
+
+## Known limits
+
+- `mint` reads the token from the OS keyring where Codex stores it:
+  Windows Credential Manager (works headlessly), macOS Keychain (`security`
+  may show one permission prompt), Linux via `secret-tool` (best effort).
+- Keyring layouts are reverse-engineered from the Codex CLI's behavior as of
+  its 0.13x releases; if a future Codex version changes storage, `mint` will
+  tell you and the manual steps in [SKILL.md](./SKILL.md) still apply.
+
+## For agent authors: the SKILL.md
+
+This package ships [`SKILL.md`](./SKILL.md) — a drop-in skill file (frontmatter +
+procedure) that teaches any agent how to diagnose and fix this exact failure,
+including the fully manual fallback. Copy it into your agent's skills directory
+(e.g. `~/.agents/skills/figma-mcp-auth/SKILL.md`, `~/.claude/skills/`, …) or
+just let the agent run `npx figma-mcp-auth doctor` and read its output.
+
+## Publishing / running from source
+
+```bash
+git clone <this repo> && cd figma-mcp-auth
+node bin/figma-mcp-auth.js doctor      # run without installing
+npm link                               # or: npm i -g .
+npm publish                            # makes `npx figma-mcp-auth` work for everyone
+```
+
+## License
+
+MIT. Unofficial community tool — not affiliated with or endorsed by Figma.
+Use with your own Figma account; the browser approval is always yours to give.

package/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: figma-mcp-auth
+description: Fix "Dynamic Client Registration rejected (HTTP 403)" / "MCP authorization was not completed" when a non-catalog MCP client (ZCode, Windsurf, Trae, custom agents, anything not VS Code/Cursor/Claude Code/Codex/Xcode) tries to authenticate against Figma's remote MCP server (mcp.figma.com/mcp). Mints a token via the allow-listed Codex CLI and injects it as a Bearer header. Use whenever Figma MCP auth fails with 401/403 in a client that is not in Figma's catalog.
+---
+
+# Figma MCP auth for non-catalog clients
+
+## The problem
+
+Figma's remote MCP server (`https://mcp.figma.com/mcp`) is OAuth-only and rejects
+RFC 7591 dynamic client registration from every client not on its catalog
+(VS Code, Cursor, Claude Code, Codex, Xcode). Symptoms:
+
+- Settings shows the server failed with `Dynamic Client Registration rejected (HTTP 403): Forbidden`
+- or `MCP authorization was not completed or timed out. Authorize again.` in a loop
+- clicking the client's Authorize/Login button always fails, deterministically
+- PATs / `X-Figma-Token` headers do NOT work on the remote server (OAuth only)
+
+This is not fixable by retrying, changing config fields, or payloads — the
+allow-list is server-side.
+
+## The fix (automated)
+
+Mint a token through an allow-listed client that IS accepted (Codex CLI), then
+inject it into the failing client's config as a Bearer header:
+
+```bash
+npx figma-mcp-auth all                # doctor + mint + inject (auto-detects config)
+```
+
+Or step by step:
+
+```bash
+npx figma-mcp-auth doctor             # diagnose: endpoint, stored token, agent configs
+npx figma-mcp-auth mint               # runs codex mcp login in a throwaway home; user approves in browser
+npx figma-mcp-auth inject --target zcode --config ~/.zcode/cli/config.json --name figma
+npx figma-mcp-auth refresh            # later, when the 90-day token expires
+```
+
+- `mint` requires the Codex CLI on the machine (or `--client claude` after
+  authenticating figma inside Claude Code via `/mcp`). The user's own Codex/Claude
+  setup is never modified (Codex runs with an isolated `CODEX_HOME`).
+- `inject` supports `{"mcp":{"servers":{...}}}` (ZCode) and `{"mcpServers":{...}}`
+  (Claude Code, Cursor, .mcp.json) shapes. It backs up the file to
+  `<path>.figma-mcp-auth.bak` before writing.
+- Token store: `~/.figma-mcp-auth/token.json` (keeps `injected: [{path,name}]`).
+- The access token lives ~90 days (`expires_in: 7776000`). `refresh` only works
+  when a `client_secret` is present in the store — Figma's token endpoint
+  requires it for refresh and the minting client doesn't retain it, so the
+  practical renewal is `npx figma-mcp-auth mint` again (one browser click, ~once
+  per 90 days).
+
+## Manual fallback (no npx, do it by hand)
+
+1. Verify the gate (optional): `POST https://api.figma.com/v1/oauth/mcp/register`
+   with any RFC 7591 body → 403 Forbidden confirms the allow-list.
+2. Create a temp dir with `config.toml`:
+   ```toml
+   [mcp_servers.figma]
+   url = "https://mcp.figma.com/mcp"
+   ```
+3. `CODEX_HOME=<tempdir> codex mcp login figma` → approve in browser.
+4. Read the token from the OS keyring — account `Codex MCP Credentials`,
+   service `figma|<client_id>`. The blob is a JSON doc:
+   `{ server_name, url, client_id, token_response: { access_token, refresh_token, expires_in }, expires_at }`
+   - Windows: PowerShell `CredEnumerate 'figma|*'`; blob is **UTF-16LE** encoded.
+   - macOS: `security find-generic-password -s 'figma|<id>' -a 'Codex MCP Credentials' -w`
+   - Linux: `secret-tool search account 'Codex MCP Credentials'` (best effort)
+5. Put `"headers": { "Authorization": "Bearer <access_token>" }` on the figma
+   entry of the failing client's MCP config (HTTP transport). Restart the client.
+
+## Notes and gotchas
+
+- Sign in to Figma with the account that owns the files the agent should see.
+- If the client has its own OAuth machinery (like ZCode's Settings → MCP
+  "Authorize again"), leave it broken — a config `Authorization` header takes
+  precedence because the server never returns a 401 challenge.
+- Do NOT put the token in any file that gets committed; it is an account credential.
+- If refresh ever fails (revoked), just re-run `mint` — it is a fresh 90-day token.
+- Unofficial tool; not affiliated with Figma. Uses the user's own account with
+  explicit browser approval.

package/bin/figma-mcp-auth.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+"use strict";
+
+const { runDoctor } = require("../lib/doctor");
+const { runMint } = require("../lib/mint");
+const { runInject } = require("../lib/inject");
+const { runRefresh } = require("../lib/refresh");
+const { STORE_PATH } = require("../lib/constants");
+
+const HELP = `
+figma-mcp-auth — connect non-catalog MCP clients to Figma's remote MCP server
+
+Figma's remote MCP server (https://mcp.figma.com/mcp) only accepts OAuth client
+registrations from its catalog apps (VS Code, Cursor, Claude Code, Codex, Xcode).
+Any other agent gets "Dynamic Client Registration rejected (HTTP 403)" and can
+never complete the login on its own.
+
+This tool works around that by minting a Figma MCP token through an allow-listed
+client already on your machine (Codex CLI, or Claude Code), then injecting it
+into your agent's MCP config as an "Authorization: Bearer" header. No config of
+the minting client is modified — Codex runs in a throwaway home directory.
+
+Usage:
+  figma-mcp-auth doctor                Diagnose endpoint, stored token, and configs
+  figma-mcp-auth mint [--client codex|claude]
+                                       Mint a token (opens your browser to approve)
+  figma-mcp-auth inject [--target <t>] [--config <path>] [--name <n>] [--dry-run]
+                                       Write the Bearer header into an agent config
+  figma-mcp-auth refresh               Exchange the refresh token for a new access token
+  figma-mcp-auth all [--target <t>]    doctor + mint (if needed) + inject
+
+Targets: zcode | claude | cursor   (or any JSON config via --config; both the
+nested {"mcp":{"servers":{...}}} shape and the flat {"mcpServers":{...}} shape
+are supported)
+
+Token store: ${STORE_PATH}
+`;
+
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const eq = key.indexOf("=");
+    if (eq > -1) {
+      flags[key.slice(0, eq)] = key.slice(eq + 1);
+    } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+      flags[key] = argv[++i];
+    } else {
+      flags[key] = true;
+    }
+  }
+  return flags;
+}
+
+async function runAll(flags) {
+  const doctor = await runDoctor({ ...flags, quiet: true });
+  const doc = require("../lib/store").load();
+  if (!doctor.ok || !doc || require("../lib/store").isExpired(doc)) {
+    await runMint(flags);
+  }
+  return runInject(flags);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv.find((a) => !a.startsWith("--"));
+  const flags = parseFlags(argv);
+  switch (cmd) {
+    case "doctor":
+      return runDoctor(flags);
+    case "mint":
+      return runMint(flags);
+    case "inject":
+      return runInject(flags);
+    case "refresh":
+      return runRefresh(flags);
+    case "all":
+      return runAll(flags);
+    case "-h":
+    case "--help":
+    case "help":
+    case undefined:
+      console.log(HELP);
+      return;
+    default:
+      console.error(`Unknown command: ${cmd}`);
+      console.log(HELP);
+      process.exitCode = 1;
+  }
+}
+
+main().catch((e) => {
+  console.error(e && e.message ? e.message : e);
+  process.exitCode = 1;
+});

package/lib/constants.js

@@ -0,0 +1,32 @@
+"use strict";
+
+const os = require("os");
+const path = require("path");
+
+const MCP_URL = "https://mcp.figma.com/mcp";
+const AUTHORIZE_URL = "https://www.figma.com/oauth/mcp";
+const TOKEN_URL = "https://api.figma.com/v1/oauth/token";
+const REGISTER_URL = "https://api.figma.com/v1/oauth/mcp/register";
+const PROTECTED_RESOURCE_URL = "https://mcp.figma.com/.well-known/oauth-protected-resource";
+const SCOPE = "mcp:connect";
+
+// Keyring blob layout written by the Codex CLI's MCP OAuth store:
+// { server_name, url, client_id, token_response: { access_token, token_type, expires_in, refresh_token }, expires_at }
+const KEYRING_ACCOUNT = "Codex MCP Credentials";
+const KEYRING_SERVICE_PREFIX = "figma|";
+
+const STORE_DIR = path.join(os.homedir(), ".figma-mcp-auth");
+const STORE_PATH = path.join(STORE_DIR, "token.json");
+
+module.exports = {
+  MCP_URL,
+  AUTHORIZE_URL,
+  TOKEN_URL,
+  REGISTER_URL,
+  PROTECTED_RESOURCE_URL,
+  SCOPE,
+  KEYRING_ACCOUNT,
+  KEYRING_SERVICE_PREFIX,
+  STORE_DIR,
+  STORE_PATH,
+};

package/lib/doctor.js

@@ -0,0 +1,126 @@
+"use strict";
+
+const fs = require("fs");
+const store = require("./store");
+const { probeInitialize, probeRegister } = require("./probe");
+const { TARGETS, openConfig, locateServers } = require("./inject");
+const { findCodex } = require("./mint");
+
+function checkConfig(name, p, serverName, failuresRef) {
+  if (!fs.existsSync(p)) {
+    console.log(`info - ${name}: no config at ${p}`);
+    return;
+  }
+  let json;
+  try {
+    json = openConfig(p);
+  } catch (e) {
+    console.log(`FAIL - ${name}: ${e.message}`);
+    failuresRef.n++;
+    return;
+  }
+  const servers = locateServers(json);
+  const entry = servers && servers[serverName];
+  if (!entry) {
+    console.log(`info - ${name}: config exists at ${p} but has no "${serverName}" server entry`);
+    return;
+  }
+  const header = entry.headers && entry.headers.Authorization;
+  if (!header) {
+    console.log(`warn - ${name}: "${serverName}" entry at ${p} has no Authorization header (this is why auth fails)`);
+    return;
+  }
+  console.log(`ok   - ${name}: "${serverName}" configured at ${p} (Authorization ${header.slice(0, 14)}...${header.slice(-4)})`);
+  return header;
+}
+
+async function runDoctor(flags) {
+  const failures = { n: 0 };
+  let ok = true;
+
+  // 1. Is the remote server reachable, and does it behave as expected?
+  let probe;
+  try {
+    probe = await probeInitialize(null);
+  } catch (e) {
+    console.log(`warn - could not reach mcp.figma.com (${e.message}). Check your network/proxy; skipping endpoint checks.`);
+    probe = null;
+  }
+  if (probe && probe.status === 401) {
+    console.log("ok   - mcp.figma.com is reachable and rejects unauthenticated clients (expected)");
+  } else if (probe) {
+    console.log(`warn - mcp.figma.com probe returned HTTP ${probe.status} (expected 401)`);
+  }
+
+  // 2. Stored token state.
+  const doc = store.load();
+  const token = store.accessToken(doc);
+  if (!doc) {
+    console.log(`info - no token stored yet (${store.STORE_PATH})`);
+  } else if (store.isExpired(doc)) {
+    console.log(`warn - stored token EXPIRED (was valid until ${new Date(store.expiresAt(doc)).toISOString()}). Run: figma-mcp-auth refresh`);
+  } else {
+    console.log(`ok   - stored token valid until ${new Date(store.expiresAt(doc)).toISOString()}`);
+    try {
+      const live = await probeInitialize(token);
+      if (live.ok) {
+        console.log("ok   - initialize handshake with stored token: HTTP 200 (tools available)");
+      } else {
+        console.log(`FAIL - initialize with stored token: HTTP ${live.status}. Try: figma-mcp-auth refresh`);
+        failures.n++;
+      }
+    } catch (e) {
+      console.log(`warn - live handshake with stored token failed (${e.message}) — network issue, token state unknown`);
+    }
+  }
+
+  // 3. Demonstrate the allow-list gate (why plain OAuth can never work here).
+  try {
+    const reg = await probeRegister();
+    if (reg.status === 403) {
+      console.log("info - direct OAuth registration is rejected (HTTP 403): Figma only accepts catalog clients (VS Code, Cursor, Claude Code, Codex, Xcode). That is the failure this tool works around.");
+    } else {
+      console.log(`info - registration probe returned HTTP ${reg.status} (unexpected; Figma may have changed its policy)`);
+    }
+  } catch (e) {
+    console.log(`warn - registration probe failed (${e.message}) — skipping allow-list check`);
+  }
+
+  // 4. Agent configs.
+  const serverName = flags.name || "figma";
+  for (const [name, fn] of Object.entries(TARGETS)) {
+    let header;
+    try {
+      header = checkConfig(name, fn(), serverName, failures);
+    } catch (e) {
+      console.log(`warn - ${name}: config check failed (${e.message})`);
+      continue;
+    }
+    const m = header && header.match(/^Bearer (.+)$/);
+    if (m) {
+      try {
+        const live = await probeInitialize(m[1]);
+        if (live.ok) {
+          console.log(`ok   - ${name}: configured token works (HTTP 200)`);
+        } else {
+          console.log(`FAIL - ${name}: configured token rejected (HTTP ${live.status}). Run: figma-mcp-auth refresh`);
+          failures.n++;
+        }
+      } catch (e) {
+        console.log(`warn - ${name}: live check failed (${e.message}) — network issue, config state unknown`);
+      }
+    }
+  }
+
+  // 5. Can we mint at all?
+  const codex = findCodex();
+  console.log(codex ? `ok   - Codex CLI found (${codex}) — minting available` : "info - Codex CLI not found on this machine (mint --client claude is the alternative)");
+
+  ok = failures.n === 0;
+  if (!flags.quiet) {
+    console.log(ok ? "\nAll checks passed." : `\n${failures.n} check(s) failed.`);
+  }
+  return { ok };
+}
+
+module.exports = { runDoctor };

package/lib/inject.js

@@ -0,0 +1,130 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { MCP_URL } = require("./constants");
+const store = require("./store");
+const { adoptClaudeToken } = require("./mint");
+
+const TARGETS = {
+  zcode: () => path.join(os.homedir(), ".zcode", "cli", "config.json"),
+  claude: () => path.join(os.homedir(), ".claude.json"),
+  cursor: () => path.join(os.homedir(), ".cursor", "mcp.json"),
+};
+
+function openConfig(p) {
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch (e) {
+    throw new Error(`${p} is not valid JSON: ${e.message}`);
+  }
+}
+
+/** Find the mcpServers map in either the ZCode nested shape or the flat standard shape. */
+function locateServers(doc) {
+  if (doc.mcp && doc.mcp.servers && typeof doc.mcp.servers === "object") return doc.mcp.servers;
+  if (doc.mcpServers && typeof doc.mcpServers === "object") return doc.mcpServers;
+  return null;
+}
+
+function ensureServersContainer(doc) {
+  if (locateServers(doc)) return locateServers(doc);
+  if (doc.mcp && typeof doc.mcp === "object") {
+    doc.mcp.servers = doc.mcp.servers || {};
+    return doc.mcp.servers;
+  }
+  doc.mcpServers = {};
+  return doc.mcpServers;
+}
+
+function describeEntry(entry) {
+  const header = entry && entry.headers && entry.headers.Authorization;
+  return {
+    exists: !!entry,
+    hasToken: !!header,
+    masked: header ? `${header.slice(0, 14)}...${header.slice(-4)}` : null,
+  };
+}
+
+async function runInject(flags) {
+  // Resolve the token: store first, then adopt from Claude's credentials file.
+  let doc = store.load();
+  let token = store.accessToken(doc);
+  if (!token && (flags.client === "claude" || !flags.client)) {
+    const adopted = adoptClaudeToken();
+    if (adopted) {
+      console.log("Adopting token found in Claude Code credentials (~/.claude/.credentials.json).");
+      doc = { ...adopted, injected: (doc && doc.injected) || [] };
+      store.save(doc);
+      token = store.accessToken(doc);
+    }
+  }
+  if (!token) {
+    console.error("No Figma MCP token available. Run first: figma-mcp-auth mint");
+    process.exitCode = 1;
+    return { ok: false };
+  }
+
+  // Resolve the target config path.
+  let cfgPath;
+  if (flags.config) {
+    cfgPath = path.resolve(flags.config);
+  } else if (flags.target && TARGETS[flags.target]) {
+    cfgPath = TARGETS[flags.target]();
+  } else if (flags.target) {
+    console.error(`Unknown target '${flags.target}'. Targets: ${Object.keys(TARGETS).join(", ")} or pass --config <path>.`);
+    process.exitCode = 1;
+    return { ok: false };
+  } else {
+    for (const fn of Object.values(TARGETS)) {
+      const p = fn();
+      if (fs.existsSync(p)) {
+        cfgPath = p;
+        break;
+      }
+    }
+    if (!cfgPath) {
+      console.error(`No known agent config found. Pass one explicitly: --config <path> or --target <${Object.keys(TARGETS).join("|")}>`);
+      process.exitCode = 1;
+      return { ok: false };
+    }
+  }
+
+  const json = openConfig(cfgPath) || {};
+  const servers = ensureServersContainer(json);
+  const name = flags.name || "figma";
+  const before = describeEntry(servers[name]);
+
+  servers[name] = {
+    ...(servers[name] || {}),
+    type: (servers[name] && servers[name].type) || "http",
+    url: (servers[name] && servers[name].url) || MCP_URL,
+    headers: {
+      ...((servers[name] && servers[name].headers) || {}),
+      Authorization: `Bearer ${token}`,
+    },
+  };
+
+  const dryRun = !!(flags.dryRun || flags["dry-run"]);
+  if (!dryRun) {
+    if (!fs.existsSync(cfgPath)) console.log(`(creating ${cfgPath})`);
+    else fs.copyFileSync(cfgPath, cfgPath + ".figma-mcp-auth.bak");
+    fs.writeFileSync(cfgPath, JSON.stringify(json, null, 2) + "\n");
+    store.rememberInjected(doc, cfgPath, name);
+  }
+
+  const after = describeEntry(servers[name]);
+  if (before.hasToken && before.masked === after.masked) {
+    console.log(`${cfgPath}: "${name}" already up to date (Authorization ${after.masked}).`);
+  } else {
+    console.log(`${cfgPath}: ${dryRun ? "[dry-run] would update" : "updated"} "${name}" -> ${after.hasToken ? `Authorization ${after.masked}` : "(no header)"}`);
+  }
+  if (!dryRun) {
+    console.log("Restart your agent / start a new session so the MCP server reconnects with the new header.");
+  }
+  return { ok: true, configPath: cfgPath, name };
+}
+
+module.exports = { runInject, TARGETS, openConfig, locateServers };

package/lib/keyring.js

@@ -0,0 +1,198 @@
+"use strict";
+
+const { execFileSync } = require("child_process");
+const { MCP_URL, KEYRING_ACCOUNT, KEYRING_SERVICE_PREFIX } = require("./constants");
+
+/**
+ * Extract Figma MCP token blobs that the Codex CLI stores in the OS keyring
+ * after `codex mcp login <name>` succeeds.
+ *
+ * Layout per platform:
+ *  - Windows: Credential Manager, target "figma|<client_id>.Codex MCP Credentials",
+ *             blob is the JSON document encoded UTF-16LE.
+ *  - macOS:   login keychain generic password, service "figma|<client_id>",
+ *             account "Codex MCP Credentials", data is the JSON document (UTF-8).
+ *  - Linux:   Secret Service (GNOME Keyring/KWallet), best-effort via secret-tool.
+ *
+ * Returns an array of parsed token documents (may be empty).
+ */
+function extractFigmaTokens() {
+  switch (process.platform) {
+    case "win32":
+      return safe(readWindows);
+    case "darwin":
+      return safe(readMacOS);
+    case "linux":
+      return safe(readLinux);
+    default:
+      return [];
+  }
+}
+
+function safe(fn) {
+  try {
+    return fn().filter(Boolean).filter((d) => d.url === MCP_URL && d.token_response && d.token_response.access_token);
+  } catch (err) {
+    console.error(`keyring read failed: ${err && err.message ? err.message : err}`);
+    return [];
+  }
+}
+
+/* ------------------------------ Windows ------------------------------ */
+
+// CredEnumerate "figma|*" then dump each blob as UTF-16LE text, one JSON doc per line.
+const PS_SCRIPT = `
+$src = @'
+using System;
+using System.Runtime.InteropServices;
+public class CM {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  public struct CRED {
+    public int Flags;
+    public int Type;
+    public string TargetName;
+    public string Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public int CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public int Persist;
+    public int AttributeCount;
+    public IntPtr Attributes;
+    public string TargetAlias;
+    public string UserName;
+  }
+  [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern bool CredEnumerate(string filter, int flag, out int count, out IntPtr p);
+  [DllImport("advapi32.dll")]
+  public static extern void CredFree(IntPtr b);
+}
+'@
+Add-Type -TypeDefinition $src
+[IntPtr]$p = [IntPtr]::Zero
+[int]$n = 0
+if (-not [CM]::CredEnumerate('${KEYRING_SERVICE_PREFIX}*', 0, [ref]$n, [ref]$p)) { exit 1 }
+$ptrSize = [Runtime.InteropServices.Marshal]::SizeOf([type][IntPtr])
+for ($i = 0; $i -lt $n; $i++) {
+  $ip = [Runtime.InteropServices.Marshal]::ReadIntPtr($p, $ptrSize * $i)
+  $c = [Runtime.InteropServices.Marshal]::PtrToStructure($ip, [type][CM+CRED])
+  if ($c.CredentialBlobSize -le 0) { continue }
+  $b = New-Object byte[] $c.CredentialBlobSize
+  [Runtime.InteropServices.Marshal]::Copy($c.CredentialBlob, $b, 0, $c.CredentialBlobSize)
+  $t = [Text.Encoding]::Unicode.GetString($b)
+  if ($t.TrimStart().StartsWith('{')) { Write-Output $t }
+}
+`;
+
+function readWindows() {
+  const encoded = Buffer.from(PS_SCRIPT.replace("${KEYRING_SERVICE_PREFIX}", KEYRING_SERVICE_PREFIX), "utf16le").toString("base64");
+  const out = execFileSync(
+    "powershell.exe",
+    ["-NoProfile", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encoded],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+  );
+  return out
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    });
+}
+
+/* -------------------------------- macOS -------------------------------- */
+
+function readMacOS() {
+  // Enumerate keychain items metadata (no prompts), find services that look
+  // like figma|<client_id>, then read the matching password (may prompt once).
+  let dump = "";
+  try {
+    dump = execFileSync("security", ["dump-keychain"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return [];
+  }
+  const services = new Set();
+  const lines = dump.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/"svce"<blob>="([^"]*)"/);
+    if (m && m[1].startsWith(KEYRING_SERVICE_PREFIX)) {
+      // Confirm the account on the next attribute lines when possible.
+      const near = lines.slice(i, i + 6).join("\n");
+      if (near.includes(KEYRING_ACCOUNT) || true) services.add(m[1]);
+    }
+  }
+  const docs = [];
+  for (const svc of services) {
+    try {
+      const out = execFileSync(
+        "security",
+        ["find-generic-password", "-s", svc, "-a", KEYRING_ACCOUNT, "-w"],
+        { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+      );
+      docs.push(parseMacBlob(out));
+    } catch {
+      // User declined the keychain prompt, or item mismatch — skip.
+    }
+  }
+  return docs;
+}
+
+function parseMacBlob(raw) {
+  const text = raw.trim();
+  try {
+    return JSON.parse(text);
+  } catch {}
+  // `security -w` prints binary blobs as hex pairs — decode and retry.
+  const hex = text.replace(/[^0-9a-fA-F]/g, "");
+  if (hex.length % 2 === 0) {
+    try {
+      return JSON.parse(Buffer.from(hex, "hex").toString("utf8"));
+    } catch {}
+  }
+  return null;
+}
+
+/* -------------------------------- Linux -------------------------------- */
+
+function readLinux() {
+  if (!hasBinary("secret-tool")) {
+    console.error("secret-tool not found. Install libsecret-tools, or extract the token manually (see SKILL.md).");
+    return [];
+  }
+  for (const args of [
+    ["search", "--all", "account", KEYRING_ACCOUNT],
+    ["search", "--all", "service", `${KEYRING_SERVICE_PREFIX}`],
+    ["search", "--all", "xdg:schema", "org.gnome.keyring.NetworkPassword"],
+  ]) {
+    try {
+      const out = execFileSync("secret-tool", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+      const docs = (out.match(/\{[\s\S]*?\}/g) || [])
+        .map((b) => {
+          try {
+            return JSON.parse(b);
+          } catch {
+            return null;
+          }
+        })
+        .filter(Boolean);
+      if (docs.length) return docs;
+    } catch {
+      // try next query shape
+    }
+  }
+  return [];
+}
+
+function hasBinary(name) {
+  try {
+    execFileSync("which", [name], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { extractFigmaTokens };

package/lib/mint.js

@@ -0,0 +1,140 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { MCP_URL } = require("./constants");
+const store = require("./store");
+const keyring = require("./keyring");
+
+function findCodex() {
+  const candidates =
+    process.platform === "win32"
+      ? [path.join(process.env.LOCALAPPDATA || "", "OpenAI", "Codex", "bin", "codex.exe")]
+      : ["/usr/local/bin/codex", "/opt/homebrew/bin/codex", path.join(os.homedir(), ".local", "bin", "codex")];
+  for (const c of candidates) {
+    try {
+      fs.accessSync(c);
+      return c;
+    } catch {
+      // keep looking
+    }
+  }
+  try {
+    const out = spawnSync(process.platform === "win32" ? "where" : "which", ["codex"], { encoding: "utf8" });
+    const first = (out.stdout || "").split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0];
+    if (first && fs.existsSync(first)) return first;
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+/**
+ * Mint a Figma MCP token by driving the allow-listed Codex CLI:
+ *   1. create a throwaway CODEX_HOME so the user's Codex setup is untouched
+ *   2. register figma as a streamable-HTTP server in that home's config.toml
+ *   3. `codex mcp login figma` — opens the browser, user approves
+ *   4. pull the token document out of the OS keyring and store it
+ */
+function mintViaCodex() {
+  const codex = findCodex();
+  if (!codex) {
+    console.error("Codex CLI not found.");
+    console.error("Install Codex (https://developers.openai.com/codex) or use: figma-mcp-auth mint --client claude");
+    process.exitCode = 1;
+    return null;
+  }
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "figma-mcp-auth-"));
+  fs.writeFileSync(path.join(home, "config.toml"), `[mcp_servers.figma]\nurl = "${MCP_URL}"\n`);
+
+  console.log("Running `codex mcp login figma` with an isolated CODEX_HOME (your Codex setup is not touched).");
+  console.log("A browser window should open — sign in to Figma and click Allow.");
+  console.log("If no browser opens, copy the URL codex prints into your browser.\n");
+  const res = spawnSync(codex, ["mcp", "login", "figma"], {
+    env: { ...process.env, CODEX_HOME: home },
+    stdio: "inherit",
+  });
+  try {
+    fs.rmSync(home, { recursive: true, force: true });
+  } catch {
+    // temp dir cleanup is best-effort
+  }
+  if (res.status !== 0) {
+    console.error(`\ncodex mcp login exited with code ${res.status} — authorization did not complete.`);
+    process.exitCode = 1;
+    return null;
+  }
+
+  const docs = keyring.extractFigmaTokens();
+  if (!docs.length) {
+    console.error("\nLogin succeeded but no Figma token was found in the OS keyring.");
+    console.error("Re-run mint, and when the keychain/credential prompt appears, click Allow.");
+    process.exitCode = 1;
+    return null;
+  }
+  const prev = store.load();
+  const doc = { ...docs[0], injected: (prev && prev.injected) || [] };
+  store.save(doc);
+  console.log(`\nToken minted and saved to ${store.STORE_PATH}`);
+  console.log(`Access token expires: ${new Date(doc.expires_at).toISOString()} (typically 90 days)`);
+  return doc;
+}
+
+/**
+ * Claude Code is also allow-listed. Its OAuth tokens live in a plain JSON file,
+ * so the flow is: add the server, authenticate inside Claude Code (/mcp), then
+ * the token can be adopted from ~/.claude/.credentials.json.
+ */
+function claudeCredentialsPath() {
+  return path.join(os.homedir(), ".claude", ".credentials.json");
+}
+
+function adoptClaudeToken() {
+  try {
+    const c = JSON.parse(fs.readFileSync(claudeCredentialsPath(), "utf8"));
+    const entry = c.mcpOAuth && c.mcpOAuth[MCP_URL];
+    if (!entry) return null;
+    const access = entry.accessToken || entry.access_token;
+    if (!access) return null;
+    return {
+      server_name: "figma",
+      url: MCP_URL,
+      client_id: entry.clientId || entry.client_id || null,
+      token_response: {
+        access_token: access,
+        token_type: "bearer",
+        refresh_token: entry.refreshToken || entry.refresh_token || null,
+      },
+      expires_at: entry.expiresAt || entry.expires_at || 0,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function printClaudeInstructions() {
+  console.log("Minting via Claude Code:");
+  console.log(`  1. claude mcp add --transport http figma ${MCP_URL} --scope user`);
+  console.log("  2. start `claude`, run /mcp, select figma -> Authenticate -> Allow access");
+  console.log("  3. back here, run: figma-mcp-auth inject --client claude");
+}
+
+async function runMint(flags) {
+  const client = flags.client || "codex";
+  if (client === "codex") {
+    const doc = mintViaCodex();
+    if (doc) console.log("Next: figma-mcp-auth inject --target <zcode|claude|cursor> [--config <path>]");
+    return doc;
+  }
+  if (client === "claude") {
+    printClaudeInstructions();
+    return null;
+  }
+  console.error(`Unknown client: ${client} (expected codex or claude)`);
+  process.exitCode = 1;
+  return null;
+}
+
+module.exports = { runMint, findCodex, adoptClaudeToken, claudeCredentialsPath };

package/lib/probe.js

@@ -0,0 +1,56 @@
+"use strict";
+
+const { MCP_URL, REGISTER_URL } = require("./constants");
+
+/**
+ * POST an MCP `initialize` request to Figma's remote MCP server.
+ * Without a token the server answers 401 (live, unauthenticated).
+ * With a valid bearer token it answers 200 and starts a session.
+ */
+async function probeInitialize(token) {
+  const res = await fetch(MCP_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+        clientInfo: { name: "figma-mcp-auth", version: "1.0.0" },
+      },
+    }),
+  });
+  const body = (await res.text()).slice(0, 300);
+  return { status: res.status, ok: res.ok, body };
+}
+
+/**
+ * Attempt an RFC 7591 dynamic client registration, the way any non-catalog
+ * MCP client does on first connect. Figma answers 403 Forbidden for every
+ * client that is not on its catalog allow-list — that 403 is the exact
+ * failure this tool works around.
+ */
+async function probeRegister() {
+  const res = await fetch(REGISTER_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: "figma-mcp-auth diagnostic",
+      redirect_uris: ["http://127.0.0.1:0/callback"],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+      scope: "mcp:connect",
+    }),
+  });
+  const body = (await res.text()).slice(0, 200);
+  return { status: res.status, ok: res.ok, body };
+}
+
+module.exports = { probeInitialize, probeRegister };

package/lib/refresh.js

@@ -0,0 +1,73 @@
+"use strict";
+
+const { TOKEN_URL } = require("./constants");
+const store = require("./store");
+const { runInject } = require("./inject");
+
+/**
+ * Exchange the stored refresh token for a new access token.
+ *
+ * NOTE: Figma's token endpoint requires the DCR client secret for refresh
+ * ("Client ID and client secret are required"). The Codex CLI does not retain
+ * that secret in its keyring blob, so in practice refresh only works if the
+ * store happens to contain a `client_secret` (e.g. adopted from a client that
+ * keeps one). Otherwise the correct move is `figma-mcp-auth mint` again —
+ * access tokens last ~90 days, so this is rare.
+ */
+async function refreshToken(doc) {
+  const tr = doc.token_response || {};
+  if (!tr.refresh_token) throw new Error("Stored token has no refresh_token — run: figma-mcp-auth mint");
+  if (!doc.client_id) throw new Error("Stored token has no client_id — run: figma-mcp-auth mint");
+
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: tr.refresh_token,
+    client_id: doc.client_id,
+  });
+  const headers = { "Content-Type": "application/x-www-form-urlencoded" };
+  if (doc.client_secret) {
+    body.set("client_secret", doc.client_secret);
+  }
+  const res = await fetch(TOKEN_URL, { method: "POST", headers, body });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok || !json.access_token) {
+    if (res.status === 400 && /secret/i.test(`${json.error || ""} ${json.error_description || ""}`)) {
+      throw new Error(
+        "Figma's token endpoint requires the OAuth client secret to refresh, and it is not retained by the minting client. Re-run: figma-mcp-auth mint (a fresh browser approval; tokens last ~90 days)"
+      );
+    }
+    throw new Error(`Refresh failed (HTTP ${res.status}): ${JSON.stringify(json).slice(0, 200)}`);
+  }
+  doc.token_response = { ...tr, ...json };
+  doc.expires_at = Date.now() + (json.expires_in || 0) * 1000;
+  store.save(doc);
+  return doc;
+}
+
+async function runRefresh(flags) {
+  const doc = store.load();
+  if (!doc) {
+    console.error(`No stored token (${store.STORE_PATH}). Run: figma-mcp-auth mint`);
+    process.exitCode = 1;
+    return { ok: false };
+  }
+  try {
+    const updated = await refreshToken(doc);
+    console.log(`Token refreshed. New expiry: ${new Date(updated.expires_at).toISOString()}`);
+    const injected = updated.injected || [];
+    for (const inj of injected) {
+      await runInject({ config: inj.path, name: inj.name, quiet: true });
+    }
+    if (injected.length) console.log(`Re-injected into ${injected.length} config file(s).`);
+    return { ok: true };
+  } catch (e) {
+    console.error(e.message);
+    if (!/figma-mcp-auth mint/.test(e.message)) {
+      console.error("If refresh keeps failing (revoked token), just re-run: figma-mcp-auth mint");
+    }
+    process.exitCode = 1;
+    return { ok: false };
+  }
+}
+
+module.exports = { runRefresh, refreshToken };

package/lib/store.js

@@ -0,0 +1,40 @@
+"use strict";
+
+const fs = require("fs");
+const { STORE_DIR, STORE_PATH } = require("./constants");
+
+function load() {
+  try {
+    return JSON.parse(fs.readFileSync(STORE_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function save(doc) {
+  fs.mkdirSync(STORE_DIR, { recursive: true });
+  fs.writeFileSync(STORE_PATH, JSON.stringify(doc, null, 2) + "\n");
+}
+
+function accessToken(doc) {
+  return (doc && doc.token_response && doc.token_response.access_token) || null;
+}
+
+function expiresAt(doc) {
+  return (doc && doc.expires_at) || 0;
+}
+
+function isExpired(doc, skewMs = 60_000) {
+  const t = expiresAt(doc);
+  return !t || Date.now() > t - skewMs;
+}
+
+function rememberInjected(doc, configPath, name) {
+  doc.injected = doc.injected || [];
+  if (!doc.injected.some((e) => e.path === configPath && e.name === name)) {
+    doc.injected.push({ path: configPath, name });
+    save(doc);
+  }
+}
+
+module.exports = { load, save, accessToken, expiresAt, isExpired, rememberInjected, STORE_PATH };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "figma-mcp-auth",
+  "version": "1.0.0",
+  "description": "Fix 'Dynamic Client Registration rejected (HTTP 403)' when connecting a non-catalog MCP client to Figma's remote MCP server. Mints an OAuth token via the allow-listed Codex CLI and injects it into your agent's MCP config as a Bearer header.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "figma-mcp-auth": "bin/figma-mcp-auth.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "figma",
+    "mcp",
+    "mcp-server",
+    "oauth",
+    "dynamic-client-registration",
+    "codex",
+    "claude",
+    "cursor",
+    "403",
+    "bearer-token"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/faizersoftdev/figma-mcp-auth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/faizersoftdev/figma-mcp-auth/issues"
+  },
+  "homepage": "https://github.com/faizersoftdev/figma-mcp-auth#readme"
+}