One command to wire MCP into detected agents

Hand-editing mcpServers JSON per agent is how a laptop ends up with Versely in Cursor and a stale key in Claude Code. versely install is the command that looks at what is actually on the machine, writes the Versely MCP server into each config it finds, and attaches the key you already minted. One invocation. Every detected agent.

It is not a generate command. It does not talk to a model. It is a wiring tool, and treating it as optional is how you spend the afternoon in the wrong file.

What it actually writes

After versely auth login (or versely auth login --key vsk_… if you already have a key), run:

versely install

With no --agent flag, the CLI detects installed coding agents and writes a Versely entry into each one it finds. Today that is two targets. Claude Code gets an HTTP server at https://mcp.versely.studio/mcp under mcpServers.versely in ~/.claude.json, with an Authorization: Bearer header carrying your key. Cursor gets the same shape in ~/.cursor/mcp.json. The CLI page is the product surface; the command list is short on purpose: setup, auth, install, uninstall, status.

The key is copied into the agent config at install time. That detail matters more than the file path. versely auth login on its own updates ~/.versely/config.json and nothing else. If you rotate a key and skip versely install, the agent keeps sending the old bearer token until you rewrite the header.

What it does not write: the skill packs. Skills are a separate layer, installed with npx skills add AI-XLabs-Innovation/versely-skills or as the first step of npx @versely/cli setup. MCP tools are the callables. Skills are the instructions. Wiring skills into Claude Code covers that half. This command is the MCP half.

Detection, flags, and the three status states

The CLI page also names Codex, Gemini CLI, Windsurf, Copilot, Cline, Continue, Goose, and Replit, plus a longer tail. That is the product's reach story: the hosted MCP server can be added in any client that speaks remote MCP, and the skills installer writes procedures into many agents. versely install only writes the two config files above. Detection looks for ~/.claude.json or ~/.claude, and for ~/.cursor. If the agent lives somewhere else, detection misses it.

Target one agent when you do not want the whole machine touched:

versely install --agent claude-code

Force a write when detection reports nothing:

versely install --agent '*'

Then restart the agent. MCP config is not reloaded in place. A correct write that still shows no mcp__versely__* tools is almost always a process that started before the file changed. That is the single most common "install did nothing" report.

versely status is how you stop guessing. It prints the auth line (a masked key, and whether it came from ~/.versely/config.json or VERSELY_API_KEY) and a per-agent line in one of three states:

Status	Meaning	Fix
not detected	The CLI cannot see that agent's config path	Install the agent, or versely install --agent '*' to force
detected, not connected	The agent is on disk; Versely is not in its MCP config	versely install --agent <name>
connected	The Versely server entry is present	Restart the agent if tools still do not appear

Those three states are different bugs. Re-running setup because status says detected, not connected wastes a browser trip. The missing piece is the write, not the key.

VERSELY_API_KEY in the environment takes precedence over the file on disk. That is the behaviour you want in CI. It is also why a laptop with a secret exported in .zshrc can look "signed in" to versely status while ~/.versely/config.json is empty. Check the source the status line names, not the file you assume.

The sequence around it

versely install is the third step, not the first.

1. Install the binary. npm install -g @versely/cli.
2. Mint or attach a key. versely auth login opens a browser, runs an authorization-code flow with PKCE over a localhost redirect, and stores a long-lived vsk_ key at ~/.versely/config.json with user-only permissions. On a box with no browser, versely auth login --key vsk_… skips the flow. The first generation from the terminal walkthrough is this step in slow motion.
3. Wire MCP. versely install.
4. Restart every agent it touched. Then ask: "Generate an image with Versely."

The one-shot that runs skills, auth, and MCP wiring in that order is:

npx @versely/cli setup

Use setup on a fresh laptop. Use install when the key already exists and you added an agent, rotated a key, or cloned a new machine account. Use npx skills add AI-XLabs-Innovation/versely-skills when MCP is already connected and you only want the procedures. The skills page is that path.

A chat client is a different door. Claude's Settings → Connectors flow pastes https://mcp.versely.studio/mcp and signs in through OAuth. No CLI, no file write, no detection. The MCP page is that path. versely install exists because a terminal agent does not have that UI. It needs a config file, and it needs the same file written in every agent you actually run.

If you only ever use one agent, --agent keeps the blast radius to that config. If you bounce between Cursor and Claude Code in the same week, run it with no flag and let detection do the boring part.

After the key rotates

Revoking a key does not patch the copies versely install already wrote. The agent config still has a bearer token. The next tool call returns 401.

The recovery is mechanical:

1. Mint a new key (browser login, or paste with --key).
2. Run versely install again so every detected agent gets the new header.
3. Restart the agents.
4. Confirm versely status reads connected and the auth line shows the new prefix.

versely uninstall strips the Versely entry from every agent config it knows, or --agent claude-code to target one. versely auth logout clears the stored key separately. Neither touches the skill packs. Both are safe to run more than once. Uninstall is how you stop an agent you no longer use from sitting on a live key.

For teams, settle the spending policy before you roll this out to every laptop. An agent with a key can spend credits without a confirmation dialog in the web app. Same catalog, same balance, no free allowance on any surface. The developer page is the index of the three setup paths if you need to start a machine over. Guardrails for agent-run brand content is the policy conversation that should happen before the install, not after the first surprise invoice.

FAQ

Does versely install generate anything?

No. There is no versely generate. The CLI covers setup, auth, install, uninstall, and status. Generation is HTTP against https://api.versely.studio, or a tool call once MCP is wired. The install command only writes config.

I ran it and the agent still has no Versely tools.

Restart the agent first. If versely status says not detected, the CLI cannot see that agent's config path: use --agent '*' or confirm the agent is installed where the CLI expects. If it says detected, not connected, run versely install --agent <name> and restart. If it says connected and tools are still missing, you are looking at a process started before the write.

Do I have to run it on every agent I install later?

Yes, if you want Versely in that agent and the CLI knows its config path. Detection only sees what is on disk now, and today that is Claude Code and Cursor. Installing one of those later does not retroactively wire last month's run. Run versely install again, or --agent the new one. For an agent the CLI does not know, paste the MCP URL in that client's connector UI, or add the HTTP entry by hand.

How is this different from pasting the connector URL?

Same MCP server, different credential shape. The connector UI is an OAuth sign-in in a chat client. versely install writes a long-lived key into a local agent's config so the agent can call the server without a consent screen on every session. Pick the door that matches how you launch the agent. The MCP, API, or web UI comparison is the wider version of that choice.