Affinity Codex Plugin

Connect Codex to Affinity by Canva's native local MCP server for document inspection, vector and photo editing, page layouts, previews, reusable scripts, and a guided native-file handoff and refresh workflow for Cavalry.

This independent community plugin forwards Affinity's own MCP tools through a local SSE-to-stdio adapter. It includes a workflow skill, a global installer, and a harmless connection check. No cloud server or API key is needed for the local connection.

Affinity to Cavalry handoff

Open and save a current .af document, then open the destination composition in Cavalry. Ask Codex to “Plan an Affinity to Cavalry handoff for my open document.” The plugin adds five tools:

The default asset mode lets you drag the staged asset into Cavalry and choose Separate Layers in Cavalry's native dialog. The optional single_layer mode requests one footage layer through scripting; verify its render before using it. In our live Affinity 3.3.0/Cavalry 2.8.0 test, that scripted footage layer showed a blank image even though Affinity rendered colored artwork. Cavalry's scripting API does not expose the native Separate Layers dialog choice as a script argument, so the guided handoff keeps that choice in Cavalry's UI.

Save changes in Affinity before planning. The handoff does not save or alter the source document. It refuses to stage if the source document, saved file, or active Cavalry composition changes after planning. Existing Cavalry assets with the exact same path are reused. After import, inspect the layers and save the Cavalry scene. Re-save older Affinity files in the current version if Cavalry warns that they lack stable layer IDs for per-layer updates.

For later edits, save the .af file, ask Codex to plan and apply a refresh, then compare the previews. A completed reload confirms that Cavalry accepted reloadAsset and retained the same asset and composition layer IDs; it does not guarantee that the visible art changed. In our live test, Affinity's image changed while Cavalry's scripted footage preview remained unchanged, including after a short delay. Check the Cavalry view before saving. Cavalry documents that adding or removing Affinity layers after a Separate Layers import does not add or remove those Cavalry scene layers on reload; reimport the asset into the composition for structural changes. Cavalry Affinity Asset documentation.

Keep both apps open with their MCP servers enabled. Cavalry defaults to port 6768; set CAVALRY_MCP_PORT for a different port. The handoff connects only to the local Cavalry server when a handoff tool runs.

Related MCP server: Rail Connector MCP

Requirements

• macOS with a version of Affinity by Canva that includes the native MCP server, installed and open with that server enabled. Initially tested with Affinity 3.3.0.

• Node.js 20 or newer and npm.

• Python 3 and a recent Codex CLI with codex plugin add, available on PATH.

• Codex desktop for the plugin UI.

Install globally

git clone https://github.com/ebuberpg-prog/affinity-codex-plugin.git
cd affinity-codex-plugin
npm ci --ignore-scripts
python3 scripts/install-global.py

The installer copies the package and dependencies into ~/plugins/affinity, adds it to the existing personal marketplace at ~/.agents/plugins/marketplace.json, and installs/enables affinity@personal. Other marketplace entries are preserved, and a timestamped catalog backup is saved before updating it. Git history, environment files, and logs are excluded from the installed copy.

Restart Codex and open a new chat. Keep Affinity open and its MCP server enabled. The default port is 6767.

Try: “Use Affinity to inspect my open document.”

Verify and update

npm run check
npm test
npm run verify

npm test checks handoff and refresh planning, stale-file protection, preview output, and script construction without opening either app. npm run verify performs the native handshake, discovers tools, reads the SDK preamble, and executes only console.log. It does not edit documents. The native app initially exposed 11 tools; this plugin adds five workflow tools.

For updates:

git pull --ff-only
npm ci --ignore-scripts
python3 scripts/install-global.py

Restart Codex afterward. For local development, edit this checkout, check the connection, and rerun the installer to refresh the global copy. node_modules is ignored by Git and installed from the lockfile.

Connection and workflow

The adapter connects to http://127.0.0.1:6767/sse by default. To use a different app port, pass AFFINITY_MCP_PORT in the MCP process environment. For a command-line verification, use AFFINITY_MCP_PORT=YOUR_PORT npm run verify. The optional handoff connects to Cavalry at 127.0.0.1:6768 unless CAVALRY_MCP_PORT is set.

Native tool definitions, messages, results, and application instructions pass through without rewriting them. The five codex_affinity_* workflow tools are handled by the local adapter. The skill reads the native SDK preamble before scripting, uses current API documentation, preserves selection when changing spreads, and verifies edits through native previews.

Affinity may restrict SDK filesystem, network, or AI operations in its settings. NOT_ALLOWED results should be handled within those restrictions. Its SDK documents filesystem access as limited to Desktop. The plugin does not change application permissions.

The server also exposes optional global hint-search and issue-reporting tools. The skill requires explicit authorization before reporting issues, publishing hints, or sending private document/script content to those services. The local transport itself does not upload documents or transmit telemetry.

Package contents

• .codex-plugin/plugin.json: plugin identity, icon, and skill/MCP declarations.

• .mcp.json: local transport launch configuration.

• scripts/bridge.mjs: transport adapter using the pinned official MCP SDK.

• scripts/handoff-tools.mjs: planned Affinity-to-Cavalry native-file handoff, refresh, and visual comparison.

• scripts/handoff-tools.test.mjs: offline handoff checks.

• scripts/install-global.py: personal marketplace installer.

• scripts/verify.mjs: non-mutating smoke check.

• skills/affinity/SKILL.md: Affinity workflow guidance.

The package follows OpenAI's plugin format. For the native integration, see Affinity's integrations page. Plugin code and authored documentation are MIT-licensed. The native app icon is excluded; see NOTICE.md.