# MCP server

Source: https://www.ascii-magic.com/docs/mcp (ASCII Magic documentation)

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

`The endpoint`
```url
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.json`
```json
{
  "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.

_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 once`
```bash
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

| Symptom | What it usually is |
|---|---|
| The client never prompts you to sign in | It 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 else | It 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 account | The agent passed a free style with `style_requested_by_user`. Check `account_status` first. |
| A local file will not attach | The known upload gate bug. Pass a public URL instead. See [the tools reference](https://www.ascii-magic.com/docs/mcp-tools). |
| A solid background renders black | A 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.