@mediamonks/canopy-cli 0.7.30 → 0.7.31

package/dist/{ai-fAvjdjVX.mjs → ai-DHLnyqfq.mjs}

@@ -1,4 +1,5 @@
-import { d as withContext, l as apiRequest, r as reportErrors } from "./ui-CeupNHNa.mjs";
+import { i as apiRequest, o as withContext } from "./api-C4rMhE7i.mjs";
+import { r as reportErrors } from "./ui-C_jSc1Kz.mjs";
 import { defineCommand } from "citty";
 //#region src/ai.ts
 /**

package/dist/{ui-CeupNHNa.mjs → api-C4rMhE7i.mjs}

@@ -1,6 +1,4 @@
 import { n as siteConfig } from "./site-DM2J10CB.mjs";
-import { spawn } from "node:child_process";
-import { cancel, isCancel } from "@clack/prompts";
 //#region src/api.ts
 /**
 * Authenticated requests to the Canopy control plane. Credentials, in order:
@@ -340,123 +338,4 @@ async function apiDataRequest(method, path, projectSlug, body, rawContentType, c
 	return await response.json();
 }
 //#endregion
-//#region src/ui.ts
-/**
-* Shared terminal UX plumbing: clack prompt unwrapping and uniform
-* command error reporting.
-*/
-/** Unwrap a clack prompt result, exiting cleanly when the user cancels (ctrl-c). */
-function unwrap(result) {
-	if (isCancel(result)) {
-		cancel("Aborted.");
-		process.exit(130);
-	}
-	return result;
-}
-/** Terminal width to wrap error copy to, bounded so it stays readable. */
-const TEXT_WIDTH = Math.min(process.stdout.columns || 80, 88);
-/** Render `  Label  text…`, wrapping and aligning continuation lines under the text. */
-function labeled(label, text) {
-	const lead = `  ${label}  `;
-	const indent = " ".repeat(lead.length);
-	const max = Math.max(TEXT_WIDTH - lead.length, 24);
-	const lines = [];
-	let line = "";
-	for (const word of text.split(/\s+/)) if (line && line.length + 1 + word.length > max) {
-		lines.push(line);
-		line = word;
-	} else line = line ? `${line} ${word}` : word;
-	if (line) lines.push(line);
-	return lines.map((l, i) => (i === 0 ? lead : indent) + l).join("\n");
-}
-/**
-* Compose a command failure. API failures get a three-part block — what we
-* tried (headline), why it failed, and how to fix it — everything else prints
-* as a single `canopy <name>: <message>` line.
-*/
-function formatCliError(name, err) {
-	if (err instanceof ApiError) {
-		const { headline, why, fix } = err.explain();
-		return [
-			`canopy ${name}: ${headline}`,
-			"",
-			labeled("Why", why),
-			labeled("Fix", fix),
-			""
-		].join("\n");
-	}
-	return `canopy ${name}: ${err instanceof Error ? err.message : String(err)}`;
-}
-const kebab = (s) => s.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
-const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-/**
-* Reject flags a command does not declare. citty parses with strict: false, so
-* a misspelled or not-yet-released flag would otherwise be silently dropped —
-* on `deploy --staging` (pre-0.7) that meant deploying to the wrong channel.
-*/
-function assertKnownFlags(name, rawArgs, argDefs) {
-	const known = /* @__PURE__ */ new Set([
-		"help",
-		"h",
-		"version",
-		"profile"
-	]);
-	for (const [key, def] of Object.entries(argDefs)) {
-		if (def.type === "positional") continue;
-		known.add(key);
-		known.add(kebab(key));
-		known.add(camel(key));
-		const aliases = typeof def.alias === "string" ? [def.alias] : def.alias ?? [];
-		for (const a of aliases) known.add(a);
-		if (def.type === "boolean") {
-			known.add(`no-${key}`);
-			known.add(`no-${kebab(key)}`);
-		}
-	}
-	for (const token of rawArgs) {
-		if (token === "--") break;
-		if (!token.startsWith("-") || token === "-") continue;
-		const body = token.replace(/^--?/, "").split("=")[0] ?? "";
-		if (!body || /^\d/.test(body)) continue;
-		if (!known.has(body)) throw new Error(`Unknown flag --${body}. Run \`canopy ${name} --help\` to see supported flags — if the docs mention it, your CLI may be outdated (\`canopy upgrade\`).`);
-	}
-}
-/** Wrap a command action so failures print an actionable report and exit 1. */
-function reportErrors(name, action) {
-	return async (...args) => {
-		try {
-			const ctx = args[0];
-			if (ctx?.rawArgs && ctx.cmd?.args) assertKnownFlags(name, ctx.rawArgs, ctx.cmd.args);
-			await action(...args);
-		} catch (err) {
-			console.error(formatCliError(name, err));
-			process.exit(1);
-		}
-	};
-}
-/** Guard interactive prompts: bail with a actionable message on non-TTY runs. */
-function requireTty(hint) {
-	if (!process.stdin.isTTY) throw new Error(`This needs an interactive terminal — ${hint}`);
-}
-/**
-* API timestamps are UTC — ISO with a Z suffix, though a lagging API site may
-* still send the bare "YYYY-MM-DD HH:MM:SS" form. Parse either as UTC and
-* render compact local wall-clock time ("2026-08-25 14:23").
-*/
-function formatDateTime(raw) {
-	const hasZone = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(raw);
-	const date = new Date(hasZone ? raw : raw.replace(" ", "T") + "Z");
-	if (Number.isNaN(date.getTime())) return raw;
-	const pad = (n) => String(n).padStart(2, "0");
-	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
-}
-/** Open a URL in the default browser, fire-and-forget. */
-function openBrowser(url) {
-	spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open", [url], {
-		stdio: "ignore",
-		detached: true,
-		shell: process.platform === "win32"
-	}).on("error", () => {}).unref();
-}
-//#endregion
-export { unwrap as a, apiDownload as c, withContext as d, requireTty as i, apiRequest as l, openBrowser as n, ApiError as o, reportErrors as r, apiDataRequest as s, formatDateTime as t, apiUpload as u };
+export { apiUpload as a, apiRequest as i, apiDataRequest as n, withContext as o, apiDownload as r, ApiError as t };

