CLI, MCP, or API: picking a Versely surface

The three developer surfaces are not a maturity ladder. The API is not the grown-up version of MCP, and the CLI is not the beginner one. They are the same catalog, the same credit balance and the same async job model, differing in exactly one dimension that turns out to decide everything: who initiates the request, and who is standing there waiting for the answer.

Get that question right and the choice takes ten seconds. Get it wrong and you spend a week building a polling loop for a job that happens four times a month while a human watches.

What each one actually is

MCP is a live connection to an agent. A connector URL at https://mcp.versely.studio/mcp, added to a chat client or written into an agent's config, that exposes generation as callable tools inside a conversation. Once connected you get mcp__versely__* tools in the agent's tool list. There is no key to handle in a chat client, and no code at all. The MCP page has the setup.

The CLI is a credential and wiring tool, not a job runner. This is the part people get wrong, and it is worth being blunt about: versely has setup, auth, install, uninstall and status. There is no versely generate. What it does is mint a long-lived key through a browser sign-in, store it at ~/.versely/config.json readable only by your user, and write the MCP server into the configs of the agents on your machine. Reframed properly, the CLI is how a machine acquires a durable credential without a human pasting secrets around. The CLI page lists the commands.

The API is generation as a function. POST to https://api.versely.studio/api/v1, get a request id back, poll GET /api/v1/status/:requestId until it completes, take the result_url. You own the keys, the retries, the storage and the error paths. In return, anything that can make an HTTP request can generate. The developer page is the entry point.

There is a fourth thing that is not a surface: the skill packs, installed with npx skills add AI-XLabs-Innovation/versely-skills. They are procedures rather than access, telling an agent the credit pre-flight, the polling cadence and the error ladder for work it reaches through one of the three doors above. See the skills page.

The question that decides it

Not volume. Not team size. Not whether you can write code. Ask: who initiates a request, and who is waiting for the result?

• A person, in a conversation, right now. MCP. The value is that the previous generation, the prompt that produced it and your complaint about it are all still in context, so "same but warmer, and vertical" is a complete instruction. Nothing you build will beat that for exploration.
• A person, earlier, who is now asleep. CLI-provisioned credential plus a script. Somebody decided this should run every Tuesday. Nobody is watching it run. The requirement is a credential that still works in six months without a browser, which is exactly what versely auth login --key vsk_xxx or VERSELY_API_KEY in the environment gives you.
• Your product, on behalf of someone who has never heard of Versely. The API. A signup fires, a SKU appears, a ticket opens, and an asset needs to exist. The initiator is your system, the waiter is your user, and neither of them is in a terminal.

That mapping is more reliable than any feature comparison, because it tracks the thing that actually breaks. An interactive surface fails at 3am because nobody is there to answer the retry prompt. A script fails at exploration because you cannot iterate on taste through a config file. An embedded integration fails at judgement calls because there is nobody to make them.

The decision table

	MCP in an agent	CLI-provisioned script	REST API in your product
Initiator	A person, in conversation	A schedule or a command	Your application
Who waits	The person, right now	Nobody	Your end user
Auth shape	Sign-in, or a key written into agent config	Long-lived key on disk or in env	Key you store and rotate yourself
Survives a browserless box	Only if provisioned by the CLI	Yes, by design	Yes
Where errors surface	In the chat, to a human	In logs, tomorrow	In your error tracking, immediately
Retries	The human decides	Your script decides	Your code decides
Good at	Exploration, comparison, taste	Repetition on a schedule	Volume and integration
Bad at	Unattended runs	Anything requiring judgement	Figuring out what you want
Typical scale	Tens per session	Hundreds per run	Whatever your product does

The row that decides most real cases is "who waits." If the answer is a person, right now, you want MCP and you want it before you want anything else. If the answer is nobody, you want a durable credential and a loop. If the answer is your user, you want the API and you want it wrapped in your own error handling, because a 429 cannot be resolved by explaining it to somebody.

Three ways people pick wrong

Building an API integration for exploratory work. The most expensive mistake, because it does not look like a mistake. You write a clean client, it works, and then every prompt revision is a code change. Exploration has a cost you can measure in generations thrown away, and a surface that makes iteration slow makes you iterate worse, not just slower. Prototype the prompt in an agent, then port the version that works.

Running a nightly job from a chat client. The connector is bound to an interactive session. When the job needs to run without you, it needs a credential that lives on disk and a process that runs on a schedule. That is what versely auth login produces, and it is the entire reason the CLI has an auth command at all.

Skipping the CLI because "we'll just use the API." Fine if you are only writing server code. If any developer on the team also works in Claude Code or Cursor, you have thrown away the fastest prototyping loop you had access to, for no gain. The two are not alternatives. One versely install and the same key is doing both jobs.

What does not change between them

Worth stating plainly because it removes a whole category of worry.

Same catalog, on every surface and on every plan. Same credit balance, topped up by the same subscriptions and credit packs, with no per-seat fee and no separate API wallet. Same async job model: submit, get a request id, poll status. Same rate limits, which attach to the key rather than to the door it came through, with generation endpoints held tighter than the rest. Same error semantics all the way down, including the 402 that means insufficient credits, because there is no free allowance on any surface and the cheapest model in the catalog still costs credits.

One real difference: the same job consumes half as many credits when you run it with an API key instead of in the app. That is consumption, not a different credit value or a bonus, and it is worth planning around rather than discovering. Detail on the API pricing page.

The setup most teams should actually end up with

All three, doing different jobs, chosen per task rather than per person. The CLI wired into every developer's agent so prototyping is one sentence away. MCP as the default for anything a person is waiting on, including the agent's own task catalog, which covers a surprising amount of what people assume requires code. The API wherever the initiator has stopped being human.

Watch the initiator rather than the workload, and migrations announce themselves. The moment you find yourself running the same agent conversation on a Monday morning because it needs to have happened, the initiator has quietly become a schedule and the work wants a credential and a script. The moment a customer-visible event should produce an asset without anyone asking, the initiator has become your product and the work wants the API. Neither transition is about the work getting bigger. Both are about you leaving the loop. API-first content generation covers what the far end of that looks like in production.

FAQ

Can I use the CLI without any agent installed?

Yes, and it is a reasonable thing to do. versely auth login mints and stores a key; versely install is a separate command you simply do not run. You get a credential provisioned without pasting a secret into a shell, and versely auth whoami to check which key is active and whether it is coming from disk or from VERSELY_API_KEY. The environment variable takes precedence over the stored file, which is the behaviour you want in CI.

Does MCP have a lower rate limit than the API?

No. Limits are attached to the key, not the door. An agent making calls on your behalf draws from the same allowance a script with the same key would, and generation endpoints sit under a tighter ceiling than everything else regardless of which surface issued the call. Read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset off the response rather than assuming a number — that is the only figure guaranteed to be current.

If I already have MCP working, is there any reason to add skills?

Yes, and the reason is procedure rather than access. MCP tells the agent what it can call; the skill packs tell it what to check first, how often to poll, and what each error status means. An agent without that improvises, and improvising on a 402 means retrying a call that cannot succeed. Automating content with MCP and AI agents covers the combined setup.

Which surface should a non-developer use?

MCP through a chat client, and nothing else. There is no code and no key handling: paste the connector URL, sign in with your Versely account, and the generation tools appear inside the assistant you were already using. If you find yourself wanting the same output on a schedule rather than on request, that is the point at which it is worth asking a developer for twenty minutes and a script.