--- title: Quickstart with Claude Code description: Connect Claude Code to Kaviris over MCP and deploy your app by asking for it. --- # 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: ```sh 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 `/mcp` dialog waits, you can instead run `curl ''` 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](https://docs.beta.kaviris.com/skills/deploy/SKILL.md) 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: ```sh 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: 1. Reserve a name for your app (`create_app`). The name is yours for good, and your app gets the address `https://.apps.beta.kaviris.com`. 2. Upload your source (`create_upload`). It sends committed files only, so **commit your work first**. `.env` files are never sent. 3. Start the deploy (`deploy`) and follow it (`get_deploy`). A small app takes about 3 minutes, a Next.js app about 5. 4. On the first deploy, show you the draft [contract](../concepts/contract.md) and approve it (`approve_contract`). 5. 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](../refusals/index.md). 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](../refusals/vuln_fixable.md)). > **One thing to check in your code:** Kaviris tells your app which port to > listen on in the `PORT` environment 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 on > `0.0.0.0`. Most frameworks already do. If yours doesn't, the deploy > stops with [port_mismatch](../refusals/port_mismatch.md), 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](../concepts/secrets.md). ## 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](../reference/mcp-tools.md). ## Tips - If Claude Code says it is not authorized, run `/mcp` and authenticate again. Access tokens last 10 minutes and are refreshed for you. - If Claude Code says it has no Kaviris tools, check `claude mcp list` in a terminal. Listed but no tools: start a new session. Not listed: step 1. - You can also use the [`kaviris` command line](cli.md) next to Claude Code. It is the most private way to send secrets.