Connect Claude Code · Qaldy Docs

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.

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

Add the server:

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

Start claude, type /mcp, choose qaldy and select Authenticate.
Your browser opens the Qaldy sign-in. Choose the workspace and read only, or read and write, and press Allow.
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. — 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:

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:

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.

Tell Claude Code how to use Qaldy#

Run this once in your repository:

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.

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. 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, the command line, How an agent stays safe.