Edithly MCP — User guide

Connect Edithly to Claude (claude.ai, Claude Desktop, and Claude Code), Cursor, VS Code, Codex CLI, or any MCP client to create cheatsheets, mind maps, flashcards, posters, 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

An Edithly account — In Claude you sign in with it directly, so you don't need an API key. Other clients use an API key.
Credits — 1 credit per visual or solvesheet, 4 per AI poster image, and 5 per sales visual made from a playbook.

Check your balance anytime with get_credit_balance.

Server URL: https://api.edithly.com/api/v1/mcp

Every request must be signed in. Without a valid sign-in or API key, the server answers 401 Unauthorized.

Connect in Claude (claude.ai and Claude Desktop)

Add Edithly as a custom connector. You sign in with your Edithly account, so there's no API key to copy.

On claude.ai, open Settings → Connectors and click Add custom connector.
Enter Edithly as the name and https://api.edithly.com/api/v1/mcp as the URL, then click Add.
Click Connect next to Edithly. The Edithly sign-in page opens. Sign in and approve access.
Start a chat, make sure Edithly is turned on in the tools menu under the message box, and ask for a visual.

A connector you add on claude.ai also works in Claude Desktop and the Claude mobile apps.

On Team and Enterprise plans, an owner adds the connector for the organization first. Each member then clicks Connect and signs in with their own Edithly account.

Connect in Claude Code

With the plugin: install the Edithly plugin from the Claude Code plugin marketplace (run /plugin and search for Edithly). It sets up the MCP server and adds skills for each visual type.

Or add the server yourself:

claude mcp add --transport http edithly https://api.edithly.com/api/v1/mcp

Either way, run /mcp in Claude Code, select edithly, and choose Authenticate to sign in in your browser.

To use an API key instead of signing in (for example in CI), pass it as a header:

claude mcp add --transport http edithly https://api.edithly.com/api/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Create an API key

Cursor, VS Code, Codex CLI, and most other clients authenticate with 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 Authorization header in the configs below.

Connect in Cursor

Open Cursor Settings → MCP and add:

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

Replace YOUR_API_KEY with your key.

Restart Cursor or reload MCP servers.

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",
      "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"
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 can connect to Edithly:

URL: https://api.edithly.com/api/v1/mcp (Streamable HTTP)
SSE-only clients: https://api.edithly.com/api/v1/mcp/sse
Auth: Authorization: Bearer YOUR_API_KEY, or OAuth sign-in if your client supports it. Clients find the sign-in details at https://api.edithly.com/.well-known/oauth-protected-resource.

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

Connected before October 2026?

The SSE URL (/api/v1/mcp/sse) still works, so existing setups keep running. Two things changed:

Tools no longer take an api_key argument. Send your key in the Authorization header instead.
Every tool needs sign-in, including get_visual_types, get_visual_schema, and list_templates.

What Edithly can access

When you sign in from Claude or another OAuth client, you approve these permissions:

Permission	Lets the client
`visuals:read`	Read your visuals, visual types, and templates
`visuals:write`	Create and update visuals
`projects:read`	List your Edithly projects
`exports:create`	Export visuals as PDF or PNG

To disconnect, open Settings → Connectors in Claude and disconnect Edithly. To revoke an API key, delete it in the API Portal tab. See Data and storage and the privacy policy for how Edithly handles your content.

All tools

Every tool the Edithly MCP server exposes, grouped by what it's for. Claude shows each tool by its title. Every tool needs sign-in.

Discovery — figure out what to build

Tool	Title	What it does	Credits
`get_visual_types`	List visual types	List all Edithly visual types with descriptions and use cases	Free
`get_visual_schema`	Get visual type guidance	Get guidance and an example for a visual type	Free
`list_templates`	List layout templates	List Edithly layout templates / recipes, optionally filtered by visual type	Free

Generate — create a new visual

