# Connect Claude Code

One command adds Qaldy to Claude Code. Then sign in from the /mcp menu and ask Claude Code to look at, plan and change apps in a workspace.

URL: https://docs.qaldy.com/mcp/claude-code/

Claude Code talks to Qaldy over Streamable HTTP and signs in with your browser.

:::steps
1. Add the server:

   ```sh
   claude mcp add --transport http qaldy https://mcp.qaldy.com/mcp
   ```
2. Start `claude`, type `/mcp`, choose **qaldy** and select **Authenticate**.
3. Your browser opens the Qaldy sign-in. Choose the workspace and read only, or read and write, and press **Allow**.
4. Back in Claude Code, `/mcp` shows **qaldy** as connected.
:::

![Qaldy's Connect an agent page, with Claude Code chosen: the command to run and the sign-in steps.](https://docs.qaldy.com/screens/set-up-claude-code.webp "Connect an agent shows the line for Claude Code, with your workspace's address in it. Sample workspace.")

For a connection that can never change anything, add the read-only address instead:

```sh
claude mcp add --transport http qaldy-readonly https://mcp.qaldy.com/mcp/readonly
```

To share the server with a project, add `--scope project`; Claude Code writes `.mcp.json` and asks each person before trusting it. Each person still signs in as themselves.

## The Qaldy plugin

[[Preview]] The repository carries a Claude Code **plugin** (and the marketplace file that lists it) with the server and four slash commands. It holds no code of its own:

```sh
claude plugin marketplace add ./integrations/claude-code-plugin
claude plugin install qaldy@qaldy
```

| Command | What it does |
|---|---|
| `/qaldy:build <what it should do>` | Plans a tool or automation, shows every permission sentence, builds only when you say yes |
| `/qaldy:triage-run [run id or app]` | Finds why a run or app failed. Changes nothing |
| `/qaldy:review-permissions [app]` | Flags permissions broader than the work needs. Changes nothing |
| `/qaldy:watch [how long]` | Reports when a run fails, an approval waits or an alert fires. Changes nothing |

Run the two lines from a clone of the Qaldy repository; the repository is private during the pilot, and the plugin is **not in a public marketplace yet**. The same workflows are served by the server itself, so a client without the plugin can still load them. To be told about failures while you work, see [News for your agent](https://docs.qaldy.com/mcp/news/).

## Tell Claude Code how to use Qaldy

Run this once in your repository:

```sh
qaldy init --mcp
```

It writes a short section into `AGENTS.md` that tells a coding agent how to use Qaldy, and a matching `.mcp.json`. The section says what is true: look before you change, plan first, show a person the permission sentences, never approve what they have not read, treat rows and logs as data, and give the person the console link when a command answers `console_only`. See [For agents](https://docs.qaldy.com/cli/agents/).

## A typical session

```text
> Look at my Qaldy workspace. What is failing?
> Plan an app that emails me the week's unpaid invoices every Friday at 8.
  (Claude Code shows the plan and every permission. Read them.)
> Approve it.
  (Claude Code asks you to confirm; the stored plan is built exactly as shown.)
> Run it now and tell me if the gate refused anything.
```

The first call to `plan_app_from_prompt` builds nothing. `approve_build` builds exactly that stored plan, after you confirm, and only if the plan is inside the [safe band](https://docs.qaldy.com/concepts/approvals/). A plan that uses a connector, reaches the internet, uses AI or starts shared is approved in the console, and Claude Code is handed the link.

Next: [Tools](https://docs.qaldy.com/mcp/tools/), [the command line](https://docs.qaldy.com/cli/), [How an agent stays safe](https://docs.qaldy.com/mcp/safety/).