@belvador/mcp 0.1.0 → 0.2.0

package/README.md

@@ -22,6 +22,10 @@ straight from `edge.belvador.dev` with short-lived tickets, so that data never p
   - macOS: `security add-generic-password -s belvador.dev -a mcp -w`
   - Linux: `secret-tool store --label=Belvador service belvador.dev account mcp`
 - **Toolsets**: `--toolsets=investigate,reliability,docs` (the default); the token's scopes narrow them further.
+  Add `configure` to change settings (`search_operations`, `describe_operation`, `plan_change`, `apply_change`,
+  `get_operation`); it needs a token with write scopes. Sensitive changes — keys, members, tokens, alert
+  destinations, node changes — answer `approval_required` with a belvador.dev link: a person approves with
+  their authenticator code, and new secrets are shown only to them, never to the agent.
 - **Untrusted data**: everything that came from your apps is returned under `untrusted`, cleaned and size-limited;
   the server's instructions tell the agent not to follow text inside it. No tool opens URLs found in data.
 - **Logs**: diagnostics go to stderr and never contain the token or tool results.

package/dist/cli.js

@@ -104,6 +104,7 @@ var API_ERROR_STATUS = {
   APPROVAL_EXPIRED: 410,
   APPROVAL_REJECTED: 403,
   APPROVAL_PARAMS_MISMATCH: 409,
+  APPROVAL_OUTCOME_UNKNOWN: 409,
   IDEMPOTENCY_KEY_REUSED: 422,
   IDEMPOTENCY_IN_PROGRESS: 409,
   PRECONDITION_REQUIRED: 428,
@@ -177,7 +178,7 @@ function cleanUntrustedText(raw, maxBytes = MCP_LIMITS.untrustedStringMaxBytes)
   const { text, cut } = cutUtf8(escaped, maxBytes);
   return { text, cut, suspicious };
 }
-var MCP_TOOLS_VERSION = 1;
+var MCP_TOOLS_VERSION = 2;
 var MCP_TOOLS = [
   { name: "get_workspace", toolset: "investigate", scope: "org:read", readOnly: true, destructive: false, idempotent: true },
   { name: "list_projects", toolset: "investigate", scope: "projects:read", readOnly: true, destructive: false, idempotent: true },
@@ -211,12 +212,7 @@ var MCP_TOOLS_PENDING = {
   release_health: "P15",
   list_incidents: "P9",
   get_incident: "P9",
-  get_coverage: "P10",
-  search_operations: "P7",
-  describe_operation: "P7",
-  plan_change: "P7",
-  apply_change: "P7",
-  get_operation: "P7"
+  get_coverage: "P10"
 };
 
 // ../src/shared/mcp/docs.ts
@@ -258,7 +254,7 @@ function docsFetcher(siteUrl, fetcher = fetch, now = () => Date.now()) {
 }
 
 // ../src/shared/mcp/server.ts
-import { McpServer } from "@modelcontextprotocol/server";
+import { CLIENT_CAPABILITIES_META_KEY, inputRequired, McpServer } from "@modelcontextprotocol/server";
 
 // ../src/shared/contracts/mcp-tools.ts
 import { z as z20 } from "zod";
@@ -2875,7 +2871,8 @@ var READ_INPUTS = {
   alertsList: list.extend({
     state: z18.enum(["open", "resolved", "all"]).default("all"),
     monitorId: uuid.optional()
-  })
+  }),
+  approvalsGet: z18.object({ workspaceId: uuid, approvalId: uuid })
 };
 var R = READ_INPUTS;
 var base = {
@@ -3055,6 +3052,16 @@ var READ_OPERATIONS = [
     paged: true,
     mcp: "investigate",
     summary: "Audit log, newest first (admins)."
+  }),
+  op({
+    ...base,
+    id: "approvals.get",
+    path: "/v1/approvals/{approval_id}",
+    scope: "org:read",
+    rpcs: ["api_read_approval"],
+    input: R.approvalsGet,
+    mcp: "configure",
+    summary: "State of an approval this token asked for (admins: any in the workspace): pending, approved, executed, rejected, expired or failed, with its result ids."
   })
 ];
 
