DEV Community: Jill Mercer

i added MCP support to my SaaS in an afternoon. here's the whole thing.

Jill Mercer — Mon, 25 May 2026 03:40:23 +0000

I built Imagcon because I kept needing it. PWA icon generator — describe what you want, get all 19 sizes back plus splash screens and a manifest.json. every app I ship needs a fresh icon set and I got tired of doing it manually.
a few weeks ago I'm in the terminal with Claude Code working on something, I need icons, and I'm about to open a browser tab to do it. which means: describe the icon, wait for it to render, download the ZIP, drag the files into the project. while I'm already in a session where I could just say what I want.
so I asked Claude: is there a way to make this callable from inside the terminal, without leaving the editor?
MCP came back as the answer. I said let's build it. we went back and forth for an afternoon, hit one URL gotcha that cost me a solid hour, and by the end it was packaged and installable with one command. this is that whole afternoon.

what MCP is
Claude explained it to me as: you expose a set of functions, give them names and descriptions, and the AI can call them the same way it calls any built-in tool. the user never has to leave their editor.
before: "generate icons for my app" → switch tabs, describe, wait, download ZIP, drag files in.
after:
generate_pwa_icons("minimal blue compass on dark gradient", "./public/icons")

Claude Code runs that, extracts the ZIP, the icons land in your project. you keep typing.
(I've also been sitting on something that fits alongside this — a way to tell agents how to actually navigate your app, not just call the API. got deep into that before I even knew MCP existed. different post.)

the structure
three files. Claude laid this out before writing anything:
imagcon_mcp/
client.py # httpx wrapper around the Imagcon REST API
server.py # FastMCP tool definitions
main.py # entry point, auth, argparse

here's what's in each one.

the client
nothing clever — each method maps to one API call:
import io
import zipfile
from pathlib import Path
import httpx

BASE_URL = "https://imagcon.app"

class ImagconClient:
def init(self, api_key: str, timeout: float = 300.0) -> None:
self._client = httpx.Client(
base_url=BASE_URL,
headers={"Authorization": f"Bearer {api_key}"},
timeout=timeout,
)

def generate_image(self, description: str) -> dict:
    r = self._client.post(
        "/routes/generate-image",
        json={"description": description, "aspect_ratio": "1:1", "number_of_images": 1},
    )
    r.raise_for_status()
    return r.json()

def generate_pwa_icons(self, image_key: str) -> dict:
    r = self._client.post("/routes/generate-pwa-icons", json={"image_key": image_key})
    r.raise_for_status()
    return r.json()

@staticmethod
def extract_zip_to_dir(zip_bytes: bytes, output_dir: Path) -> None:
    output_dir.mkdir(parents=True, exist_ok=True)
    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
        zf.extractall(output_dir)

the 300-second timeout — I found out why that matters the first time a request died mid-generation. image generation takes real compute time and the default httpx timeout cuts it off before it finishes. Claude bumped it after that happened.
the auth error handling was Claude thinking ahead:
def _request_error_message(self, response: httpx.Response) -> str:
if response.status_code in (401, 403):
return (
f"Imagcon API returned {response.status_code}. "
f"Check your API key at https://imagcon.app/api-keys"
)
return f"Imagcon API error {response.status_code}: {response.text[:500]}"

without something like this, a bad API key just returns a 401 with no useful message and you spend twenty minutes convinced it's a network problem.

the server
FastMCP makes this almost too simple. you decorate a function and it becomes a callable tool:
from mcp.server.fastmcp import FastMCP
from imagcon_mcp.client import ImagconClient

mcp = FastMCP("imagcon")
_client: ImagconClient | None = None

def set_client(client: ImagconClient) -> None:
global _client
_client = client

def _require_client() -> ImagconClient:
if _client is None:
raise RuntimeError("Imagcon client is not configured.")
return _client

I asked why the client was a global instead of passed around. Claude explained: the MCP server runs as a long-lived process, not a request handler — you wire up auth once at boot and reuse it across every tool call. hadn't thought about that. makes sense once you see it.
the main tool — the one that does the full pipeline:
@mcp.tool()
def generate_pwa_icons(description: str, output_dir: str = "./public/icons") -> str:
client = _require_client()
out = Path(output_dir)

# Step 1: generate the base image
gen = client.generate_image(description)
image_key = gen["image_key"]

# Step 2: resize to all 19 PWA sizes
pwa = client.generate_pwa_icons(image_key)
raw_icons = pwa["icons"]

# Step 3: save to gallery so it can be re-downloaded
save = client.save_pwa_icon_set(
    set_name=description[:99],
    original_image_key=image_key,
    icons=[{"size": ic["size"], "image_key": ic["image_key"]} for ic in raw_icons],
    prompt=description,
)

# Step 4: download the ZIP and extract
zip_bytes = client.download_pwa_icon_set_zip(save["set_id"])
ImagconClient.extract_zip_to_dir(zip_bytes, out)

return f"Generated {len(raw_icons)} icons in {out.resolve()}. manifest.json included."

four API calls under the hood, but from the AI's perspective it's one tool with two parameters. it doesn't need to know about image keys or set IDs — those are just plumbing. the user says what they want, the tool handles everything.
the smaller tools follow the same pattern:
@mcp.tool()
def get_credit_balance() -> str:
data = _require_client().get_credit_balance()
return f"You have {data['remaining_credits']} credits remaining."

@mcp.tool()
def list_saved_icon_sets() -> str:
data = _require_client().list_pwa_icon_sets()
sets = data.get("icon_sets", [])
if not sets:
return "No saved icon sets found."
return "\n".join(
f"{s['id']}: {s['set_name']} (created {s['created_at'][:10]})"
for s in sets
)

return strings, not JSON. the AI reads the return value and decides what to say to the user — plain text relays directly. JSON makes the AI summarize the JSON, which adds noise.

the entry point
I didn't know how auth was typically handled for something like this. Claude set up two patterns — environment variable and CLI flag:
import argparse, os, sys
from imagcon_mcp.client import ImagconClient
from imagcon_mcp.server import mcp, set_client

def resolve_api_key(cli_key: str | None) -> str:
key = (cli_key or os.environ.get("IMAGCON_API_KEY") or "").strip()
if not key:
print(
"Missing Imagcon API key. Set IMAGCON_API_KEY or pass --api-key.\n"
"Create a key at https://imagcon.app/api-keys",
file=sys.stderr,
)
raise SystemExit(2)
if not key.startswith("ic_live"):
print("Invalid API key format. Keys start with ic_live_.", file=sys.stderr)
raise SystemExit(2)
return key

def main() -> None:
parser = argparse.ArgumentParser(prog="imagcon-mcp")
parser.add_argument("--api-key", default=None)
args, remaining = parser.parse_known_args()
sys.argv = [sys.argv[0], *remaining] # pass remaining args to FastMCP

api_key = _resolve_api_key(args.api_key)
client = ImagconClient(api_key)
set_client(client)
try:
    mcp.run()
finally:
    client.close()

the parse_known_args trick — I wouldn't have known to do that. it lets you add your own flags without conflicting with whatever FastMCP wants to pass through. the finally: client.close() cleans up the connection pool on shutdown; skip it and you'll see warnings.

packaging
[project]
name = "imagcon-mcp"
version = "0.1.3"
requires-python = ">=3.11"
dependencies = [
"mcp>=1.0.0",
"httpx>=0.27.0",
]

[project.scripts]
imagcon-mcp = "imagcon_mcp.main:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

the [project.scripts] entry is what makes uvx imagcon-mcp work. uvx creates an isolated environment, installs the package, runs the script. no pip install step, no virtualenv the user has to manage.

the gotcha that cost me an hour
my backend routes are auto-discovered from Python modules and mounted at a prefix. so image_generator/generate_image should be at /routes/image_generator/generate_image.
in production it's not. the actual paths are flat: /routes/generate-image. the prefixes only exist in the router config, not in the deployed URLs.
I spent an hour calling paths that 404'd because I assumed the URL structure matched the file structure. Claude was working from the same wrong assumption I'd given it — so it didn't catch it either. we were both confidently wrong.
open your browser's network tab before you write a single line of client code. look at the actual request URLs your app makes. don't trust your mental model, and don't assume the AI's is any better than yours.

what I'd do differently
first version had four separate tools — one per API step. generate_image, generate_pwa_icons, save_set, download_set. the AI used them correctly but every conversation filled up with intermediate steps the user didn't care about. nobody needs to see the image key. collapsing everything into one generate_pwa_icons call made it dramatically cleaner. if nobody would ever want to stop in the middle of your pipeline, it should be one tool.
the docstrings matter more than I expected. I left them vague at first and the AI kept asking clarifying questions that weren't necessary. the function docstring is how the AI decides whether to use a tool and when — vague means it guesses.
the JSON return thing I found out by watching the AI respond. it would get a JSON blob back and then narrate the JSON to the user. switching to plain text fixed it immediately.

if you vibe code your apps you probably already have some service you built that you're constantly switching tabs to use. this pattern works for any of them.
full source is in the Imagcon repo. keys at imagcon.app/api-keys — I use it on every app I ship.

my apps were invisible to AI agents — here's what I am doing about it

Jill Mercer — Mon, 18 May 2026 01:22:32 +0000

your app has a readme for humans. it has nothing for ai agents.

this isn't a future problem. ai agents are already how people discover and use tools. when someone asks claude or chatgpt to "find an invoicing app" or "help me send a quote," the ai either knows what your app can do or it doesn't. if it doesn't, you're invisible — not because your app is bad, but because you never told the agent how to read it.
when an ai assistant tries to use your app — recommend it, navigate it, automate a task inside it — it guesses. it looks at your landing page, reads whatever text it can find, and tries to figure out what your app does and how to use it. sometimes it gets close. often it hallucinates the wrong tool, clicks the wrong thing, or just fails silently and moves on.

so i built blueprint protocol. a blueprint.txt file at the root of your app that tells agents exactly what it can do, which tools to call, what's human-only, and how to complete each flow step by step. no mcp required. it works for any agent trying to navigate any web app.

then i ran a benchmark and found out it also cuts mcp discovery overhead by 78%.

what it does for mcp specifically
mcp has two calls. tools/list returns every tool the server exposes. tools/call calls a specific tool by name.

without a blueprint, an agent calls tools/list first, reads through all N tool definitions, picks one, then calls it.

with a blueprint, the agent already knows the tool name and exact parameters. it calls tools/call directly. tools/list never happens.

that's not just cheaper discovery. it's the removal of an entire round trip.

the benchmark
i ran a controlled test across four models — claude, gpt-4o, gemini, and grok — five candidate mcp servers, one correct match. agents were told to find the best server efficiently. no blueprint references in the harness instructions. discovery was organic.

model without blueprint with blueprint reduction
claude 58 pts 13 pts ~78%
gpt-4o 58 pts 28 pts ~54%
gemini 23 pts 9 pts ~61%
grok 58 pts 58 pts 0%
overhead scored by weighted resource inspection cost — llms.txt at 10pts, blueprint.txt at 1pt, reflecting typical real-world document sizes.

grok's 0% is an honest result. not all models follow discovery signals today. that's expected — robots.txt and llms.txt didn't work everywhere on day one either.

v3.0.0 — agent-first structure
the spec just hit v3.0.0. two changes that matter for mcp:

[MCP] flag on line one — agents confirm server availability instantly
format b capabilities index — root file is ~150 tokens, agents fetch only the one capability file they need (~350 tokens). total: ~500 tokens vs thousands from tools/list
try it
spec: https://github.com/Explorer-64/blueprint-protocol

live reference implementation: https://imagcon.app/blueprint.txt

benchmark results: https://stackapps.app/mcp-blueprint-results

open standard. mit licensed. no tooling required. works with or without mcp. if you have a web app or an mcp server, a blueprint takes about 10 minutes.

I shipped 30 apps. AI crawlers ignore them.

Jill Mercer — Sun, 10 May 2026 16:43:48 +0000

I have shipped over 30 apps. Most of them are absolute ghosts right now.

If you ask an AI tool to find something that does exactly what my projects do, they won't show up. It is not because the apps are bad. It is because I built them before AI crawlers mattered.

I learned the hard way that the ground moves fast in this industry. I am self-taught — learned by shipping, not by studying. A while back, I started vibe coding with Bolt. Then I found Databutton. I loved it — the community was real, and it is where I actually learned how to vibe code. Then they pivoted to B2B overnight. They shut down the Discord. Pricing shot up. The little guy got pushed out.

I was weeks away from monetizing. Instead, I had to pack up and leave. I jumped to Replit, tried Firebase Studio, messed with Google AI Studio, and finally landed on Cursor. Moving those apps one by one took forever. Six months just evaporated. That whole mess taught me a hard lesson: own your stack. Own your presentation layer. Never let a platform sit between you and your users.

So now I do. I build everything in Cursor. I own the code.

But owning the stack does not solve the discovery problem. People are searching differently now. They ask Perplexity, ChatGPT, or Claude for tool recommendations instead of scrolling Google. And those AI bots do not read websites the way humans do.

Here is what I have learned from watching my older apps fail to rank in AI search:

1. Client-side rendering is a wall.
Most of my old projects are pure client-side React. To a human, they load fast and look great. To an AI crawler that does not execute JavaScript, they look like a blank page with a <div id="root">. If the bot cannot read the text in the initial HTML, it just leaves.

2. Words matter more than pictures.
I used to rely on slick screenshots and minimal copy for landing pages. AI vision models might be smart, but standard web crawlers still run on plain text. I have started rewriting my landing pages to clearly explain the problem and the solution in plain English.

3. Semantic HTML is back.
Div soup is out. Using actual <header>, <nav>, <main>, and <article> tags helps the AI understand the hierarchy of the page. It needs to know what is navigation and what is the actual product description.

4. Structured data helps.
I used to ignore JSON-LD and schema markup. It felt like boring SEO work. Now, I put it everywhere. It feeds the bots exact data about what the app is, who made it, and what it costs.

I am still figuring this out. I am currently working through the discovery problem one app at a time to make my work visible to LLMs. It is frustrating to realize the rules changed while I was busy migrating code — but that is the job.

We spent a decade optimizing for Google search. Now we have to figure out how to talk to the bots.

How are you handling this shift? Are you doing anything specific to get your projects seen by AI search tools?