Tool	Title	What it does	Credits
`create_visual`	Create visual	Generate a visual from a topic or source text	1 (5 for sales playbook visuals)
`create_image`	Create AI poster image	Generate an AI poster image (WebP) from raw content	4
`create_solvesheet`	Create solvesheet	Turn a problem or worksheet into a worked-example solvesheet	1

Manage — edit, export, and inspect existing visuals

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

Account — credits and projects

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

Tool reference

Full parameters for every tool. Authentication comes from your connection (Claude sign-in or the Authorization header), so no tool takes an api_key argument.

About save_path

Several tools accept save_path. It writes the file on the machine running the MCP server. With the hosted server (everything on this page), that is Edithly's server, not your computer, so leave it empty and use the returned view_url or download_url.

`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 guidance and an illustrative example for a visual_type. Call get_visual_types() first to pick the right type. The example is for reference only: create_visual takes your content and the type, and Edithly designs the layout.

For image and solvesheet, it points to create_image and create_solvesheet instead.

Parameter	Type	Required	Description
`visual_type`	string	No	The visual type to get guidance for (from `get_visual_types`). Empty returns general guidance

`list_templates`

List Edithly layout templates / recipes. Optionally filter by visual_type.

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

`create_visual`

Generate a visual with the same pipeline as visuals made in the Edithly app: Edithly analyzes the content, designs the layout, and publishes a shareable view_url. Pass the content and the type. Don't build the design by hand. Costs 1 credit, or 5 credits for a sales visual made from a playbook.

Use create_image for posters and images, and create_solvesheet for worked examples.

Parameter	Type	Required	Description
`content`	string	Yes	The topic or source text for the visual
`visual_type`	string	Yes	A type from `get_visual_types`, e.g. `cheatcode`, `mindmap`, `flashcard`, `one_pager`
`page_title`	string	No	Title hint
`color_theme`	string	No	`ocean_deep`, `midnight_noir`, `sunset_glow`, `forest_sage`, `rose_quartz`, `golden_hour`, `arctic_aurora`, `volcanic_ember`, or `cosmic_purple`
`sheet_theme`	string	No	Sheet look for types that support it: `studio`, `notebook`, `chalk`, `sticky`, `legal`, `graph`, `sketchnote`
`save_path`	string	No	Leave empty with the hosted server (why)
`playbook_slug`	string	No	One of your sales playbooks. With the four prospect fields below, builds a sales visual for that prospect (5 credits)
`prospect_company_name`	string	With `playbook_slug`	Prospect's company
`prospect_website_url`	string	With `playbook_slug`	Prospect's website
`prospect_contact_name`	string	With `playbook_slug`	Contact's name
`prospect_location`	string	With `playbook_slug`	Prospect's location
`prospect_linkedin_url`	string	No	Contact's LinkedIn URL
`prospect_contact_role`	string	No	Contact's role
`custom_notes`	string	No	Extra notes for the sales visual

Returns view_url and visual_id, plus download_url when a file is available — 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	Leave empty with the hosted server (why)

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	`studio`, `notebook`, `chalk`, `sticky`, `legal`, `graph`, or `sketchnote`
`save_path`	string	No	Leave empty with the hosted server (why)

Returns view_url and visual_id.

`update_visual`

Modify an existing visual. Pass instructions and/or a design_patch, and Edithly re-renders it. Doesn't work on AI poster images; make a new one with create_image. 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 to merge in
`output_format`	string	No	`pdf` or `png` for the re-render
`page_size`	string	No	Override the page size for the re-render
`save_path`	string	No	Leave empty with the hosted server (why)

Returns view_url, download_url, and visual_id.

`export_visual`

Re-export an existing visual as PDF or PNG without changing its content. Doesn't work on AI poster images. Costs 1 credit.

Parameter	Type	Required	Description
`visual_id`	string	Yes	The visual to export
`output_format`	string	No	`pdf` (default) or `png`
`page_size`	string	No	Page size override
`save_path`	string	No	Leave empty with the hosted server (why)

Returns download_url, view_url, and the new visual_id.

`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