@@ -3071,13 +3078,267 @@ var BY_ID = new Map(API_OPERATIONS.map((o) => [o.id, o]));
 function apiOperation(id) {
   return BY_ID.get(id);
 }
+function pathParams(path) {
+  return [...path.matchAll(/\{([a-z_]+)\}/g)].map((m) => m[1]);
+}
+
+// ../src/shared/contracts/approvals.ts
+var APPROVAL_STATES = ["pending", "approved", "executed", "rejected", "expired", "failed"];
+var APPROVAL_LIMITS = {
+  ttlMinutes: 15,
+  stepUpMaxAgeSeconds: 600,
+  pendingPerWorkspace: 20,
+  paramsMaxBytes: 16 * 1024,
+  decisionNoteMax: 500,
+  notifyMaxRecipients: 10
+};
+var APPROVAL_APPROVER = {
+  "projects.set_checkin_auth": "admin",
+  "projects.schedule_deletion": "admin",
+  "project_keys.create": "member",
+  "project_keys.rotate": "member",
+  "project_keys.revoke": "member",
+  "upload_tokens.create": "member",
+  "upload_tokens.revoke": "member",
+  "ingest_keys.create": "admin",
+  "ingest_keys.revoke": "admin",
+  "ping_tokens.rotate": "admin",
+  "ping_tokens.revoke_previous": "admin",
+  "ping_tokens.reset": "admin",
+  "destinations.create": "admin",
+  "destinations.update": "admin",
+  "destinations.update_connection": "admin",
+  "destinations.delete": "admin",
+  "destinations.set_recipients": "admin",
+  "members.change_role": "admin",
+  "members.remove": "admin",
+  "invites.create": "admin",
+  "tokens.create_personal": "self",
+  "tokens.create_service": "admin",
+  "tokens.set_policy": "admin",
+  "service_principals.create": "admin",
+  "service_principals.update": "admin",
+  "node.provision": "admin",
+  "node.resize": "admin",
+  "node.schedule_deletion": "owner",
+  "node.set_backup_custody": "owner",
+  "node.rebuild": "owner",
+  "node.submit_recovery_kit": "owner"
+};
+var APPROVAL_HUMAN_FIELDS = {
+  "projects.schedule_deletion": ["confirmSlug"],
+  "node.schedule_deletion": ["confirmName"],
+  "node.rebuild": ["confirmName"]
+};
+var APPROVAL_SETUP_OPS = ["destinations.create", "destinations.update_connection"];
+function approvalRequestSchema(operationId, input) {
+  const human = APPROVAL_HUMAN_FIELDS[operationId] ?? [];
+  if (!human.length)
+    return input;
+  return input.omit(Object.fromEntries(human.map((k) => [k, true])));
+}
 
 // ../src/shared/contracts/api-ops/wire.ts
 import { z as z19 } from "zod";
 var toSnake = (s) => s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+var toCamel = (s) => s.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
 var schemaCache = new WeakMap;
