如何透過 Codex CLI 將 Figma MCP 連接至 Zoo Code（macOS 和 Windows）

By Muhammad Hammad Khan

A practical setup and troubleshooting guide for connecting Figma's hosted remote MCP server to Zoo Code inside Android Studio, using Codex CLI, without requiring a Claude subscription. The macOS process reflects the setup actually completed; Windows credential handling is marked where it was not tested.

Critical configuration detail: "type": "streamable-http" (not "type": "http") resolved Zoo Code's "Invalid MCP settings format" error in the tested setup.

Version context: Zoo Code 3.90.0, Android Studio, Figma remote MCP, Codex CLI

1. Overview and safety

The remote Figma MCP endpoint is https://mcp.figma.com/mcp. It works with browser-based Figma; the Figma desktop app is not required for the remote server.

Codex CLI was used to authorize Figma. Claude Code was briefly explored but not used for the final connection, because the goal was to avoid buying a Claude subscription just to authorize Figma.

This workflow uses a workaround/helper to transfer an existing Figma MCP credential into Zoo Code. It is not an officially documented, first-party Figma-to-Zoo-Code integration. Figma notes that direct remote-server support is limited to listed clients; support and authentication behavior can change.

Security rules

• Never publish a bearer token, Keychain export, credential file, or screenshot that reveals a token.
• Back up configuration before editing; do not commit mcp_settings.json or local credential files to Git.
• Keep the normal Codex configuration intact. Do not expose credentials in chat or shell logs.
• Only authorize an account permitted to access the target Figma file.

MCP vs Code Connect

MCP lets the coding agent call Figma tools to read design context. Code Connect is an optional mapping from Figma components to real components in a codebase. Code Connect was not required to establish the MCP connection.

2. macOS: completed workflow

Step 1: Verify Node.js and npm

node --version
npm --version

Step 2: Install and verify Codex CLI

npm install -g @openai/codex
codex --version

The tested machine reported Codex CLI 0.163.0. Your version may differ.

Step 3: Sign in to Codex CLI

codex login

Complete the browser-based sign-in flow. Codex must be authenticated before the helper can launch the Figma MCP login flow.

Step 4: Start Figma authorization through the helper

npx figma-mcp-auth mint

The helper launched a Codex MCP login flow using an isolated CODEX_HOME, opened a browser, and asked for Figma authorization. Sign in to the intended Figma account and click Allow. The isolated home was intended to avoid changing the normal Codex setup.

Do not use the Claude route. The Claude-specific path would require Claude Code authentication; Codex CLI was chosen instead to avoid a Claude subscription.

Step 5: Verify Codex has the Figma MCP server

codex mcp list

Confirm the figma entry points to https://mcp.figma.com/mcp and shows OAuth enabled. The list does not need to display the token.

Step 6: Diagnose the helper's Keychain lookup

The first injection attempt failed because the helper could not find a Figma token. On the tested Mac, Keychain metadata showed this arrangement:

service: Codex MCP Credentials
account: figma|<client-id>

The helper originally expected the opposite arrangement (service beginning with figma| and account Codex MCP Credentials). The local helper's lib/keyring.js was adjusted to search the actual Mac Keychain arrangement. A safe check then confirmed a matching credential and valid access token without printing the secret.

Step 7: Check the helper's URL constants

The inspected published package had malformed URL constants in its local source. They were corrected only after inspecting that package build. If your installed version already has correct constants, do not overwrite them.

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";
const KEYRING_ACCOUNT = "Codex MCP Credentials";
const KEYRING_SERVICE_PREFIX = "figma|";

OAuth endpoints and helper internals can change. Inspect the version you are actually using; if the constants differ, consult the package maintainer and current Figma docs rather than guessing.

Step 8: Save the matching credential to the helper's local store

A local transfer script read the matching Keychain credential and saved it to the helper's local token store. It validated that the credential matched the Figma MCP URL and was unexpired, and reported the expiry without printing the token. This transfer script was environment-specific; do not recreate it by guesswork or expose the secret.

Step 9: Open Zoo Code's global MCP settings

In Android Studio, open Zoo Code → MCP Servers → Edit Global MCP. The tested macOS path was:

~/.zoo-code/globalStorage/wecode-ai.zoo-code/settings/mcp_settings.json

The file initially contained an empty mcpServers object. Back it up before editing.

{
  "mcpServers": {}
}

Step 10: Inject the credential

After the local token store was populated, the helper's dry run showed that it would update the figma entry. Review dry-run output first, then run:

npx figma-mcp-auth inject --client codex --target zcode