package/dist/{db-KTLn8J1u.mjs → db-BB6O6085.mjs}

@@ -1,6 +1,7 @@
 import { c as resolveProject, o as projectFlagArgs } from "./site-DM2J10CB.mjs";
-import { a as unwrap, d as withContext, i as requireTty, l as apiRequest, r as reportErrors, s as apiDataRequest } from "./ui-CeupNHNa.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-C8yRPJIX.mjs";
+import { i as apiRequest, n as apiDataRequest, o as withContext } from "./api-C4rMhE7i.mjs";
+import { a as unwrap, i as requireTty, r as reportErrors } from "./ui-C_jSc1Kz.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-Czlcddyz.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";

package/dist/{deploy-CBf44bvG.mjs → deploy-B-znPE-v.mjs}

@@ -1,6 +1,7 @@
 import { a as projectDirArgs, c as resolveProject, l as stagingUrl, n as siteConfig, o as projectFlagArgs, s as projectUrl, u as tryReadCanopyJson } from "./site-DM2J10CB.mjs";
-import { a as unwrap, c as apiDownload, d as withContext, l as apiRequest, r as reportErrors, s as apiDataRequest, t as formatDateTime } from "./ui-CeupNHNa.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-C8yRPJIX.mjs";
+import { i as apiRequest, n as apiDataRequest, o as withContext, r as apiDownload } from "./api-C4rMhE7i.mjs";
+import { a as unwrap, r as reportErrors, t as formatDateTime } from "./ui-C_jSc1Kz.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-Czlcddyz.mjs";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -26,6 +27,7 @@ async function bundleWorker(projectDir, entry) {
 			format: "esm",
 			target: "es2022",
 			packages: "bundle",
+			external: ["node:*"],
 			logLevel: "silent"
 		});
 		return new Uint8Array(readFileSync(outfile));