+function inputJsonSchema(op) {
+  let js = schemaCache.get(op.input);
+  if (!js) {
+    js = z19.toJSONSchema(op.input, { io: "input", unrepresentable: "any" });
+    schemaCache.set(op.input, js);
+  }
+  return js;
+}
+function variants(js) {
+  return [js, ...js.anyOf ?? [], ...js.oneOf ?? [], ...js.allOf ?? []];
+}
+function propertyMap(js) {
+  const out = new Map;
+  if (!js)
+    return out;
+  for (const v of variants(js)) {
+    for (const [name, schema] of Object.entries(v.properties ?? {}))
+      out.set(toSnake(name), { name, schema });
+  }
+  return out;
+}
+function itemSchema(js) {
+  if (!js)
+    return;
+  for (const v of variants(js)) {
+    if (v.items && !Array.isArray(v.items))
+      return v.items;
+  }
+  return;
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function camelize(value, js) {
+  if (Array.isArray(value))
+    return value.map((v) => camelize(v, itemSchema(js)));
+  if (!isPlainObject(value))
+    return value;
+  const props = propertyMap(js);
+  if (props.size === 0)
+    return value;
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    const p = props.get(k);
+    out[p ? p.name : k] = p ? camelize(v, p.schema) : v;
+  }
+  return out;
+}
+function snakeSchema(js, drop = []) {
+  const out = { ...js };
+  if (js.properties) {
+    out.properties = Object.fromEntries(Object.entries(js.properties).filter(([k]) => !drop.includes(k)).map(([k, v]) => [toSnake(k), snakeSchema(v)]));
+    if (js.required)
+      out.required = js.required.filter((k) => !drop.includes(k)).map(toSnake);
+    if (out.required && !out.required.length)
+      delete out.required;
+  }
+  if (js.items && !Array.isArray(js.items))
+    out.items = snakeSchema(js.items);
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    if (js[key])
+      out[key] = js[key].map((v) => snakeSchema(v, drop));
+  }
+  if (isPlainObject(js.additionalProperties))
+    out.additionalProperties = snakeSchema(js.additionalProperties);
+  return out;
+}
+function scalarType(js) {
+  if (!js)
+    return;
+  for (const v of variants(js)) {
+    const t = Array.isArray(v.type) ? v.type.find((x) => x !== "null") : v.type;
+    if (t)
+      return t;
+  }
+  return;
+}
+function coerce(raw, js) {
+  const t = scalarType(js);
+  if ((t === "integer" || t === "number") && /^-?\d+(\.\d+)?$/.test(raw))
+    return Number(raw);
+  if (t === "boolean" && (raw === "true" || raw === "false"))
+    return raw === "true";
+  return raw;
+}
+function buildOpInput(op, req, workspaceId) {
+  const js = inputJsonSchema(op);
+  const top = propertyMap(js);
+  const out = {};
+  const nested = {};
+  const bodyKey = op.bodyField ? toSnake(op.bodyField) : null;
+  const body = isPlainObject(req.body) ? req.body : req.body === undefined || req.body === null ? {} : null;
+  if (body === null) {
+    out["__invalidBody"] = true;
+    return out;
+  }
+  for (const [k, v] of Object.entries(body)) {
+    const p = top.get(k);
+    if (p && k !== bodyKey)
+      out[p.name] = camelize(v, p.schema);
+    else if (bodyKey)
+      nested[k] = v;
+    else
+      out[k] = v;
+  }
+  if (op.bodyField)
+    out[op.bodyField] = camelize(nested, top.get(bodyKey)?.schema);
+  for (const [k, raw] of Object.entries(req.query)) {
+    const p = top.get(k);
+    if (p)
+      out[p.name] = coerce(raw, p.schema);
+  }
+  for (const name of pathParams(op.path)) {
+    const p = top.get(name);
+    const raw = req.path[name];
+    if (p && raw !== undefined)
+      out[p.name] = coerce(raw, p.schema);
+  }
+  if (op.workspace)
+    out["workspaceId"] = workspaceId;
+  return out;
+}
+function wirePointer(op, path) {
+  const segs = path.map((p) => typeof p === "string" ? toSnake(p) : String(p));
+  if (op.bodyField && segs[0] === toSnake(op.bodyField))
+    segs.shift();
+  return `/${segs.map((s) => s.replace(/~/g, "~0").replace(/\//g, "~1")).join("/")}`;
+}
+
+// ../src/shared/contracts/api-ops/openapi.ts
+function clean(js) {
+  const { $schema: _drop, ...rest } = js;
+  return rest;
+}
+function propertyOf(js, camel) {
+  return clean(snakeSchema(js.properties?.[camel] ?? {}));
+}
+function requestSchema(op) {
+  const js = inputJsonSchema(op);
+  const path = pathParams(op.path).map(toCamel);
+  const drop = ["workspaceId", ...path];
+  if (!op.bodyField) {
+    const s = clean(snakeSchema(js, drop));
+    return s.properties && Object.keys(s.properties).length === 0 && !s.anyOf && !s.oneOf ? null : s;
+  }
+  const outer = clean(snakeSchema(js, [...drop, op.bodyField]));
+  const inner = clean(snakeSchema(js.properties?.[op.bodyField] ?? {}));
+  if (!inner.properties)
+    return { allOf: [outer, inner] };
+  return {
+    ...inner,
+    properties: { ...outer.properties ?? {}, ...inner.properties },
+    required: [...outer.required ?? [], ...inner.required ?? []]
+  };
+}
+function operationArgsSchema(op, drop = []) {
+  const js = inputJsonSchema(op);
+  const path = pathParams(op.path);
+  const pathProps = Object.fromEntries(path.map((n) => [n, propertyOf(js, toCamel(n))]));
+  const rest = op.method === "GET" ? (() => {
+    const s = clean(snakeSchema(js, ["workspaceId", ...path.map(toCamel)]));
+    return { ...s, required: [] };
+  })() : requestSchema(op);
+  if (rest && !rest.properties) {
+    return { type: "object", properties: pathProps, required: path, allOf: [rest] };
+  }
+  const props = { ...pathProps, ...rest?.properties ?? {} };
+  for (const d of drop)
+    delete props[d];
+  const required = [...path, ...rest?.required ?? []].filter((k) => !drop.includes(k));
+  return {
+    type: "object",
+    properties: props,
+    ...required.length ? { required: [...new Set(required)] } : {},
+    additionalProperties: false
+  };
+}
 
 // ../src/shared/contracts/mcp-tools.ts
