@imgly/codesign-mcp

MCP server exposing a CE.SDK CreativeEngine for vector design + print-quality PDF output. Ships skills (Iris design loop, cesdk-api signatures, cesdk-guide docs), tools (design_exec, design_capture), and prompts as MCP resources.

Install

The recommended install is via npm — hosts spawn it with npx, so there's no separate install step:

# Claude Code
claude mcp add codesign -- npx -y @imgly/codesign-mcp stdio

For Claude Desktop (JSON mcpServers block) and Codex (TOML [mcp_servers.codesign]), see docs/codesign-mcp-beta-install.md for the exact per-host snippets — all spawn npx -y @imgly/codesign-mcp stdio.

Set CESDK_LICENSE in the server's env to use your own CE.SDK node license; during the internal beta a 30-day trial is bundled, so it's optional.

From a GitHub Release tarball (offline / air-gapped)

Releases also ship a self-contained tarball with a date-based, commit-derived version — 0.1.0-<YYYYMMDD>-g<shortSHA>:

npm i -g https://github.com/imgly/imgly-codesign/releases/download/<tag>/imgly-codesign-mcp-0.1.0-<YYYYMMDD>-g<sha>.tgz
codesign-mcp --help

Build the tarball locally (output in <repo>/release/):

pnpm run release:tarball        # from the repo root

Run

One bin, two transports:

codesign-mcp stdio              # MCP over stdin/stdout
codesign-mcp http               # MCP over Streamable HTTP (default :3030)
codesign-mcp --help

Env: CESDK_LICENSE (CE.SDK headless engine license string). For stdio it is optional when a trial license is bundled in the build (see Install); otherwise required.

Stdio mode

Spawned by hosts that manage MCP servers as subprocesses (Claude Desktop, Claude Code via command).

CESDK_LICENSE=… codesign-mcp stdio

Host config example:

{
  "mcpServers": {
    "codesign": {
      "command": "codesign-mcp",
      "args": ["stdio"],
      "env": { "CESDK_LICENSE": "..." }
    }
  }
}

HTTP mode

Long-running listener; hosts connect via URL. Useful for multiple clients, keeping engines warm across requests, and running on a different host than the MCP client.

CESDK_LICENSE=… codesign-mcp http \
  --port 3030 --host 127.0.0.1 \
  --max-sessions 10 --idle-timeout-ms 1800000

All flags fall back to env vars (PORT, HOST, MAX_SESSIONS, IDLE_TIMEOUT_MS).

Endpoint: POST/GET/DELETE http://<host>:<port>/mcp (Streamable HTTP).

Host config example:

{
  "mcpServers": {
    "codesign": {
      "type": "http",
      "url": "http://127.0.0.1:3030/mcp"
    }
  }
}

Per-session engine

HTTP mode allocates a fresh CE.SDK headless engine for every MCP session (scoped by the Mcp-Session-Id header). Engines are isolated — two concurrent sessions cannot corrupt each other's scenes. Idle sessions (no activity for idle-timeout-ms) are evicted on a periodic sweep; new sessions over max-sessions get 503 Service Unavailable with Retry-After: 30.

Stdio mode uses a single engine for the lifetime of the process.

Embedding

The HTTP server is also exposed as a programmatic factory for callers that want to mount it inside a larger Express app or compose multiple MCP servers behind a single port:

import { createCodesignHttpServer } from '@imgly/codesign-mcp';
import { ensureHeadlessEngine } from '@imgly/codesign-mcp';
import { buildDesignToolRegistrations } from '@imgly/codesign-mcp';
import { loadNodeAssets } from '@imgly/codesign-mcp/assets/node';

const license = process.env.CESDK_LICENSE!;
const app = await createCodesignHttpServer({
  assets: loadNodeAssets(),
  maxSessions: 10,
  idleTimeoutMs: 30 * 60 * 1000,
  createEngine: () => ensureHeadlessEngine(license),
  buildTools: (engine) => buildDesignToolRegistrations({ license, engine }),
  // optional auth + cors hooks (no-op by default)
  auth: (req, res, next) => {
    /* check Bearer token, etc. */ next();
  },
  cors: { origin: ['https://my.frontend'] }
});
app.listen(3030, '127.0.0.1');

Going remote

The defaults (HOST=127.0.0.1, no auth, no CORS) target localhost dev. To expose remotely:

1. TLS: front with caddy / nginx, or terminate in your own Express app.
2. Auth: wire auth middleware (Bearer token / OAuth / mTLS).
3. CORS: wire cors for browser clients (Claude.ai web, custom UIs).
4. Resource limits: tune max-sessions and idle-timeout-ms for the target hardware (each engine is ~200–500 MB resident).

The hooks are pluggable from day one — going remote is config, not refactor.