Quickstart with Claude Code
Claude Code talks to Kaviris through the Kaviris MCP server. You add the server once, sign in once in your browser, and from then on you can say "deploy this to Kaviris" in any project.
1. Add the server
In a terminal, in any folder:
claude mcp add --scope user --transport http kaviris https://api.beta.kaviris.com/mcp
--scope user makes it work in all your projects. Without it, Claude Code
keeps the server for the folder you ran the command in, and in other folders
the agent says it has no Kaviris tools.
Start a new Claude Code session now. A session that was already open does
not see the server, and neither does an agent working in it. Until you sign in,
claude mcp list shows ! Needs authentication, which is expected.
2. Sign in
You start this, not the agent: an agent cannot sign in for you. In the new
session, type /mcp, pick kaviris and choose Authenticate. There is no
token to copy or paste.
A browser window opens at auth.beta.kaviris.com. Create your account: your email address, the
6-digit code we email you to confirm it, then a passkey (your phone,
fingerprint or security key). Sign-in with GitHub or
Google is coming.
Then a page says Grant access to Claude Code and Verified: this app is published by claude.ai. It lists the permissions below, then your roles, email address and profile (so that Kaviris knows who you are), with Yes and No:
| Permission | What it lets the agent do |
|---|---|
| See your apps, deploys and logs | read |
| Create and deploy apps | create apps, upload, deploy, change and approve the contract |
| Set your apps' secrets (never read them) | write secret values, never read them |
Deleting apps and rolling back are not given to agents automatically. When an agent wants to do either, it must show you a summary first and get your OK.
Choose Yes. The browser hands back to Claude Code, and /mcp shows
kaviris as connected. If Claude Code runs on a machine without a browser
(a remote machine over SSH), open the sign-in link it shows on your phone or
laptop and see below.
Signing in from your phone or another device
The agent and the browser do not have to be on the same machine: you can
approve on your phone while the agent runs on your laptop, or on your laptop
while it runs on a server over SSH. The browser just cannot hand the sign-in
back to the agent by itself. So after you choose Yes, auth.beta.kaviris.com
shows Approved — finish in your agent:
- Continue on this computer: when the browser and the agent are on the same machine.
- Agent on another device?: copy the message and paste it into the chat
with your agent. It opens the address in it on its own machine with a
command such as
curl, and that finishes the sign-in. While Claude Code's/mcpdialog waits, you can instead runcurl '<the address>'in a second terminal on that machine (a second SSH session works), or open the address in a browser there.
The address works once, only for the agent that started the sign-in, and for about 5 minutes. Paste it only into your own agent, one you started yourself: never send it to anyone.
Give it the deploy skill (optional)
The server is enough to deploy. The deploy skill adds the loop of reading refusals, fixing, redeploying and rolling back, so that Claude Code does not have to work it out. Install it for all your projects:
mkdir -p ~/.claude/skills/kaviris-deploy && curl -fsSL https://docs.beta.kaviris.com/skills/deploy/SKILL.md -o ~/.claude/skills/kaviris-deploy/SKILL.md
A new session loads it by itself when you ask to deploy to Kaviris.
3. Ask it to deploy
Deploy this app to Kaviris.
Claude Code will:
- Reserve a name for your app (
create_app). The name is yours for good, and your app gets the addresshttps://<name>.apps.beta.kaviris.com. - Upload your source (
create_upload). It sends committed files only, so commit your work first..envfiles are never sent. - Start the deploy (
deploy) and follow it (get_deploy). A small app takes about 3 minutes, a Next.js app about 5. - On the first deploy, show you the draft contract
and approve it (
approve_contract). - Tell you the address once the app is live.
If the deploy is refused, Claude Code gets the reason and the fix, fixes it, and deploys again. You can read about each reason in the refusal list.
If a library your app uses has a known security hole, the deploy still goes live, and Claude Code tells you which upgrades Kaviris recommends. Say "yes, apply them" and it applies Kaviris's ready-made patch, commits and deploys again (how it works).
One thing to check in your code: Kaviris tells your app which port to listen on in the
PORTenvironment variable. Read it instead of writing a port number into the code:app.listen(process.env.PORT || 3000)in Node,int(os.environ.get("PORT", "8000"))in Python, and listen on0.0.0.0. Most frameworks already do. If yours doesn't, the deploy stops with port_mismatch, and your agent can fix it.
4. Add your API keys
Set OPENAI_API_KEY from my .env.
Claude Code asks Kaviris for a one-time link and runs a short command on
your machine that sends the value from your .env file straight to
Kaviris. The key never passes through the AI model. See
Secrets.
5. Day to day
| Say | What happens |
|---|---|
| "Is my app up?" | get_app |
| "Why did the deploy fail?" | get_deploy, then get_logs |
| "Allow it to call api.stripe.com" | update_contract, then approve_contract |
| "Apply the recommended upgrades" | get_deploy (upgrades), then git apply, commit, deploy |
| "Show me errors from the last hour" | get_logs, get_metrics |
| "Roll back to the previous version" | list_releases, then rollback (you confirm) |
| "Restore the database to yesterday 14:00" | restore_app (you confirm) |
| "Download a copy of my app" | export_app (the database is exported in the portal) |
| "Delete the app" | delete_app (you confirm) |
All tools are listed in the MCP tool reference.
Tips
- If Claude Code says it is not authorized, run
/mcpand authenticate again. Access tokens last 10 minutes and are refreshed for you. - If Claude Code says it has no Kaviris tools, check
claude mcp listin a terminal. Listed but no tools: start a new session. Not listed: step 1. - You can also use the
kaviriscommand line next to Claude Code. It is the most private way to send secrets.