+function wireFromArgs(op, args) {
+  const names = new Set(pathParams(op.path));
+  const path = {};
+  const query = {};
+  const body = {};
+  for (const [k, v] of Object.entries(args)) {
+    if (v === undefined || v === null)
+      continue;
+    if (names.has(k))
+      path[k] = String(v);
+    else if (op.method === "GET")
+      query[k] = typeof v === "string" ? v : JSON.stringify(v);
+    else
+      body[k] = v;
+  }
+  return { path, query, body: op.method === "GET" ? undefined : body };
+}
 function wireInput(operationId, opts = {}) {
   const op = apiOperation(operationId);
   if (!op)
@@ -3198,6 +3459,19 @@ var TOOL_OUTPUT_SCHEMA = z20.object({
     detail: z20.string().optional(),
     scope: z20.string().optional(),
     retry_after: z20.number().optional()
+  }).optional(),
+  operations: z20.array(z20.record(z20.string(), z20.unknown())).optional(),
+  operation: z20.record(z20.string(), z20.unknown()).optional(),
+  plan: z20.record(z20.string(), z20.unknown()).optional(),
+  status: z20.enum(["done", "approval_required", "approval_pending", ...APPROVAL_STATES]).optional(),
+  approval: z20.object({
+    approval_id: z20.string(),
+    approval_url: z20.string(),
+    expires_at: z20.string(),
+    state: z20.enum(APPROVAL_STATES),
+    result_code: z20.string().nullable().optional(),
+    result: z20.record(z20.string(), z20.unknown()).optional(),
+    next: z20.string().optional()
   }).optional()
 });
 var spec = (name) => {
@@ -3252,6 +3526,79 @@ var MONITOR_KINDS2 = {
   uptime: { list: "uptime.list", get: "uptime.get", idField: "check_id" },
   slo: { list: "slos.list", get: "slos.get", idField: "slo_id" }
 };
+var DESTRUCTIVE_VERBS = new Set([
+  "delete",
+  "revoke",
+  "remove",
+  "schedule_deletion",
+  "rotate",
+  "reset",
+  "revoke_previous",
+  "rebuild",
+  "change_role"
+]);
+function configureOperations() {
+  return API_OPERATIONS.filter((o) => o.mcp === "configure");
+}
+function configureOp(id) {
+  if (typeof id !== "string")
+    return null;
+  const op = apiOperation(id);
+  return op && op.mcp === "configure" ? op : null;
+}
+function isDestructiveOperation(op) {
+  return op.method === "DELETE" || DESTRUCTIVE_VERBS.has(op.id.slice(op.id.indexOf(".") + 1));
+}
+var humanWire = (op) => (APPROVAL_HUMAN_FIELDS[op.id] ?? []).map(toSnake);
+function resourceRead(op) {
+  if (op.method === "GET")
+    return null;
+  return API_OPERATIONS.find((o) => o.method === "GET" && o.path === op.path && o.kind !== "node") ?? null;
+}
+var PLACEHOLDER_WS = "00000000-0000-0000-0000-000000000000";
+function validateConfigure(op, params) {
+  for (const f of humanWire(op))
+    if (f in params)
+      return { ok: false, errors: [{ pointer: `/${f}`, code: "typed_by_approver" }] };
+  const input = buildOpInput(op, wireFromArgs(op, params), PLACEHOLDER_WS);
+  if (input["__invalidBody"])
+    return { ok: false, errors: [{ pointer: "", code: "object_expected" }] };
+  const schema = op.sensitivity === "approval" ? approvalRequestSchema(op.id, op.input) : op.input;
+  const r = schema.safeParse(input);
+  if (r.success)
+    return { ok: true };
+  return {
+    ok: false,
+    errors: r.error.issues.slice(0, 20).map((i) => ({ pointer: wirePointer(op, i.path), code: i.code }))
+  };
+}
+function describe(op, scopes) {
+  return {
+    operation_id: op.id,
+    summary: op.summary,
+    method: op.method,
+    path: op.path,
+    scope: op.scope,
+    scope_held: scopes.includes(op.scope),
+    requires_approval: op.sensitivity === "approval",
+    destructive: isDestructiveOperation(op)
+  };
+}
+var params = z20.record(z20.string(), z20.unknown()).default({}).describe("Operation fields in wire names (snake_case), as describe_operation's args_schema shows.");
+var operationIdArg = z20.string().min(3).max(80).describe("An operation id from search_operations, e.g. `monitors.update`.");
+function approvalBlock(t, next) {
+  return {
+    approval_id: t.approval_id,
+    approval_url: t.approval_url,
+    expires_at: t.expires_at,
+    state: t.state,
+    ...t.result_code !== undefined ? { result_code: t.result_code } : {},
+    ...t.result !== undefined ? { result: t.result } : {},
+    next
+  };
+}
+var NEXT_PENDING = "A person with the right role must approve this on belvador.dev (open approval_url; it needs their authenticator code). Nothing has changed yet. Show the link to the user, then call get_operation with approval_id, or apply_change again with the same idempotency_key to get the result.";
+var NEXT_SETUP = "The approving person also types the secret (bot token, webhook URL, password) on that page; it never passes through the agent.";
 var MCP_TOOL_DEFS = [
   {
     ...spec("get_workspace"),
@@ -3442,6 +3789,189 @@ var MCP_TOOL_DEFS = [
       return wrapResult({ data: r.body, operations: ["projects.send_test_event"], source: "control_plane" });
     }
   },
+  {
+    ...spec("search_operations"),
+    title: "Find a configuration change",
+    description: "Searches what this token can change in its Belvador workspace: projects, keys and tokens, monitors, uptime checks, SLOs, alert rules and destinations, members, service accounts and the node. Returns operation ids for describe_operation and plan_change, whether a person must approve the change, and whether this token holds the scope.",
+    operations: [],
+    input: z20.object({
+      query: z20.string().min(1).max(200).describe("Words such as `rotate dsn key`, `heartbeat monitor`, `slack alert`."),
+      limit: z20.number().int().min(1).max(20).default(10)
+    }),
+    async run(args, rt) {
+      const q = words(String(args["query"]));
+      const scored = configureOperations().filter((o) => o.method !== "GET").map((o) => {
+        const id = words(o.id.replace(/[._]/g, " "));
+        const rest = words(`${o.summary} ${o.path}`);
+        let score = 0;
+        for (const w of q) {
+          if (id.some((t) => t === w))
+            score += 4;
+          else if (id.some((t) => t.startsWith(w)))
+            score += 2;
+          if (rest.some((t) => t === w))
+            score += 2;
+          else if (rest.some((t) => t.startsWith(w)))
+            score += 1;
+        }
+        return { o, score };
+      }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score || a.o.id.localeCompare(b.o.id)).slice(0, Number(args["limit"] ?? 10));
+      return { structuredContent: { operations: scored.map((x) => describe(x.o, rt.scopes)) } };
+    }
+  },
+  {
+    ...spec("describe_operation"),
+    title: "Describe a configuration change",
+    description: "Everything needed to call one operation: its fields (JSON Schema, wire names), the scope, whether it needs If-Match (call plan_change for the current ETag), an idempotency key, or a person's approval, and which fields the approving person types on belvador.dev instead of the agent.",
+    operations: [],
+    input: z20.object({ operation_id: operationIdArg }),
+    async run(args, rt) {
+      const op = configureOp(args["operation_id"]);
+      if (!op || op.method === "GET")
+        return errorResult({ ok: false, status: 404, code: "NOT_FOUND" });
+      const approval = op.sensitivity === "approval";
+      return {
+        structuredContent: {
+          operation: {
+            ...describe(op, rt.scopes),
+            idempotency: op.idempotency,
+            if_match_required: !!op.ifMatch,
+            args_schema: operationArgsSchema(op, humanWire(op)),
+            ...approval ? {
+              approver: APPROVAL_APPROVER[op.id] ?? "admin",
+              typed_by_approver: humanWire(op),
+              secrets_typed_by_approver: APPROVAL_SETUP_OPS.includes(op.id)
+            } : {},
+            ...op.secretOutput?.length ? { secret_output: [...op.secretOutput] } : {}
+          }
+        }
+      };
+    }
+  },
+  {
+    ...spec("plan_change"),
+    title: "Check a change before applying it",
+    description: "Validates params for one operation without changing anything: field errors, missing scope, whether a person must approve, and — when the resource can be read — its current state, the fields that would change and the ETag to pass as if_match.",
+    operations: [],
+    input: z20.object({ operation_id: operationIdArg, params }),
+    async run(args, rt) {
+      const op = configureOp(args["operation_id"]);
+      if (!op || op.method === "GET")
+        return errorResult({ ok: false, status: 404, code: "NOT_FOUND" });
+      const p = args["params"] ?? {};
+      const v = validateConfigure(op, p);
+      const scopeMissing = rt.scopes.includes(op.scope) ? [] : [op.scope];
+      let etag = null;
+      let current = undefined;
+      const read = resourceRead(op);
+      const ids = read ? Object.fromEntries(pathParams(read.path).map((n) => [n, p[n]])) : {};
+      if (read && rt.scopes.includes(read.scope) && Object.values(ids).every((x) => x != null && x !== "")) {
+        const r = await rt.call(read.id, ids);
+        if (r.ok) {
+          etag = r.etag ?? null;
+          current = r.body;
+        }
+      }
+      const changes = Object.entries(p).filter(([k]) => !pathParams(op.path).includes(k)).map(([field, to]) => {
+        const cur = current && typeof current === "object" && !Array.isArray(current) ? current : null;
+        return cur && field in cur ? { field, from: cur[field], to } : { field, to };
+      });
+      const plan = {
+        operation_id: op.id,
+        valid: v.ok,
+        ...v.ok ? {} : { errors: v.errors },
+        scope: op.scope,
+        scope_missing: scopeMissing,
+        requires_approval: op.sensitivity === "approval",
+        ...op.sensitivity === "approval" ? { approver: APPROVAL_APPROVER[op.id] ?? "admin" } : {},
+        destructive: isDestructiveOperation(op),
+        idempotency: op.idempotency,
+        if_match_required: !!op.ifMatch,
+        etag
+      };
+      const out = wrapResult({
+        data: { changes, ...current !== undefined ? { current } : {} },
+        operations: read && current !== undefined ? [read.id] : [],
+        source: "control_plane"
+      });
+      return { structuredContent: { plan, ...out.structuredContent } };
+    }
+  },
+  {
+    ...spec("apply_change"),
+    title: "Apply a configuration change",
+    description: "Runs one operation with params (validate first with plan_change). Always send idempotency_key: repeating a call with the same key never applies it twice. Sensitive operations answer approval_required with an approval_url a person opens on belvador.dev; nothing changes until they approve with their authenticator code.",
+    operations: [],
+    input: z20.object({
+      operation_id: operationIdArg,
+      params,
+      idempotency_key: z20.string().min(8).max(255).describe("Unique per change; reuse it to retry or to fetch the result."),
+      if_match: z20.string().max(200).optional().describe("ETag from plan_change, for operations that need it.")
+    }),
+    async run(args, rt) {
+      const op = configureOp(args["operation_id"]);
+      if (!op || op.method === "GET")
+        return errorResult({ ok: false, status: 404, code: "NOT_FOUND" });
+      const p = args["params"] ?? {};
+      for (const f of humanWire(op))
+        if (f in p)
+          return errorResult({ ok: false, status: 400, code: "INVALID_INPUT", detail: `${f} is typed by the approving person` });
+      const opts = { idempotencyKey: String(args["idempotency_key"]) };
+      if (typeof args["if_match"] === "string" && args["if_match"])
+        opts.ifMatch = args["if_match"];
+      const r = await rt.call(op.id, p, opts);
+      if (r.ok) {
+        const body = r.body;
+        if (op.sensitivity === "approval" && body && typeof body["approval_id"] === "string") {
+          return {
+            structuredContent: {
+              status: "executed",
+              approval: approvalBlock(body, "Approved and run once by a person; result holds the ids.")
+            }
+          };
+        }
+        const out = wrapResult({ data: r.body, operations: [op.id], source: sourceOf(op.id) });
+        return { structuredContent: { status: "done", ...out.structuredContent } };
+      }
+      if (r.approval && r.approval.state === "pending") {
+        const next = APPROVAL_SETUP_OPS.includes(op.id) ? `${NEXT_PENDING} ${NEXT_SETUP}` : NEXT_PENDING;
+        return {
+          structuredContent: { status: "approval_required", approval: approvalBlock(r.approval, next) },
+          approval: r.approval
+        };
+      }
+      if (r.approval) {
+        return {
+          isError: true,
+          structuredContent: {
+            ...errorResult(r).structuredContent,
+            approval: approvalBlock(r.approval, "This request is closed; send a new one with a new idempotency_key if the change is still wanted.")
+          }
+        };
+      }
+      return errorResult(r);
+    }
+  },
+  {
+    ...spec("get_operation"),
+    title: "Follow an approval",
+    description: "State of a change waiting for a person's approval: pending, approved, executed (with the ids it produced), rejected, expired or failed (with the error code).",
+    operations: ["approvals.get"],
+    input: z20.object({ approval_id: z20.guid().describe("approval_id from apply_change.") }),
+    async run(args, rt) {
+      const r = await rt.call("approvals.get", { approval_id: args["approval_id"] });
+      if (!r.ok)
+        return errorResult(r);
+      const b = r.body;
+      const next = b.state === "pending" ? NEXT_PENDING : b.state === "executed" ? "Done: the change ran once." : b.state === "approved" ? "Approved; the change is running or waits for the person to finish the form." : "Closed without a change.";
+      return {
+        structuredContent: {
+          status: b.state,
+          approval: approvalBlock({ ...b, approval_url: b.approval_url ?? "" }, next)
+        }
+      };
+    }
+  },
   {
     ...spec("search_docs"),
     title: "Search Belvador docs",
@@ -3542,6 +4072,12 @@ function toolsFor(toolsets, scopes) {
 
 // ../src/shared/mcp/server.ts
 var MCP_SERVER_VERSION = `1.${MCP_TOOLS_VERSION}.0`;
+var APPROVAL_ELICIT_MESSAGE = "Belvador needs a person to approve this change. Open the link, review it and confirm with your authenticator code; then the agent continues.";
+function wantsApprovalLink(ctx) {
+  const env = ctx?.mcpReq.envelope;
+  const caps = env?.[CLIENT_CAPABILITIES_META_KEY];
+  return !!caps?.elicitation?.url && !ctx?.mcpReq.inputResponses?.["approval"];
+}
 function buildMcpServer(rt, toolsets) {
   const server = new McpServer({ name: "belvador", title: "Belvador", version: MCP_SERVER_VERSION }, { instructions: MCP_SERVER_INSTRUCTIONS });
   for (const t of toolsFor([...toolsets], rt.scopes)) {
@@ -3557,8 +4093,15 @@ function buildMcpServer(rt, toolsets) {
         idempotentHint: t.idempotent,
         openWorldHint: false
       }
-    }, async (args) => {
+    }, async (args, ctx) => {
       const r = await t.run(args, rt);
+      if (r.approval && r.approval.state === "pending" && wantsApprovalLink(ctx)) {
+        return inputRequired({
+          inputRequests: {
+            approval: inputRequired.elicitUrl({ message: APPROVAL_ELICIT_MESSAGE, url: r.approval.approval_url })
+          }
+        });
+      }
       return {
         content: [{ type: "text", text: JSON.stringify(r.structuredContent) }],
         structuredContent: r.structuredContent,
@@ -3579,7 +4122,15 @@ function outcomeOfError(e) {
       code: e.code === "ABORTED" ? "UNAVAILABLE" : e.code,
       ...e.detail ? { detail: e.detail } : {},
       ...e.scope ? { scope: e.scope } : {},
-      ...e.retryAfter ? { retryAfter: e.retryAfter } : {}
+      ...e.retryAfter ? { retryAfter: e.retryAfter } : {},
+      ...e.approval ? {
+        approval: {
+          approval_id: e.approval.id,
+          approval_url: e.approval.url,
+          expires_at: e.approval.expiresAt,
+          state: e.approval.state
+        }
+      } : {}
     };
   return { ok: false, status: 503, code: "UNAVAILABLE" };
 }
@@ -3591,8 +4142,13 @@ function clientRuntime(client, scopes, docs) {
     async call(operationId, args, opts) {
       try {
         const call = client.call.bind(client);
-        const r = await call(operationId, args, opts?.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {});
-        return { ok: true, status: r.status, body: r.data };
+        const o = {};
+        if (opts?.idempotencyKey)
+          o.idempotencyKey = opts.idempotencyKey;
+        if (opts?.ifMatch)
+          o.ifMatch = opts.ifMatch;
+        const r = await call(operationId, args, o);
+        return { ok: true, status: r.status, body: r.data, etag: r.etag };
       } catch (e) {
         return outcomeOfError(e);
       }
@@ -3624,7 +4180,7 @@ function findToken(env = process.env, keychain = keychainToken) {
 }
 
 // packages/mcp/src/cli.ts
-var PACKAGE_VERSION = "0.1.0";
+var PACKAGE_VERSION = "0.2.0";
 var HELP = `belvador-mcp ${PACKAGE_VERSION} — Belvador MCP server (stdio)
 
 Usage: npx -y @belvador/mcp [--toolsets=${MCP_DEFAULT_TOOLSETS.join(",")}]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Belvador MCP server over stdio: the same read-only tools as api.belvador.dev/mcp (issues, events, traces, logs, monitors, docs), with node data read straight from the edge.",
   "license": "MIT",
   "author": "Belvador (https://belvador.dev)",
@@ -30,7 +30,7 @@
     "node": ">=20.10"
   },
   "dependencies": {
-    "@belvador/api": "0.1.0",
+    "@belvador/api": "0.2.0",
     "@modelcontextprotocol/server": "2.4.0",
     "zod": "4.6.7"
   },