`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. Unknown IDs return status: not_found.

Parameter	Type	Required	Description
`visual_id`	string	Yes	The visual to check

`get_credit_balance`

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

No parameters.

`list_projects`

List your Edithly projects (API chatboxes).

No parameters.

Typical workflows

Generate a visual:

get_visual_types — pick the right format
get_visual_schema — optional, see what that type looks like
create_visual — pass your content and the type, get back a view_url

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

Generate a solvesheet: call create_solvesheet with the source text.

Browse recipes first: call list_templates (optionally filtered by visual_type) to see ready-made layouts.

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

Get a PDF or PNG: call export_visual with the visual_id, then open the download_url.

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

Create a Python cheatsheet covering lists, dicts, and comprehensions

The assistant picks cheatcode, calls create_visual, and returns a shareable view_url.

2. Mind map

Make a mind map about machine learning basics

Uses the mindmap visual type.

3. Flashcard quiz

Create 10 MCQ flashcards on FastAPI

Uses the flashcard visual type.

4. AI poster image

Generate a poster image about climate change facts

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 as a solvesheet: (paste the problem)

Uses create_solvesheet — the full problem text goes in 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. Download as PDF

Export that mind map as a PDF

Uses export_visual and returns a download_url.

8. Check credits

How many visual credits do I have left?

Calls get_credit_balance.

Tips

Open the link — every result includes a view_url. Ask for a PDF or PNG export when you need a file.
Posters = create_image — not create_visual.
Worksheets = create_solvesheet — let the backend solve it.
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.
Auth — Claude signs in with your Edithly account. Other clients send Authorization: Bearer YOUR_API_KEY. Tools don't take an api_key argument.

Troubleshooting

Problem	What to try
Claude says Edithly isn't connected	Open Settings → Connectors, click Connect next to Edithly, and sign in
`401 Unauthorized` / `invalid_token`	In Claude, disconnect and reconnect Edithly. With an API key, check the header reads `Authorization: Bearer YOUR_API_KEY`, or create a new key
Tool calls fail after passing `api_key`	Tools no longer take an `api_key` argument — put the key in the `Authorization` header
MCP server not showing	Restart the client; confirm the URL is `https://api.edithly.com/api/v1/mcp` (or `/api/v1/mcp/sse` for SSE-only clients)
File didn't appear on your computer	The hosted server can't write to your machine — open the `view_url`, or export and open the `download_url`
Insufficient credits	Top up credits in Edithly settings
Server unavailable	Visit `https://api.edithly.com/health/mcp` — should return `status: healthy`

Still stuck? Mail tech@edithly.com, open Contact support, or ask in Join our Discord.

Quick reference

Endpoint	Purpose
`POST /api/v1/mcp`	MCP connection (Streamable HTTP) — use this one
`GET /api/v1/mcp/sse`	MCP connection (SSE, for older clients)
`POST /api/v1/mcp/messages`	MCP messages for SSE (handled by client)
`GET /.well-known/oauth-protected-resource`	Sign-in details for OAuth clients like Claude
`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​

Connect in Claude (claude.ai and Claude Desktop)​

Connect in Claude Code​

Create an API key​

Connect in Cursor​

Connect in VS Code​

Connect in Codex CLI​

Other MCP clients​

What Edithly can access​

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​

2. Mind map​

3. Flashcard quiz​

4. AI poster image​

5. Worked-example solvesheet​

6. Revise an existing visual​

7. Download as PDF​

8. Check credits​

Tips​

Troubleshooting​

Quick reference​

Before you connect

Connect in Claude (claude.ai and Claude Desktop)

Connect in Claude Code

Create an API key

Connect in Cursor

Connect in VS Code

Connect in Codex CLI

Other MCP clients

What Edithly can access

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

2. Mind map

3. Flashcard quiz

4. AI poster image

5. Worked-example solvesheet

6. Revise an existing visual

7. Download as PDF

8. Check credits

Tips

Troubleshooting

Quick reference