package/dist/{dev-JlzMZJow.mjs → dev-CkhBnSlv.mjs}

@@ -1,7 +1,9 @@
 import { a as projectDirArgs, c as resolveProject, i as projectDialect, n as siteConfig, u as tryReadCanopyJson } from "./site-DM2J10CB.mjs";
-import { d as withContext, l as apiRequest, o as ApiError, r as reportErrors, t as formatDateTime } from "./ui-CeupNHNa.mjs";
-import { r as readMigrationFiles } from "./migrations-C8yRPJIX.mjs";
-import { n as stampWorkerHeaders } from "./src-C7zPhbxi.mjs";
+import { i as apiRequest, o as withContext, t as ApiError } from "./api-C4rMhE7i.mjs";
+import { r as reportErrors, t as formatDateTime } from "./ui-C_jSc1Kz.mjs";
+import { r as readMigrationFiles } from "./migrations-Czlcddyz.mjs";
+import { r as stampWorkerHeaders } from "./src-BkACMkol.mjs";
+import { n as writeDevServerRecord } from "./dev-server-file-Dk9pk4AR.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
 import { existsSync } from "node:fs";
@@ -38,7 +40,7 @@ async function workerPlugin(flags, slug) {
 		console.log(`note: canopy.json points "worker" at ${entry}, which does not exist — skipping.`);
 		return;
 	}
-	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-DjJGSUGj.mjs");
+	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-CaCsGBkn.mjs");
 	const secrets = readDevVars(flags.dir);
 	const email = siteConfig().email;
 	const plugin = workerDevPlugin({
@@ -120,6 +122,11 @@ async function startVite(flags, serverOverrides, extraPlugins = []) {
 		}
 	});
 	await server.listen();
+	const local = server.resolvedUrls?.local[0];
+	if (local) {
+		const remove = writeDevServerRecord(flags.dir, new URL(local).origin);
+		server.httpServer?.once("close", remove);
+	}
 	return server;
 }
 /**
@@ -218,7 +225,7 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-BA_TPWpN.mjs");
+		const { fetchProjectDump } = await import("./local-DAYCNUyz.mjs");
 		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
 		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
@@ -233,7 +240,7 @@ async function devLocal(flags, slug) {
 		const reason = err instanceof ApiError ? err.explain().why : String(err);
 		console.log(`Note: ai/services will be unavailable — could not reach the platform (${reason}).`);
 	}
-	const { createSandbox } = await import("./local-BA_TPWpN.mjs");
+	const { createSandbox } = await import("./local-DAYCNUyz.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),

package/dist/dev-MoHHjQh1.mjs

@@ -0,0 +1,2 @@
+import { n as devCommand } from "./dev-CkhBnSlv.mjs";
+export { devCommand };

package/dist/dev-server-file-Dk9pk4AR.mjs

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/dev-server-file.ts
+/**
+* Where a running `canopy dev` can be reached, for `canopy mcp serve --local`
+* (docs/49): `.canopy/dev-server.json` in the project directory, written once
+* the dev server listens and removed when it stops. The pid lets a reader
+* tell a live server from a file a crash left behind.
+*/
+const devServerFile = (dir) => join(dir, ".canopy", "dev-server.json");
+function writeDevServerRecord(dir, url) {
+	const path = devServerFile(dir);
+	mkdirSync(join(dir, ".canopy"), { recursive: true });
+	writeFileSync(path, JSON.stringify({
+		url,
+		pid: process.pid
+	}) + "\n");
+	let removed = false;
+	const remove = () => {
+		if (removed) return;
+		removed = true;
+		if (readDevServerRecord(dir)?.pid === process.pid) rmSync(path, { force: true });
+	};
+	process.once("exit", remove);
+	return remove;
+}
+function readDevServerRecord(dir) {
+	try {
+		const parsed = JSON.parse(readFileSync(devServerFile(dir), "utf8"));
+		if (typeof parsed.url !== "string" || typeof parsed.pid !== "number") return null;
+		return {
+			url: parsed.url,
+			pid: parsed.pid
+		};
+	} catch {
+		return null;
+	}
+}
+/** Whether a process with this pid exists (signal 0 checks without sending). */
+function processAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err.code === "EPERM";
+	}
+}
+/** The running dev server for this directory, or null when there is none. */
+function liveDevServer(dir) {
+	const record = readDevServerRecord(dir);
+	return record && processAlive(record.pid) ? record : null;
+}
+//#endregion
+export { writeDevServerRecord as n, liveDevServer as t };

