# ridvay-mcp MCP (Model Context Protocol) server that lets AI assistants — Claude Code, Claude Desktop, GitHub Copilot (VS Code agent mode), Cursor, and any other MCP client — create and edit **[Ridvay Studio](https://ridvay.com/studio)** posters, flyers, and social designs straight from a chat conversation. Every design comes back as a working share link (`ridvay.com/d/…`) plus links to open and edit it in the Studio editor. ## Hosted endpoint (no install) The same server runs at **https://mcp.ridvay.com** (streamable HTTP). Two ways to authenticate: - **URL with your key** — for clients that add connectors by URL and cannot set headers (claude.ai custom connectors, ChatGPT connectors): `https://mcp.ridvay.com/mcp/sk-ridvay-…`. Treat that URL like the key itself; revoke it any time at ridvay.com/user/api-keys. - **Bearer header** — for clients that support headers: `https://mcp.ridvay.com/mcp` with `Authorization: Bearer sk-ridvay-…`. Claude Code: `claude mcp add --transport http ridvay https://mcp.ridvay.com/mcp --header "Authorization: Bearer sk-ridvay-…"`. - **Try it without an account** — `https://mcp.ridvay.com/mcp/demo` is a sandbox: no key, no sign-up, the free tools only (design guide, compose a design, render, export PNG, share). Designs made there are public and may be removed; it is rate-limited per network. Claude Code: `claude mcp add --transport http ridvay-demo https://mcp.ridvay.com/mcp/demo`. - **Sign in (OAuth 2.1)** — for clients that support MCP OAuth (claude.ai custom connectors, ChatGPT connectors/plugins, Claude Code, Cursor, MCP Inspector): add `https://mcp.ridvay.com/mcp` with no key, and the client discovers `api.ridvay.com` as the authorization server, registers itself (Dynamic Client Registration) or presents a Client ID Metadata Document, and sends you to `ridvay.com/oauth/consent` to approve. The token it receives is a normal Ridvay API key named " (OAuth)", so you can revoke it any time from your account page (or the client can call the revocation endpoint). ### Living designs tools (0.6.0) `list_designs`, `share_design` (view / edit / live-image / screen links), `get_values` and `set_values` (update a design's declared `{{variables}}` — a menu board or price board that refreshes itself on the `/screen/` page and the `/img/.png` live image), and `list_brands` (pass `brand_id` to `generate_poster`). ## How it works  *Every frame of that GIF was designed and rendered by this MCP server* — a four-page design composed as design IR, saved with `create_poster`, then exported page by page with `export_poster`. No screen recording, no image editor. ## Tools | Tool | What it does | |------|--------------| | `get_design_guide` | **Start here** — the design-IR authoring spec (element types, backgrounds, fonts, worked example) that teaches your assistant to compose designs itself. | | `create_poster` | **The preferred path:** your assistant composes the design as Ridvay design IR — Ridvay only stores, renders, and shares it. Fast, free, full creative control. | | `generate_poster` | Fallback: Ridvay's AI designs from a text brief (slower, consumes the account's generation credits). | | `recreate_poster` | Turn an **existing design image** (poster photo, screenshot, export — file path or URL) into an editable design: text becomes editable, shapes become vectors, imagery is re-rendered fresh. Slow (1–4 min), uses generation credits. | | `refine_poster` | Natural-language edit of an existing design (`design_id`, `instruction`). | | `check_poster` | Report whether a design's AI images finished rendering and return its links + view count (`Views: N`). | | `export_poster` | Render a design to a downloadable **PNG/JPEG** at its native pixel size (`scale` 1–4, default 2). | | `animate_poster` | Add motion (entrance/exit, page transitions, morph) — blank for a tasteful default, or describe it. | | `export_video` | Render an animated design to a downloadable **H.264 MP4** (optional looped soundtrack). | | `check_export` | Poll an async `export_poster` / `export_video` job for its download URL. | Your AI client is the designer; Ridvay is the save/render/share backend. Client-authored designs may still include `prompt` image slots — Ridvay renders those server-side after creation. `generate_poster` remains for when the assistant can't compose the design itself. **Export & motion:** `export_poster` gives you the actual poster image at its real dimensions (e.g. a 1080×1350 PNG), not the share page. For animation, either include motion fields when you compose the design (see the guide) or call `animate_poster`, then `export_video` for an MP4. `size` accepts `1080x1080` (default), `1080x1920` / `story`, `1080x1350`, `1920x1080`, `a4`, `slide`, or any `WxH`. ### Live images Every **shared** design also gets an always-current image URL — each fetch re-resolves the design's live data bindings (`{{time.now}}`, countdowns, JSON feeds, declared `{{vars}}`), so an embedded image never goes stale (re-rendered at most every 60 s): ``` https://ridvay.com/img/{designId}.png ``` Declared vars are filled from query params, which makes personalized email images a one-URL job with your ESP's merge tags: ``` https://ridvay.com/img/abc123.png?name=*|FNAME|* ``` A `.jpg` variant plus `page`, `scale`, `w`, and `quality` params are supported — see `get_design_guide` ("Live data bindings + live image URL") for the bindings format (including the reserved param names that can't double as binding/var keys). Every live-image load and every `/d/` share-page view counts toward the design's view count — `check_poster` reports it as `Views: N`. ## Get an API key Sign in and create a key at **[ridvay.com/user/api-keys](https://ridvay.com/user/api-keys)**. Designs generated through MCP appear in your own *My designs*. ## Quickstart **Claude Code** ```bash claude mcp add --scope user ridvay --env RIDVAY_API_KEY=sk-ridvay-… -- npx -y ridvay-mcp ``` **Claude Desktop** — add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "ridvay": { "command": "npx", "args": ["-y", "ridvay-mcp"], "env": { "RIDVAY_API_KEY": "sk-ridvay-…" } } } } ``` **VS Code / GitHub Copilot agent mode** — add to your user `mcp.json` (Command Palette → "MCP: Open User Configuration"), then enable **ridvay** in the Copilot Chat tools picker: ```json { "servers": { "ridvay": { "type": "stdio", "command": "npx", "args": ["-y", "ridvay-mcp"], "env": { "RIDVAY_API_KEY": "sk-ridvay-…" } } } } ``` Then ask your assistant things like: > Generate a story-size poster for our weekend flash sale — 30% off everything, Saturday only. ## Examples **A poster, straight from a brief** > Generate a story-size poster for our weekend flash sale — 30% off everything, Saturday only. **A promo video, end to end** — design, animation, and MP4 in one turn: > Using the ridvay MCP, create a 3-page 1080x1920 promo video design about [topic]. Page 1: a > bold hook. Page 2: three or four key points with accent bars. Page 3: a worked example plus a > call to action. Dark navy background, blue accents, Poppins headlines. Then animate it with > snappy staggered entrances and morph transitions, and render it to MP4. **An existing design, made editable again** > Recreate ~/Desktop/last-years-flyer.png as an editable design, then change the date to > October 3rd and set the headline in our brand blue. **An image that never goes stale** — live bindings resolve on every fetch: > Build a 1080x1080 status card with today's date and a countdown to our September 1 launch, > then give me the live image URL. A longer walkthrough of the video example, with the agent's actual tool sequence, is on the blog: **[Ridvay MCP: free AI design generation from Claude Code](https://ridvay.com/blog/ridvay-mcp)**. ## Environment | Var | Required | Meaning | |-----|----------|---------| | `RIDVAY_API_KEY` | yes | Your Ridvay API key (`sk-ridvay-…`). | | `RIDVAY_API_URL` | no | Default `https://api.ridvay.com`. | | `RIDVAY_WEB_URL` | no | Base for returned links, default `https://ridvay.com`. | | `RIDVAY_SUB_USER_ID` | no | Admin/platform keys only: act on behalf of a specific user. | ## Behavior notes - **Sharing:** `generate_poster` / `create_poster` create an unlisted public share link by default so the chat reply contains a working `/d/{id}` URL. Pass `share: false` to keep a design private to your account (only the Studio edit link is returned). - **Deferred images:** generation returns as soon as the layout is ready; AI/stock images render server-side in the background (~1 min). `check_poster` reports on and, if needed, re-triggers that pass. ## Telemetry Content and usage data from the MCP (such as prompts and generated designs) may be used to improve Ridvay's products, services, and AI features. Requests include basic attribution: the connecting MCP client's name/version and, when the assistant provides the optional `agent_model` argument, the model id that authored the design. ## Development ```bash npm install npm run build # emits dist/ npm test # vitest unit suite node dist/index.js # run the stdio server directly (needs RIDVAY_API_KEY) ``` MIT © Ridvay