====== Setting up Penpot MCP for Codex ======
This page describes how to connect Codex to Penpot using the hosted Penpot MCP server.
===== How the connection works =====
Codex connects to the hosted Penpot MCP endpoint provided by Penpot. The currently open Penpot file must also be connected from the browser side.
<code>
Codex -> hosted Penpot MCP server -> Penpot browser connection -> current Penpot file
</code>
===== 1. Enable MCP in Penpot =====
In Penpot:
  * Go to **Account -> Integrations**
  * Enable **MCP Server**
  * Generate/copy the MCP credentials
Penpot provides the credentials as JSON, for example:
<code json>
{
  "mcpServers": {
    "penpot": {
      "url": "https://design.penpot.app/mcp/stream?userToken=YOUR_PENPOT_MCP_TOKEN"
    }
  }
}
</code>
===== 2. Save the MCP credentials =====
In your project directory, save the JSON as:
<code>
.mcp.json
</code>
Do not commit this file. The ''userToken'' is a secret.
===== 3. Install Codex =====
Codex requires Node.js/npm.
<code bash>
npm install -g @openai/codex
codex login
</code>
===== 4. Register Penpot MCP in Codex =====
From the same project directory, run:
<code bash>
codex mcp add penpot --url "$(jq -r '.mcpServers.penpot.url' .mcp.json)"
</code>
This reads the hosted Penpot MCP URL from ''.mcp.json'' and adds it to Codex as an MCP server named ''penpot''.
===== 5. Connect the Penpot file =====
Open the relevant Penpot design file in the browser.
Then connect the file to MCP from the Penpot UI:
  * Open the design file
  * Choose **… (three dots menu) -> MCP Server -> Connect**
  * Keep the Penpot browser tab open while Codex is using the design
===== 6. Verify in Codex =====
Start Codex in the project directory:
<code bash>
codex
</code>
Inside Codex, run:
<code>
/mcp
</code>
The ''penpot'' MCP server should appear in the list.
You can also ask Codex to inspect the connected design, for example:
<code>
List all pages in the connected Penpot file.
</code>