Cursor

Cursor reads MCP servers from a JSON file. Project config lives at .cursor/mcp.json; global config at ~/.cursor/mcp.json. Galley is an HTTP server, so the entry is a URL and nothing else — there is no command to install and no process to run.

Project config

.cursor/mcp.json

{
  "mcpServers": {
    "galley": {
      "url": "https://mcp.galleyrender.com/mcp"
    }
  }
}

That is enough to start. No key, no signup: the first render mints a 50-render trial and returns its token in the response.

With a key:

.cursor/mcp.json

{
  "mcpServers": {
    "galley": {
      "url": "https://mcp.galleyrender.com/mcp",
      "headers": {
        "X-Galley-Api-Key": "glr_sk_…"
      }
    }
  }
}

Caution

.cursor/mcp.json sits in your repository. Do not commit a key in it. Either put the keyed entry in ~/.cursor/mcp.json instead, or commit the keyless form and add .cursor/mcp.json to .gitignore on machines that need a key.

Global config

~/.cursor/mcp.json applies to every project you open. Same shape:

~/.cursor/mcp.json

{
  "mcpServers": {
    "galley": {
      "url": "https://mcp.galleyrender.com/mcp",
      "headers": {
        "X-Galley-Api-Key": "glr_sk_…"
      }
    }
  }
}

A per-project entry with the same name takes precedence over the global one, which is the usual way to point one repository at a different account.

Keeping one trial without a key

The keyless trial is identified by a hash of your IP and User-Agent, so it resets when your network changes. To hold on to one trial across restarts and coffee shops, declare a stable client id instead of a key:

~/.cursor/mcp.json

{
  "mcpServers": {
    "galley": {
      "url": "https://mcp.galleyrender.com/mcp",
      "headers": {
        "X-Galley-Client-Id": "cursor-mm-7f3c9a21"
      }
    }
  }
}

Any opaque string between 8 and 200 characters works. See how you are identified.

Confirm it connected

1. Open Settings → Cursor Settings → MCP (or Tools & Integrations, depending on your version).

2. galley should be listed with a green indicator.

3. Expand it. Ten tools should be there:

   list_templates	get_template	create_template
   update_template	validate_data	render
   get_render	list_renders	usage
   create_account

If the row is red or the tool list is empty, hit the refresh control on the server entry — Cursor caches the tool list and only re-reads mcp.json on reload.

You can also check the endpoint directly, independent of Cursor:

curl -sS https://mcp.galleyrender.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Ten tools in the response means the server is fine and the problem is in the config file.

A worked example

In Composer or chat, with Agent mode on:

Make me an OG image for a blog post titled “Deterministic PDFs for agents”, with the subtitle “Same input, same file, every time”. Use Galley’s og-card template, 1200×630 at 2× scale, and give me the URL.

Cursor will ask to run the tools; approve them. A good run is:

1. list_templates → finds og-card in the starter library.
2. get_template with {"template": "og-card"} → reads the schema: title is required; subtitle, eyebrow, accent and background are optional with defaults.
3. render:

{
  "template": "og-card@1",
  "format": "png",
  "data": {
    "eyebrow": "Galley Render",
    "title": "Deterministic PDFs for agents",
    "subtitle": "Same input, same file, every time",
    "accent": "#2dd4bf",
    "background": "#0b0f14"
  },
  "options": { "width": 1200, "height": 630, "scale": 2 }
}

Result

{
  "object": "render",
  "id": "rnd_7hq2m4x8k1bv",
  "status": "succeeded",
  "template": "og-card@1",
  "format": "png",
  "cached": false,
  "url": "https://<account>.r2.cloudflarestorage.com/galley-renders/renders/…?X-Amz-Expires=3600&X-Amz-Signature=…",
  "page_count": 1,
  "billable_units": 1
}

The og-card starter renders on the Satori engine, so this comes back in tens of milliseconds rather than the hundreds a browser render takes.

Ask for the same thing twice and the second call returns "cached": true, instantly and for free.

Tip

Tell Cursor to pin the version — og-card@1, not og-card — in anything it writes into your codebase. An unpinned reference follows latest, so a template change silently changes your output. See Template versions.

Troubleshooting

Symptom	Cause
Server listed but no tools	Reload the MCP settings pane, or restart Cursor. The tool list is cached.
authentication_error	The header value is not a Galley key. Keys start with glr_sk_.
quota_exceeded	The 50 trial renders are spent. Ask the agent to call create_account with your email, click the link, then ask again.
A fresh trial every few days	Add X-Galley-Client-Id, or carry the trial token as X-Galley-Api-Key.
Invalid JSON on startup	mcp.json must be a single object with one mcpServers key. Trailing commas are not allowed.