ASCII MagicDocs

MCP server

One URL, no API key, no SDK. Your agent renders images through the same engine the editor uses.

The endpointurl
https://www.ascii-magic.com/mcp

The server supports OAuth with dynamic client registration, so your client registers itself and asks you to sign in. You sign in with the same ASCII Magic account you use on the site.

Who can use it

Anyone with an account. Pro is not required to connect.

  • Free accounts get the 15 free styles, every dither palette and algorithm, and recipe encoding and decoding.
  • Pro accounts get all 91 styles and all 28 post effects.

Your plan is read on every call, so upgrading takes effect immediately with no reconnection. Asking for a Pro style on a free account returns a clear lock message rather than quietly rendering something else.

Claude Code

bash
claude mcp add --transport http ascii-magic https://www.ascii-magic.com/mcp

Then run claude, type /mcp inside it, select ascii-magic and choose Authenticate.

Note

The server is registered to the folder you ran the add command in, so start Claude Code from that same folder or it will not appear.

Claude Desktop and claude.ai

Settings, then Connectors, then Add custom connector. Paste the URL and sign in when prompted. The connector shows up in both the desktop app and the web app.

Cursor

Settings, then MCP, then Add new MCP server. Or edit ~/.cursor/mcp.json:

~/.cursor/mcp.jsonjson
{
  "mcpServers": {
    "ascii-magic": {
      "url": "https://www.ascii-magic.com/mcp"
    }
  }
}

Restart Cursor and approve the sign-in prompt.

Everything else

Any client that speaks streamable HTTP and OAuth works the same way: give it the URL. That includes VS Code, Windsurf and Zed.

Two things to know before you start

Pass an image URL, not a file path. The server runs in the cloud and cannot see your disk, so ~/Desktop/photo.jpg will never work. For a local file the agent uses create_upload and sends the bytes over your shell, which means local files work in Claude Code and not in Claude Desktop, claude.ai or Cursor. Those clients have no shell to run the upload with. That is a limit of the protocol, not something missing here.

The first call after a quiet spell is slow. The renderer sleeps when nobody is using it, so the first request can take around 20 seconds while it wakes. Everything after that is quick.

How the sign-in works

There is no API key to create, copy or rotate, because there is no API key. The server speaks OAuth with dynamic client registration, which means a client that has never seen ASCII Magic before can register itself from the URL alone and then send you to sign in.

your clientthe serveryou, in a browserPOST /oauth/registerclient id, no key to copyopen this to sign insigned in, token stored by the client
Nothing in this exchange is a secret you hold. The client registers itself, you approve the sign-in in a browser, and the token lives in the client's own storage.

Setting it up, per client

Every client only needs the one URL. These are the exact incantations.

Claude Code

Add it oncebash
claude mcp add --transport http ascii-magic https://www.ascii-magic.com/mcp

Then start claude, type /mcp at the prompt, pick ASCII Magic from the list and choose to authenticate. A browser opens, you sign in, and the session is connected. The /mcp step happens inside Claude Code, not in your shell.

Claude Desktop

Settings, then Connectors, then add a custom connector with the same URL. It registers itself and prompts you to sign in.

Cursor

Add an HTTP MCP server pointing at the same URL in the MCP settings. Cursor performs the same registration and sign-in.

Anything else

If it speaks MCP over HTTP and supports OAuth, the URL is all it needs. There is no separate configuration document, no key to paste and no per-client variant of the endpoint.

Checking it worked

Ask the agent what ASCII Magic account it is signed in as. That runs account_status, which is the cheapest possible round trip and tells you both that the connection is live and which tier you will get.

When something is wrong

SymptomWhat it usually is
The client never prompts you to sign inIt registered but has not been asked to do anything yet. Ask for a render and the sign-in prompt follows.
A style renders as something elseIt should not. Locked Pro styles error rather than substituting. If you are getting a different look, you probably omitted style and the server chose one.
Everything is the free tier on a Pro accountThe agent passed a free style with style_requested_by_user. Check account_status first.
A local file will not attachThe known upload gate bug. Pass a public URL instead. See the tools reference.
A solid background renders blackA known gap on the current build: solid backgrounds render black whatever colour is asked for. A fix is staged.

What it costs

Nothing per call. The MCP server drives the same local-style engine, so ordinary renders are free at any volume on either tier. The only metered path is a generative render, which costs credits exactly as it does in the editor.

Last updated