The helper reported that the Zoo Code settings file had been updated. Command behavior can vary by package version; check its README/help before running it in another environment. Do not inject before token lookup succeeds.

Step 11: Correct the transport type (critical fix)

The first config used "type": "http" and Zoo Code returned Invalid MCP settings format: mcpServers.figma: Invalid input. Changing the value to "streamable-http" resolved the validation error.

{
  "mcpServers": {
    "figma": {
      "type": "streamable-http",
      "url": "https://mcp.figma.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_EXISTING_TOKEN"
      }
    }
  }
}

Keep the real token only in your local file; the placeholder above is for documentation. Preserve all quotes, commas, and braces. The endpoint must be the plain URL shown, not a Markdown-formatted link.

Step 12: Restart and test

• Restart Zoo Code or start a fresh agent session.
• Ask: "List the available tools from the Figma MCP server."
• Paste the complete Figma file URL and ask the agent to inspect a specific frame/node.
• If it asks for fileKey, provide the file URL. Server configuration alone does not identify the file you want to inspect.

3. Windows: equivalent steps and important limitation

The successful credential transfer described above was performed on macOS. The helper version was adjusted for macOS Keychain; Windows uses a different credential store. Do not treat the Windows credential-transfer portion as verified end-to-end until tested on a Windows machine.

Step 1: Install prerequisites

Install Node.js from nodejs.org. Open PowerShell and verify:

node --version
npm --version

Step 2: Install and authenticate Codex CLI

npm install -g @openai/codex
codex --version
codex login

Complete the browser-based Codex login. Then run the helper authorization command and approve Figma in the browser:

npx figma-mcp-auth mint

Step 3: Confirm Codex Figma entry

codex mcp list

Confirm the Figma entry and endpoint https://mcp.figma.com/mcp.

Step 4: Check Windows credential-store support before injection

The Mac-specific Keychain lookup cannot be used on Windows. Inspect the helper source and documentation to confirm it supports Windows Credential Manager or another secure Windows credential source. If it does not, stop and use a reviewed Windows-compatible method or ask the maintainer to add support. Do not print tokens or paste secrets into scripts, chats, or tickets.

Step 5: Locate Zoo Code global settings

In Android Studio, open Zoo Code → MCP Servers → Edit Global MCP. Use the actual path opened by the extension. If needed, search the user profile for mcp_settings.json under Zoo Code's globalStorage directory. Back up the file.

Step 6: Configure the server

{
  "mcpServers": {
    "figma": {
      "type": "streamable-http",
      "url": "https://mcp.figma.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_EXISTING_TOKEN"
      }
    }
  }
}

Use a real token only after secure, supported transfer. Do not use "type": "http" in the tested Zoo Code version.

Step 7: Restart and verify

• Restart Zoo Code or create a new agent session.
• Ask it to list Figma MCP tools.
• Supply the complete Figma file URL and target frame/node.
• If validation fails, check transport type, JSON syntax, endpoint, and header structure before debugging authentication.

4. Troubleshooting

5. End-to-end verification checklist

• Codex CLI is installed and authenticated.
• Codex lists the Figma MCP server and correct remote endpoint.
• The helper can securely locate an unexpired credential without printing it.
• Zoo Code's global config contains the figma server entry.
• The transport is exactly streamable-http.
• The endpoint is exactly https://mcp.figma.com/mcp.
• Authorization is a Bearer header and the token remains private.
• Zoo Code has been restarted or a fresh agent session opened.
• The agent lists Figma tools and can read the target file when given its URL.

A config entry by itself is not proof of success. Confirm the agent can list tools and read the intended design.

6. Prompts to test the connection

Check tool availability

List the tools available from the connected Figma MCP server. Report any connection or authentication error exactly.

Inspect a design

Inspect this Figma design: PASTE_THE_COMPLETE_FIGMA_FILE_URL. Use the connected Figma MCP tools. Identify the file and target node from the URL. Read the selected frame's design context.

7. Code Connect (optional)

Code Connect maps a Figma component to the corresponding real component in the codebase. For example, it can map a Figma button to a reusable Jetpack Compose button so generated code can reuse the existing implementation. It is not needed just to read designs with MCP. Choose "Not now" unless your project has reusable components ready to map.

8. References

• Figma: remote server installation
• Figma: guide to the MCP server
• Zoo Code: MCP configuration
• Figma: troubleshooting tools that do not load

The macOS keyring fix and helper-source adjustments were specific to the package version and local environment. The Windows credential transfer has not been verified end-to-end.

Muhammad Hammad Khan