@mediamonks/canopy-cli 0.7.30 → 0.7.32

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-Ka2lHkyy.mjs}

@@ -1,6 +1,8 @@
 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 { builtinModules } from "node:module";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -26,6 +28,7 @@ async function bundleWorker(projectDir, entry) {
 			format: "esm",
 			target: "es2022",
 			packages: "bundle",
+			plugins: [nodeBuiltins],
 			logLevel: "silent"
 		});
 		return new Uint8Array(readFileSync(outfile));
@@ -36,6 +39,115 @@ async function bundleWorker(projectDir, entry) {
 		});
 	}
 }
+/** Bare names Node resolves to a built-in (`fs`, `fs/promises`, …). */
+const BARE_BUILTINS = new Set(builtinModules.filter((name) => !name.startsWith("_")));
+/**
+* Built-ins both hosts provide, each with a default export: Node, and workerd
+* at the dispatch scripts' compatibility date (2026-05-01, nodejs_compat —
+* probed with a worker importing every one; several are stubs that throw only
+* when called). Missing on workerd: `sea`, `test/reporters`. Left out on
+* purpose: `sqlite` (experimental on Node) and `test`.
+*/
+const HOSTED_BUILTINS = /* @__PURE__ */ new Set([
+	"assert",
+	"assert/strict",
+	"async_hooks",
+	"buffer",
+	"child_process",
+	"cluster",
+	"console",
+	"constants",
+	"crypto",
+	"dgram",
+	"diagnostics_channel",
+	"dns",
+	"dns/promises",
+	"domain",
+	"events",
+	"fs",
+	"fs/promises",
+	"http",
+	"http2",
+	"https",
+	"inspector",
+	"inspector/promises",
+	"module",
+	"net",
+	"os",
+	"path",
+	"path/posix",
+	"path/win32",
+	"perf_hooks",
+	"process",
+	"punycode",
+	"querystring",
+	"readline",
+	"readline/promises",
+	"repl",
+	"stream",
+	"stream/consumers",
+	"stream/promises",
+	"stream/web",
+	"string_decoder",
+	"sys",
+	"timers",
+	"timers/promises",
+	"tls",
+	"trace_events",
+	"tty",
+	"url",
+	"util",
+	"util/types",
+	"v8",
+	"vm",
+	"wasi",
+	"worker_threads",
+	"zlib"
+]);
+const REQUIRE_NAMESPACE = "canopy-node-require";
+/**
+* Node built-ins are the host's, not the bundle's: the GCP runtime is Node and
+* Cloudflare dispatch scripts run with nodejs_compat. A `neutral` build cannot
+* resolve them at all, so every import of one — `node:fs` or bare `fs`, as Node
+* itself treats them — stays external under its `node:` name.
+*
+* A CommonJS `require()` of one cannot simply stay external: in an ESM bundle
+* esbuild turns it into a `__require` shim that throws "Dynamic require of …
+* is not supported" when it runs. Neither host offers a `require` to an ES
+* module, so the call is routed to a tiny ES module that re-exports the
+* built-in through a static `import`. The AI SDK needs this: `ai` reaches
+* `@vercel/oidc`, whose CommonJS build requires `fs`, `os` and `path` at load.
+*
+* That turns a lazy require — often an optional one in a try/catch — into an
+* import made at load, and Cloudflare refuses a script importing a module it
+* lacks. So only HOSTED_BUILTINS are rewritten; a require of any other
+* built-in keeps the throwing shim, which fails only if that line runs.
+*/
+const nodeBuiltins = {
+	name: "canopy-node-builtins",
+	setup(build) {
+		build.onResolve({ filter: /^(node:)?[a-z_][a-z0-9_/]*$/ }, (args) => {
+			const prefixed = args.path.startsWith("node:");
+			const name = prefixed ? args.path.slice(5) : args.path;
+			if (!prefixed && !BARE_BUILTINS.has(name)) return void 0;
+			if (args.kind === "require-call" && HOSTED_BUILTINS.has(name)) return {
+				path: name,
+				namespace: REQUIRE_NAMESPACE
+			};
+			return {
+				path: `node:${name}`,
+				external: true
+			};
+		});
+		build.onLoad({
+			filter: /.*/,
+			namespace: REQUIRE_NAMESPACE
+		}, (args) => ({
+			contents: `export * from "node:${args.path}";\nexport { default } from "node:${args.path}";\n`,
+			loader: "js"
+		}));
+	}
+};
 //#endregion
 //#region src/deploy.ts
 /**

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,212 @@
+---
+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";
+
+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]);
+```
+
+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 the [SDK reference](https://docs.canopy.website/sdk/mcp) for every option and [canopy mcp](https://docs.canopy.website/cli/mcp)
+for every flag.