Edithly MCP — User guide

Connect Edithly to Cursor, Claude Desktop, VS Code, Codex CLI, or any MCP client to create PDFs, posters, mind maps, flashcards, solvesheets, and more from chat.

12 tools, one server

The Edithly MCP server exposes 12 tools covering discovery, generation, editing, export, and account status. The full reference is below — every tool, every parameter. Building a backend integration instead of an MCP client? See the API reference.

Before you connect

API key — Create one from your dashboard and copy it.
Credits — You need at least 1 credit for visuals and solvesheets, 4 for AI images.

Check your balance anytime with get_credit_balance.

Create an API key

Open the dashboard and switch to the API Portal tab.
Click Create API.
In the Create New API dialog, enter a name for the key (e.g. MCP Integration) and click Create API.

Create New API dialog

Copy the generated key right away — use it as YOUR_API_KEY in the MCP config below, either in the Authorization header or as the api_key argument on individual tool calls.

Connect in Cursor

Open Cursor Settings → MCP and add:

{
  "mcpServers": {
    "edithly": {
      "url": "https://api.edithly.com/api/v1/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your key.

Restart Cursor or reload MCP servers.

Connect in Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "edithly": {
      "url": "https://api.edithly.com/api/v1/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop.

Connect in VS Code

Open the Command Palette and run MCP: Add Server, or create .vscode/mcp.json in your workspace (or your user mcp.json to make it available everywhere):

{
  "servers": {
    "edithly": {
      "type": "http",
      "url": "https://api.edithly.com/api/v1/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

VS Code will pick up the server for Copilot Chat / agent mode. Use MCP: List Servers from the Command Palette to start, stop, or restart it.

Connect in Codex CLI

Edit ~/.codex/config.toml (or your project's .codex/config.toml) and add an entry under mcp_servers:

[mcp_servers.edithly]
url = "https://api.edithly.com/api/v1/mcp/sse"
bearer_token_env_var = "EDITHLY_API_KEY"

Export your key as an environment variable before launching Codex so it can fill in the Authorization header:

export EDITHLY_API_KEY="YOUR_API_KEY"

Other MCP clients

Any MCP client that supports remote servers over streamable HTTP / SSE with custom headers can connect to Edithly — point it at:

URL: https://api.edithly.com/api/v1/mcp/sse
Header: Authorization: Bearer YOUR_API_KEY

Most clients (Windsurf, Zed, and others) use the same mcpServers JSON shape shown for Cursor and Claude Desktop above — drop in the same block under the client's MCP settings.

All tools

Every tool the Edithly MCP server exposes, grouped by what it's for.

Discovery — figure out what to build

Tool	What it does	Credits	Auth
`get_visual_types`	List all Edithly visual types with descriptions and use cases	Free	No
`get_visual_schema`	Get the exact `design_json` schema and a working example for a visual type	Free	No
`list_templates`	List Edithly layout templates / recipes, optionally filtered by visual type	Free	No

Generate — create a new visual

Tool	What it does	Credits	Auth
`create_visual`	Render a visual (PDF/PNG) from a `design_json` PageSpec	1	Yes
`create_image`	Generate an AI poster image (WebP) from raw content	4	Yes
`create_solvesheet`	Turn a problem or worksheet into a worked-example solvesheet	1	Yes

Manage — edit, export, and inspect existing visuals

Tool	What it does	Credits	Auth
`update_visual`	Modify an existing visual with instructions and/or a `design_patch`, then re-render	1	Yes
`export_visual`	Re-export an existing visual as PDF or PNG from its stored `design_json`	1	Yes
`get_visual`	Retrieve metadata and URLs for a previously created visual	Free	Yes
`get_generation_status`	Check the status of a `visual_id` (MCP renders synchronously, so this returns `completed` immediately)	Free	Yes

Account — credits and projects

Tool	What it does	Credits	Auth
`get_credit_balance`	Get your current visual credit balance	Free	Yes
`list_projects`	List your Edithly projects (API chatboxes)	Free	Yes

Tool reference

Full parameters for every tool. api_key is optional on every call if you're already sending an Authorization: Bearer header in your MCP client config — pass it explicitly only when calling a tool outside that context.

`get_visual_types`

List all Edithly visual types with descriptions and use cases. Always call this first before get_visual_schema or create_visual to identify the correct visual_type for the request.

No parameters.

`get_visual_schema`

Get the exact design_json schema and a complete working example for a specific visual_type. Call get_visual_types() first to pick the right type, then call this with that type. The returned example shows exactly what to put in design_json for create_visual().

Parameter	Type	Required	Description
`visual_type`	string	No	The visual type to fetch a schema for (from `get_visual_types`)

`list_templates`

List Edithly layout templates / recipes. Optionally filter by visual_type. No authentication required.

Parameter	Type	Required	Description
`visual_type`	string	No	Filter templates to a single visual type

`create_visual`

Render a visual from a PageSpec design_json. Uploads to S3 and creates a shareable view_url. Only writes a local file when save_path is explicitly provided. Costs 1 credit.

Parameter	Type	Required	Description
`design_json`	object	Yes	The PageSpec design — call `get_visual_schema()` first to learn the correct format
`output_format`	string	No	Output file format. Default `pdf`
`page_size`	string	No	Page size. Default `A4`
`save_path`	string	No	Local path to write the file to; the file is only written locally when this is set
`api_key`	string	No	Overrides the `Authorization` header for this call

Returns view_url and visual_id — never invent filenames or IDs.

`create_image`

Generate an AI poster image from raw content. Use this — not create_visual — whenever the request is for an image, poster, or visual cheatsheet. Costs 4 credits.

Parameter	Type	Required	Description
`page_title`	string	Yes	Title shown on the generated image
`content`	string	Yes	All extracted facts, data, and concepts to include — the more detail, the better the result
`save_path`	string	No	Local path to write the `.webp` to; only written locally when this is set
`api_key`	string	No	Overrides the `Authorization` header for this call

Returns view_url and visual_id.

`create_solvesheet`

Turn a problem, worksheet, or document's text into a worked-example solvesheet. The backend solves the question — the model should not invent steps or fall back to create_visual. Costs 1 credit.

Parameter	Type	Required	Description
`content`	string	Yes	The full source text
`question`	string	No	Set when the source document has more than one problem, to target a specific one
`page_title`	string	No	Title for the sheet
`sheet_theme`	string	No	Visual theme for the sheet
`save_path`	string	No	Local path to write the file to
`api_key`	string	No	Overrides the `Authorization` header for this call

Returns view_url and visual_id.

`update_visual`

Modify an existing visual. Pass instructions and/or a design_patch, and Edithly re-renders it. Costs 1 credit.

Parameter	Type	Required	Description
`visual_id`	string	Yes	The visual to update
`instructions`	string	No	Natural-language description of the change
`design_patch`	object \| null	No	A partial `design_json` patch to merge in
`output_format`	string	No	Override the output format for the re-render
`page_size`	string	No	Override the page size for the re-render
`save_path`	string	No	Local path to write the updated file to
`api_key`	string	No	Overrides the `Authorization` header for this call

Returns view_url and visual_id (local_path only if save_path was set).

`export_visual`

Re-export an existing MCP visual as PDF or PNG from its stored design_json, without changing its content. Costs 1 credit.

Parameter	Type	Required	Description
`visual_id`	string	Yes	The visual to export
`output_format`	string	No	Output format. Default `pdf`
`page_size`	string	No	Page size override
`save_path`	string	No	Local path to write the file to
`api_key`	string	No	Auth required for this call

`get_visual`

Retrieve metadata and URLs for a previously created MCP visual.

Parameter	Type	Required	Description
`visual_id`	string	Yes	The visual to look up
`api_key`	string	No	Auth required for this call

`get_generation_status`

Compatibility status check for a visual_id. MCP renders synchronously, so a completed visual returns status: completed immediately — this exists mainly for clients built against an async generation model.

Parameter	Type	Required	Description
`visual_id`	string	Yes	The visual to check
`api_key`	string	No	Auth required for this call

`get_credit_balance`

Get your current visual credit balance. create_visual and create_solvesheet cost 1 credit; create_image costs 4 credits.

Parameter	Type	Required	Description
`api_key`	string	No	Auth required for this call

`list_projects`

List the authenticated user's Edithly projects (API chatboxes).

Parameter	Type	Required	Description
`api_key`	string	No	Auth required for this call

Typical workflows

Generate a visual (PDF/PNG):

get_visual_types — pick the right format
get_visual_schema — get the layout template
create_visual — render and save the file

Generate a poster / image: call create_image directly instead of create_visual.

Generate a solvesheet: call create_solvesheet with the source text — don't build a design_json by hand for this.

Browse recipes first: call list_templates (optionally filtered by visual_type) to see ready-made layouts before writing a design_json from scratch.

Edit something you already made: call update_visual with instructions describing the change, or a design_patch.

Check on a visual later: get_visual for metadata and URLs, or get_generation_status for a status check.

Ask in natural language — the AI will call the right tools for you.

Examples

1. Python cheatsheet (PDF)

Create a Python cheatsheet PDF and save it to ~/Downloads/python-cheatsheet.pdf

The assistant picks cheatcode, builds the content, and returns a local file path plus a shareable view_url.

2. Mind map

Make a mind map about machine learning basics and save as ~/Downloads/ml-mindmap.pdf

Uses the mindmap visual type.

3. Flashcard quiz

Create 10 MCQ flashcards on FastAPI and save to ~/Downloads/fastapi-quiz.pdf

Uses the flashcard visual type.

4. AI poster image

Generate a poster image about climate change facts and save to ~/Downloads/climate-poster.webp

Uses create_image (4 credits). Include plenty of facts in your request for a better result.

5. Worked-example solvesheet

Solve this physics problem step by step and save the solvesheet to ~/Downloads/physics-solvesheet.pdf

Uses create_solvesheet — paste the full problem text as content.

6. Revise an existing visual

Make the headings bigger on that mind map you just created

Uses update_visual with instructions, reusing the visual_id from the previous response.

7. Check credits

How many visual credits do I have left?

Calls get_credit_balance.

Tips

Always give a save path — e.g. ~/Downloads/my-visual.pdf so the file lands where you expect.
Posters = create_image — not create_visual.
Worksheets = create_solvesheet — let the backend solve it instead of hand-building a design_json.
More content = better output — paste notes or bullet points when you can.
Check list_templates before designing from scratch — a ready-made recipe is often a better start than a blank design_json.
Auth — Prefer the Authorization header in MCP config; you can also pass api_key on individual tool calls.

Troubleshooting

Problem	What to try
MCP server not showing	Restart the client; confirm the URL ends with `/api/v1/mcp/sse`
Auth errors	Regenerate API key; check `Bearer` prefix in the header
Insufficient credits	Top up credits in Edithly settings
Server unavailable	Visit `https://api.edithly.com/health/mcp` — should return `status: ok`

Still stuck? Mail [email protected], open Contact support, or ask in Join our Discord.

Quick reference

Endpoint	Purpose
`GET /api/v1/mcp/sse`	MCP connection (SSE)
`POST /api/v1/mcp/messages`	MCP messages (handled by client)
`GET /health/mcp`	Check if MCP is running

Full tool list

get_visual_types · get_visual_schema · list_templates · create_visual · create_image · create_solvesheet · update_visual · export_visual · get_visual · get_generation_status · get_credit_balance · list_projects

Before you connect​

Create an API key​

Connect in Cursor​

Connect in Claude Desktop​

Connect in VS Code​

Connect in Codex CLI​

Other MCP clients​

All tools​

Discovery — figure out what to build​

Generate — create a new visual​

Manage — edit, export, and inspect existing visuals​

Account — credits and projects​

Tool reference​

get_visual_types​

get_visual_schema​

list_templates​

create_visual​

create_image​

create_solvesheet​

update_visual​

export_visual​

get_visual​

get_generation_status​

get_credit_balance​

list_projects​

Typical workflows​

Examples​

1. Python cheatsheet (PDF)​

2. Mind map​

3. Flashcard quiz​

4. AI poster image​

5. Worked-example solvesheet​

6. Revise an existing visual​

7. Check credits​

Tips​

Troubleshooting​

Quick reference​