package/dist/{dev-worker-DjJGSUGj.mjs → dev-worker-CaCsGBkn.mjs}

@@ -1,4 +1,4 @@
-import { n as stampWorkerHeaders, t as redactCanopyCredentials } from "./src-C7zPhbxi.mjs";
+import { n as redactCanopyCredentials, r as stampWorkerHeaders, t as CALLER_HEADER } from "./src-BkACMkol.mjs";
 import { readFileSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 //#region src/dev-worker.ts
@@ -12,6 +12,26 @@ function isWorkerPath(pathname) {
 }
 /** The manual schedule tick, mirroring the shim's own path (docs/07). */
 const SCHEDULED_PATH = "/__canopy/scheduled";
+/** A project's tools endpoint (docs/49), served for `canopy mcp serve --local`. */
+const MCP_PATH = "/__canopy/mcp";
+const LOCAL_HOSTNAMES = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
+/**
+* Whether a request to the local tools endpoint comes from `canopy mcp serve
+* --local` rather than a web page. A page on any site can make the browser
+* call a localhost port (and DNS rebinding can make it look same-origin), so
+* the dev server answers only a localhost Host with no Origin header at all —
+* the CLI bridge sends none, a browser always does on a cross-site POST.
+*/
+function isLocalToolsRequest(headers) {
+	if (headers.has("origin")) return false;
+	const host = (headers.get("host") ?? "").toLowerCase();
+	const hostname = host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.split(":")[0];
+	return LOCAL_HOSTNAMES.has(hostname ?? "");
+}
 /**
 * `.dev.vars` — local-only worker secrets, the wrangler-shaped file the repo
 * already gitignores.
@@ -255,11 +275,23 @@ function workerDevPlugin(options) {
 			server.middlewares.use((req, res, next) => {
 				const path = (req.url ?? "/").split("?")[0] ?? "/";
 				const scheduled = path === SCHEDULED_PATH;
-				if (!isWorkerPath(path) && !scheduled) return next();
+				const tools = path === MCP_PATH;
+				if (!isWorkerPath(path) && !scheduled && !tools) return next();
 				(async () => {
 					const address = server.httpServer?.address();
 					if (apiBase === "" && address != null && typeof address === "object") apiBase = `http://${loopbackHost(address.address)}:${address.port}/_api`;
 					const request = await toRequest(req, `http://${req.headers.host ?? "localhost"}`);
+					request.headers.delete(CALLER_HEADER);
+					if (tools) {
+						if (!isLocalToolsRequest(request.headers)) {
+							await sendResponse(res, Response.json({
+								error: "local_tools_forbidden",
+								detail: "the local tools endpoint only answers `canopy mcp serve --local`"
+							}, { status: 403 }));
+							return;
+						}
+						request.headers.set(CALLER_HEADER, "agent");
+					}
 					const worker = await load();
 					const env = buildWorkerEnv(options, request, {
 						canopyFetch,

package/dist/docs/agent-tools.md

@@ -0,0 +1,213 @@
+---
+title: Agent tools (MCP)
+description: Let AI agents like Claude Code and Cursor use your project's backend as tools — as the person running them.
+---
+
+Your project's backend can offer **tools** to AI agents: Claude Code, Claude
+Desktop, Cursor, or any client that speaks MCP (the Model Context Protocol). A
+colleague adds one line to their agent and can then ask it to "list my open
+tickets" or "add a note", and the agent calls your backend to do it.
+
+The agent always acts as the signed-in Monk who runs it. It sees what they
+could see in the browser, nothing more, and your routes get the same
+`env.USER` as for that person's page.
+
+Tools need a backend (`worker/` in your project). Agents reach them through
+the `canopy` CLI on the user's own machine, so there is nothing public to
+secure.
+
+## Wrap the routes you already have
+
+Most projects already have the right routes. Point a tool at one:
+
+```ts title="worker/index.ts"
+import { mountMcpTools } from "@mediamonks/canopy/mcp";
+
+mountMcpTools(app, [
+  {
+    name: "list_notes",
+    description: "List the current user's notes, newest first",
+    route: "GET /api/notes",
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "get_note",
+    description: "Read one note",
+    route: "GET /api/notes/:id",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+    },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "create_note",
+    description: "Create a note",
+    route: "POST /api/notes",
+    inputSchema: {
+      type: "object",
+      properties: { title: { type: "string" }, body: { type: "string" } },
+      required: ["title"],
+    },
+  },
+]);
+```
+
+Deploy, and that's it. When an agent calls a tool, your route runs exactly as
+if the person had clicked a button in your app:
+
+- `:id`-style parts of the path are filled from the arguments of the same name.
+- For `GET` and `DELETE`, the other arguments become the query string. For
+  other methods they're sent as a JSON body.
+- A JSON response becomes the tool's result. An error response (say a 403)
+  comes back to the agent as a tool error with the status and body.
+
+The arguments are checked against `inputSchema` before your route runs, so a
+route never sees a call with a required field missing.
+
+## Write a tool directly
+
+When there's no route to wrap, give the tool a `handler`:
+
+```ts
+import { z } from "zod";
+
+mountMcpTools(app, [
+  {
+    name: "summarise_week",
+    description: "Summarise this week's activity for the caller",
+    inputSchema: z.object({ team: z.string().optional() }),
+    annotations: { readOnlyHint: true },
+    handler: async ({ team }, ctx) => {
+      // ctx.user is the signed-in Monk; ctx.env is your backend's env.
+      return { team: team ?? "all", user: ctx.user?.email };
+    },
+  },
+]);
+```
+
+Return an object (the agent gets it as structured data), a string, or throw an
+error to report a failure. The schema can be plain JSON Schema or anything
+that implements Standard Schema with JSON Schema output: Zod 4, Valibot (with
+`toStandardJsonSchema`) or ArkType.
+
+Tools are defined in the shape the MCP specification uses (`name`, `title`,
+`description`, `inputSchema`, `outputSchema`, `annotations`), so tools you
+wrote for another MCP server carry over as they are.
+
+### Vercel AI SDK tools
+
+A tool set you already use with the AI SDK works too. Put it in the same list:
+
+```ts
+import { tool } from "@ai-sdk/provider-utils";
+
+const aiTools = {
+  weather: tool({
+    description: "Weather in a city",
+    inputSchema: z.object({ city: z.string() }),
+    execute: async ({ city }) => ({ city, tempC: 21 }),
+  }),
+};
+
+mountMcpTools(app, [...myTools, aiTools]);
+```
+
+Import `tool` from `@ai-sdk/provider-utils` in a backend: the full `ai`
+package doesn't bundle for Canopy backends yet. Tools without `execute` (ones
+the AI provider runs itself) are left out.
+
+## Write good tools
+
+The agent reads your `description` to decide when to call a tool, and the
+schema to decide what to send. A few habits help a lot:
+
+- **Say what it does and when to use it.** "List the current user's notes,
+  newest first" beats "notes".
+- **Mark read-only tools** with `annotations: { readOnlyHint: true }`. Clients
+  may skip asking before calling those. Tools that aren't marked read-only are
+  treated as possibly destructive, so the agent asks the user first.
+- **Keep results small and to the point.** Return what the agent needs, not
+  your whole table.
+- **Don't trust the data blindly.** Text in your database was written by
+  people, and an agent reads it as instructions it might follow. Keep tools
+  that change or delete things narrow, and leave them unmarked so the user
+  confirms each call.
+
+## Connect your agent
+
+Anyone who can open the project in a browser can connect. For
+collaborators-only projects, that means collaborators only. From a terminal:
+
+```bash
+canopy mcp add <slug>
+```
+
+It checks you can use the project, says how many tools it has, and prints the
+line for your client:
+
+```bash
+claude mcp add canopy-notes -- canopy mcp serve notes --profile main
+```
+
+For Claude Desktop, Cursor and other clients it also prints an `mcpServers`
+JSON block. None of it contains a password or token: `canopy mcp serve` uses
+your `canopy login` and keeps its short-lived credentials in memory.
+
+When you redeploy with new or changed tools, a running agent session is told
+the list changed, and new sessions always see the current tools. You don't
+need to run anything again.
+
+## Develop tools locally
+
+Run `canopy dev` in your project, then point your agent at your working tree:
+
+```bash
+claude mcp add notes-local -- canopy mcp serve --local
+```
+
+The agent calls the tools in your local backend as you. Edit a tool, save, and
+the next listing shows the change.
+
+## Use your own MCP server
+
+`mountMcpTools` is built on the official MCP SDK
+(`@modelcontextprotocol/server`). If you'd rather use it directly, or another
+MCP library such as Vercel's `mcp-handler`, mount it at `MCP_PATH`:
+
+```ts
+import { McpServer, createMcpHandler } from "@modelcontextprotocol/server";
+import { MCP_PATH, mcpCaller } from "@mediamonks/canopy/mcp";
+
+const mcp = createMcpHandler(() => {
+  const server = new McpServer({ name: "notes", version: "1.0.0" });
+  // register your tools here
+  return server;
+});
+
+app.all(MCP_PATH, (c) => mcp.fetch(c.req.raw));
+```
+
+`mcpCaller(request, env)` tells you who is calling (`user`) and whether it's
+an agent (`agent`), in any route. Two limits apply to your own server:
+
+- It must answer on that single URL, using MCP's streamable HTTP transport.
+  The older SSE transport, which needs a second URL, doesn't work.
+- Agents only ever see its tools. Prompts, resources, and requests from your
+  server to the agent (sampling, roots, elicitation) are not passed on.
+
+## What agents can and can't do
+
+- They act as the person running them, with the same access that person has
+  in the browser. AI spend counts against your project's budget as usual.
+- They can only call your tools. They can't reach your app's pages or `/api/*`
+  routes directly, the dashboard, or other projects.
+- Their access ends when the person signs out (`canopy logout`, or "sign out
+  everywhere"), or loses access to a collaborators-only project.
+- Very long tool descriptions or schemas are held back, a project shows at
+  most 64 tools, results over 512 KB become an error, and a call stops after
+  60 seconds.
+- Agent calls show up in your backend's logs like any other request.
+
+See [canopy mcp](https://docs.canopy.website/cli/mcp) for every flag.

package/dist/docs/cli-mcp.md

@@ -0,0 +1,88 @@
+---
+title: canopy mcp
+description: Let AI agents use a project's backend as MCP tools — check access, print client config, and run the stdio server.
+---
+
+`canopy mcp` connects AI agents (Claude Code, Claude Desktop, Cursor, any MCP
+client) to a project's tools. The agent always acts as you. See
+[Agent tools](https://docs.canopy.website/guides/agent-tools) for how a project offers tools.
+
+## Usage
+
+```bash
+canopy mcp add [slug] [--channel staging]
+canopy mcp serve [slug] [--channel staging] [--local]
+```
+
+## canopy mcp add
+
+Checks that you're signed in and may open the project, reports how many tools
+it serves, and prints configuration for your client: a `claude mcp add` line
+for Claude Code, and an `mcpServers` JSON block for Claude Desktop, Cursor and
+others. It writes nothing; copy what you need.
+
+The printed command names the site (`--profile`) and, for staging, the
+channel, so it keeps working whatever your default site is. It contains no
+credentials.
+
+## canopy mcp serve
+
+The MCP server your client starts. It talks MCP on stdin/stdout and writes
+nothing else there, so everything it has to say goes to stderr, where clients
+show it as the server's log.
+
+It uses your `canopy login`: it exchanges it for short-lived credentials for
+this one project, keeps them in memory, and renews them as needed. If you're
+not signed in, it exits with a message telling you to run `canopy login`.
+
+Only the project's tools reach the agent, and the tool list stays current: a
+redeploy with new tools reaches a running session without restarting
+anything.
+
+## Arguments & flags
+
+- `slug` — the project. Defaults to the `canopy.json` in the current directory.
+- `--channel <live|staging>` — which channel's backend to use. Default `live`.
+- `--local` (serve only) — use the tools of the `canopy dev` running in the
+  current directory instead of the deployed project.
+- `--profile <id>` — which Canopy site, as for every command.
+
+## Examples
+
+```bash
+canopy mcp add notes
+```
+
+Check you can use `notes` and print its client configuration.
+
+```bash
+claude mcp add canopy-notes -- canopy mcp serve notes --profile main
+```
+
+Add `notes` to Claude Code (the line `canopy mcp add` printed).
+
+```bash
+claude mcp add notes-staging -- canopy mcp serve notes --channel staging --profile main
+```
+
+Try the staging channel's tools before promoting them.
+
+```bash
+claude mcp add notes-local -- canopy mcp serve --local
+```
+
+While developing: the tools from your working tree, served by `canopy dev`.
+
+## When it can't connect
+
+`canopy mcp add` and `canopy mcp serve` say what's wrong in plain words. The
+usual cases:
+
+- **Not signed in** — run `canopy login`.
+- **Limited to its collaborators** — ask the owner to add you.
+- **No backend, or serves no tools** — the project has no `worker/`, or it
+  doesn't mount any tools yet.
+- **Redeploy required** — the backend was deployed before tools existed. Run
+  `canopy deploy`.
+- **Invalid tool definitions** — two tools share a name, or a schema is wrong.
+  The message names the tool.

package/dist/docs/developers-agents-and-ai.md

@@ -64,6 +64,14 @@ already knows the rules:
   use `canopy dev --local` for an offline sandbox where writes never reach
   the platform.
 
+## Give agents your project's tools
+
+The other way round: your project can offer its backend to agents as MCP
+tools, so a colleague's Claude Code or Cursor can call it (as them) without
+opening the app. Wrap the routes you already have with `mountMcpTools`, deploy,
+and people connect with `canopy mcp add <slug>`. See
+[Agent tools](https://docs.canopy.website/guides/agent-tools).
+
 ## Prompts that work
 
 With the skill installed, these are safe, copy-pasteable asks — each maps to

package/dist/docs/index.json

@@ -67,6 +67,11 @@
           "title": "CI and deploy tokens",
           "summary": "Push-to-main deploys using a project-scoped deploy token."
         },
+        {
+          "slug": "agent-tools",
+          "title": "Agent tools (MCP)",
+          "summary": "Let AI agents like Claude Code and Cursor use your project's backend as tools — as the person running them."
+        },
         {
           "slug": "porting-nextjs",
           "title": "Porting a Next.js app",
@@ -286,6 +291,11 @@
           "title": "canopy feedback",
           "summary": "Read and triage a project's feedback inbox, or file a bug/feedback report — against a project or against Canopy itself."
         },
+        {
+          "slug": "cli-mcp",
+          "title": "canopy mcp",
+          "summary": "Let AI agents use a project's backend as MCP tools — check access, print client config, and run the stdio server."
+        },
         {
           "slug": "cli-open",
           "title": "canopy open",