@cursor/july 0.1.9 → 0.1.11

package/src/bin/agent-serve.ts

@@ -51,7 +51,10 @@ import {
   cmdStop,
   type DeployCliOptions,
 } from "../internal/cli-deploy.js";
-import { CLI_COMMAND_NAME as CLI } from "../internal/distribution.js";
+import {
+  CLI_COMMAND_NAME as CLI,
+  packageVersion,
+} from "../internal/distribution.js";
 import { clearTerminal, stdoutPalette } from "../internal/terminal-style.js";
 import { cmdUpdate, warnIfOutdated } from "../internal/update-check.js";
 import type { AgentProject, AgentServeHandle } from "../types.js";
@@ -93,6 +96,7 @@ Usage:
                           | --url <baseUrl> [--bearer-token <t>]
   ${CLI} mcp install [--name <serverName>] [--print] [--json]
                           (same target flags as mcp)
+  ${CLI} mcp oauth   <connection> [--dir <path>] [--store] [--slug <slug>]
   ${CLI} eval        [--dir <path>] [evalId...] [--list] [--json]
                           [--tag <tag>]... [--verbose] [--timeout-ms <n>]
                           [--no-stream] [--no-wait]
@@ -106,6 +110,7 @@ Usage:
   ${CLI} logout
   ${CLI} whoami      [--json]
   ${CLI} update
+  ${CLI} version
   ${CLI} deploy      [--dir <path>] [--slug <slug> | --all] [--team <id>] [--json]
                           [--no-wait] [--repo <url>] [--ref <ref>]
                           [--path <agentPath>] [--cursor-events-repo <owner/name>]...
@@ -170,7 +175,9 @@ Commands:
               --url targets a running server. stdout is reserved for the
               MCP wire. \`mcp install\` writes the matching entry into
               ~/.cursor/mcp.json (--print to preview; --name to override
-              the server name).
+              the server name). \`mcp oauth <connection>\` runs host PKCE
+              for defineConnection({ url, oauth: true }); \`--store\` upserts
+              MCP_OAUTH_<NAME>_* secrets on the hosted deployment.
   eval        Run filesystem evals under evals/**/*.eval.ts (streams on a TTY).
               Default: ephemeral local harness against evals on disk. Pass
               --prod to kick off the batch on the team's hosted deployment
@@ -194,6 +201,7 @@ Commands:
   whoami      Show which Cursor account powers this host (and why).
   update      Upgrade this install to the latest published version (detects
               global npm/pnpm/yarn/bun installs and project dependencies).
+  version     Print the installed ${CLI} version and exit (also --version / -V).
   deploy      Deploy onto Cursor's managed agent-serve hosting, then wait for
               the engine to come up. --repo/--ref/--path stay available;
               inside an agent git checkout they are inferred when omitted
@@ -224,6 +232,7 @@ Agent loop:
   ${CLI} dev .
 
 Options:
+  --version, -V      Print the installed version and exit.
   --dir             Project root (defaults to the current directory).
   --port             Port to listen on (default 3000).
   --host             Host to bind (default 127.0.0.1).
@@ -247,6 +256,11 @@ Options:
                      githubChannel({ cursorAccount }). Admitted callers can drive
                      sessions holding the account's repo-scoped GitHub credential,
                      so use only behind a trusted boundary (e.g. an SSO proxy).
+  --allow-anonymous-cursor-account-mcp
+                     serve: allow --allow-anonymous together with
+                     defineConnection({ cursorAccount: true }). Admitted callers
+                     can drive the account's MCP connectors, so use only behind
+                     a trusted boundary (e.g. an SSO proxy or hosted alias token).
   --public-url       serve: base URL where this host is reachable from outside
                      (e.g. https://agent-serve.example.com). Required for peer
                      connections (defineConnection({ agent })) on cloud-runtime
@@ -349,6 +363,10 @@ async function main(argv: string[]): Promise<number> {
     process.stdout.write(HELP);
     return command === undefined ? 1 : 0;
   }
+  if (command === "version" || command === "--version" || command === "-V") {
+    process.stdout.write(`${CLI} ${packageVersion()}\n`);
+    return 0;
+  }
 
   // `session --events` means "dump raw events" (boolean). Rewrite so it does
   // not collide with run/trajectory's `--events <file.ndjson>` string flag.
@@ -372,6 +390,7 @@ async function main(argv: string[]): Promise<number> {
       "bearer-token": { type: "string" },
       "allow-anonymous": { type: "boolean", default: false },
       "allow-anonymous-cursor-github": { type: "boolean", default: false },
+      "allow-anonymous-cursor-account-mcp": { type: "boolean", default: false },
       "no-schedules": { type: "boolean", default: false },
       "no-playground": { type: "boolean", default: false },
       "no-docs": { type: "boolean", default: false },
@@ -403,6 +422,7 @@ async function main(argv: string[]): Promise<number> {
       "mount-path": { type: "string" },
       "base-url": { type: "string" },
       print: { type: "boolean", default: false },
+      store: { type: "boolean", default: false },
       transport: { type: "string" },
       prefix: { type: "string" },
       "no-prefix": { type: "boolean", default: false },
@@ -502,7 +522,8 @@ async function main(argv: string[]): Promise<number> {
 
     case "mcp": {
       const { cmdMcp } = await import("../internal/cli-mcp.js");
-      return cmdMcp(positionals[0], {
+      const mcpSub = positionals[0];
+      return cmdMcp(mcpSub, {
         dir,
         slug: values.slug,
         team: values.team,
@@ -513,6 +534,8 @@ async function main(argv: string[]): Promise<number> {
         name: values.name,
         print: values.print,
         json: values.json,
+        store: values.store,
+        oauthConnection: mcpSub === "oauth" ? positionals[1] : undefined,
       });
     }
 
@@ -976,6 +999,10 @@ async function main(argv: string[]): Promise<number> {
         allowAnonymous: values["allow-anonymous"] === true ? true : undefined,
         allowAnonymousCursorGithub:
           values["allow-anonymous-cursor-github"] === true ? true : undefined,
+        allowAnonymousCursorAccountMcp:
+          values["allow-anonymous-cursor-account-mcp"] === true
+            ? true
+            : undefined,
         schedules: values["no-schedules"] === true ? false : undefined,
         playground: values["no-playground"] === true ? false : undefined,
         docs: values["no-docs"] === true ? false : undefined,

package/src/channels/github/github-channel.ts

@@ -116,6 +116,7 @@ const githubPullRequestPayloadSchema: z.ZodType<GitHubPullRequestPayload> =
       title: z.string(),
       body: z.string().nullable().optional(),
       draft: z.boolean().optional(),
+      merged: z.boolean().optional(),
       user: z
         .object({
           login: z.string().min(1).optional(),
@@ -330,6 +331,7 @@ export function parseGitHubPullRequestEvent(args: {
       ? {}
       : { baseSha: payload.pull_request.base.sha }),
     draft: payload.pull_request.draft ?? false,
+    merged: payload.pull_request.merged === true,
     ...(payload.pull_request.user?.login === undefined
       ? {}
       : { authorLogin: payload.pull_request.user.login }),

package/src/channels/github/types.ts

@@ -148,6 +148,8 @@ export type GitHubPullRequestPayload = {
     title: string;
     body?: string | null;
     draft?: boolean;
+    /** Present on real webhook payloads; false/undefined when not merged. */
+    merged?: boolean;
     user?: {
       login?: string;
       id?: number;
@@ -182,6 +184,8 @@ export interface GitHubPullRequestEvent {
   baseRef: string;
   baseSha?: string;
   draft: boolean;
+  /** True when the PR was merged (from the webhook payload). */
+  merged: boolean;
   authorLogin?: string;
 }
 

package/src/channels/slack/cursor-account.ts

@@ -167,6 +167,8 @@ export async function dispatchCursorSlackEnvelope(args: {
     credentials: runtime.credentials,
     host: args.host,
     log,
+    evalCommandsEnabled: runtime.options.evalCommands !== false,
+    cursorAgentName: envelope.agentName,
     ...(args.hasContinuationSession === undefined
       ? {}
       : { hasContinuationSession: args.hasContinuationSession }),

package/src/channels/slack/dispatch.ts

@@ -6,6 +6,10 @@ import type { HostContext, JsonValue, SendMessageFn } from "../../types.js";
 import { buildSlackBinding, slackContinuationKey } from "./api.js";
 import { firstLineTitle, maybeSetThreadTitle } from "./assistant.js";
 import type { ChannelPostWatcher } from "./channel-watch.js";
+import {
+  handleSlackEvalDirective,
+  parseSlackEvalDirective,
+} from "./eval-directive.js";
 import type { EventIdDedupe } from "./event-id-dedupe.js";
 import {
   formatSlackContextBlock,
@@ -82,6 +86,13 @@ export interface SlackInboundDispatchDeps {
   ) => Promise<string | undefined>;
   /** Cancel the active turn + clear coalesced nudges for this continuation. */
   interruptContinuation?: (continuationToken: string) => Promise<boolean>;
+  /**
+   * When false, skip the built-in `eval` directive. Defaults to true when
+   * `host.evals` is present.
+   */
+  evalCommandsEnabled?: boolean;
+  /** cursorAccount agent name stripped before `eval` directive parsing. */
+  cursorAgentName?: string;
 }
 
 function triggeringMergeMessage(
@@ -114,6 +125,12 @@ export async function dispatchInboundMessage(args: {
   interruptContinuation?: (continuationToken: string) => Promise<boolean>;
   log?: SlackLog;
   eventId?: string;
+  evalCommandsEnabled?: boolean;
+  /**
+   * cursorAccount agent display name — stripped before parsing `eval …`
+   * (`OncallBuddy eval list`).
+   */
+  cursorAgentName?: string;
 }): Promise<void> {
   const { message, kind } = args;
   const log = args.log ?? defaultSlackLog;
@@ -168,6 +185,34 @@ export async function dispatchInboundMessage(args: {
     return;
   }
 
+  // Built-in eval directive: run playground batches without an agent turn.
+  const evalCommandsEnabled = args.evalCommandsEnabled !== false;
+  const evalParseOptions =
+    args.cursorAgentName === undefined || args.cursorAgentName === ""
+      ? undefined
+      : { agentName: args.cursorAgentName };
+  const evalDirective =
+    evalCommandsEnabled && args.host.evals !== undefined
+      ? (parseSlackEvalDirective(message.text, evalParseOptions) ??
+        parseSlackEvalDirective(message.markdown, evalParseOptions))
+      : null;
+  if (evalDirective !== null && args.host.evals !== undefined) {
+    log.info("eval directive", {
+      kind,
+      channel: message.channelId,
+      thread_ts: message.threadTs,
+      continuation,
+      event_id: args.eventId,
+      directive: evalDirective.kind,
+    });
+    await handleSlackEvalDirective({
+      directive: evalDirective,
+      evals: args.host.evals,
+      binding,
+    });
+    return;
+  }
+
   if (message.ts === message.threadTs) {
     await maybeSetThreadTitle({
       botToken: args.credentials?.botToken,
@@ -393,6 +438,8 @@ export function dispatchInboundFromEventBody(
         credentials: deps.credentials,
         host: deps.host,
         log,
+        evalCommandsEnabled: deps.evalCommandsEnabled,
+        cursorAgentName: deps.cursorAgentName,
         ...(deps.hasContinuationSession === undefined
           ? {}
           : { hasContinuationSession: deps.hasContinuationSession }),
@@ -431,6 +478,8 @@ export function dispatchInboundFromEventBody(
         credentials: deps.credentials,
         host: deps.host,
         log,
+        evalCommandsEnabled: deps.evalCommandsEnabled,
+        cursorAgentName: deps.cursorAgentName,
         ...(deps.hasContinuationSession === undefined
           ? {}
           : { hasContinuationSession: deps.hasContinuationSession }),

package/src/channels/slack/eval-directive.ts

@@ -0,0 +1,348 @@
+/**
+ * Built-in Slack `eval` directive — run playground evals from a mention/DM
+ * without per-agent custom handlers (parity with CLI / playground runs).
+ *
+ * Examples (after stripping @mentions / cursorAccount agent name):
+ *   eval
+ *   eval triage/open-incidents smoke
+ *   eval --tag oncall
+ *   eval list
+ *   eval status
+ *   eval help
+ */
+
+import type { EvalRunSnapshot, HostEvalsApi } from "../../evals.js";
+import {
+  EvalRunConflictError,
+  EvalRunEmptyError,
+} from "../../internal/eval-run-store.js";
+import { stripLeadingSlackMentions } from "./stop.js";
+import type { SlackBinding } from "./types.js";
+
+const EVAL_POLL_MS = 2_000;
+const TYPING_STATUS_MAX = 50;
+
+export type SlackEvalDirective =
+  | { kind: "help" }
+  | { kind: "list" }
+  | { kind: "status" }
+  | { kind: "run"; filterIds?: string[]; tags?: string[] };
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Normalize inbound Slack text for directive parsing: strip leading
+ * `<@U…>` mentions, leading `@U…` markdown mentions, and an optional
+ * cursorAccount agentName prefix (`OncallBuddy eval …`).
+ */
+export function normalizeSlackEvalDirectiveBody(
+  text: string,
+  options?: { agentName?: string }
+): string {
+  let body = stripLeadingSlackMentions(text);
+  // markdown form from slackTextToMarkdown / cursorAccount envelopes
+  while (/^@[A-Za-z0-9._-]+\s+/.test(body)) {
+    body = body.replace(/^@[A-Za-z0-9._-]+\s+/, "").trim();
+  }
+  const agentName = options?.agentName?.trim();
+  if (agentName !== undefined && agentName.length > 0) {
+    const prefix = new RegExp(`^${escapeRegExp(agentName)}\\s+`, "i");
+    body = body.replace(prefix, "").trim();
+  }
+  return body;
+}
+
+/**
+ * Parse a Slack eval directive. Returns null when the message is not an
+ * eval command (falls through to the normal agent handler).
+ */
+export function parseSlackEvalDirective(
+  text: string,
+  options?: { agentName?: string }
+): SlackEvalDirective | null {
+  const body = normalizeSlackEvalDirectiveBody(text, options);
+  if (body.length === 0) {
+    return null;
+  }
+  const tokens = body.split(/\s+/).filter((t) => t.length > 0);
+  if (tokens.length === 0 || !/^eval$/i.test(tokens[0] ?? "")) {
+    return null;
+  }
+
+  const rest = tokens.slice(1);
+  if (rest.length === 0) {
+    return { kind: "run" };
+  }
+
+  const head = (rest[0] ?? "").toLowerCase();
+  if (
+    rest.length === 1 &&
+    (head === "help" || head === "-h" || head === "--help")
+  ) {
+    return { kind: "help" };
+  }
+  if (rest.length === 1 && (head === "list" || head === "ls")) {
+    return { kind: "list" };
+  }
+  if (rest.length === 1 && head === "status") {
+    return { kind: "status" };
+  }
+
+  const filterIds: string[] = [];
+  const tags: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const tok = rest[i] ?? "";
+    if (tok === "--tag" || tok === "-t") {
+      const value = rest[i + 1];
+      if (value === undefined || value.length === 0) {
+        return { kind: "help" };
+      }
+      tags.push(value);
+      i += 1;
+      continue;
+    }
+    if (tok.startsWith("--tag=")) {
+      const value = tok.slice("--tag=".length);
+      if (value.length === 0) {
+        return { kind: "help" };
+      }
+      tags.push(value);
+      continue;
+    }
+    if (tok.startsWith("-t=") && tok.length > 3) {
+      tags.push(tok.slice(3));
+      continue;
+    }
+    if (tok.startsWith("-")) {
+      // Unknown flag — surface help rather than treating as an eval id.
+      return { kind: "help" };
+    }
+    filterIds.push(tok);
+  }
+
+  const run: SlackEvalDirective = { kind: "run" };
+  if (filterIds.length > 0) {
+    run.filterIds = filterIds;
+  }
+  if (tags.length > 0) {
+    run.tags = tags;
+  }
+  return run;
+}
+
+/** True when either raw Slack text or markdown form is an eval directive. */
+export function isSlackEvalDirective(
+  text: string,
+  markdown: string,
+  options?: { agentName?: string }
+): boolean {
+  return (
+    parseSlackEvalDirective(text, options) !== null ||
+    parseSlackEvalDirective(markdown, options) !== null
+  );
+}
+
+export function formatSlackEvalHelp(): string {
+  return [
+    "*Eval commands* (same batches as the playground / `agentkit eval --prod`):",
+    "• `eval` — run all evals",
+    "• `eval <id> [id…]` — run specific eval ids",
+    "• `eval --tag <tag>` — run evals with a tag (`-t` also works)",
+    "• `eval list` — list available evals",
+    "• `eval status` — show the active or latest eval run",
+    "• `eval help` — this message",
+  ].join("\n");
+}
+
+export function formatSlackEvalList(
+  evals: Array<{
+    id: string;
+    description?: string;
+    tags?: string[];
+  }>
+): string {
+  if (evals.length === 0) {
+    return "No evals found under `evals/`.";
+  }
+  const lines = [`*${evals.length} eval(s):*`];
+  for (const item of evals) {
+    const tags =
+      item.tags === undefined || item.tags.length === 0
+        ? ""
+        : ` _[${item.tags.join(", ")}]_`;
+    const desc =
+      item.description === undefined || item.description === ""
+        ? ""
+        : ` — ${item.description}`;
+    lines.push(`• \`${item.id}\`${tags}${desc}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatSlackEvalRunSummary(run: EvalRunSnapshot): string {
+  const { summary } = run;
+  const statusLabel =
+    run.status === "completed"
+      ? "completed"
+      : run.status === "failed"
+        ? "failed"
+        : "running";
+  const lines = [
+    `*Eval run* \`${run.runId}\` — *${statusLabel}*`,
+    `• ${summary.passed} passed, ${summary.failed} failed, ${summary.total} total` +
+      (summary.done < summary.total
+        ? ` (${summary.done}/${summary.total} done)`
+        : ""),
+  ];
+  if (run.error !== undefined && run.error !== "") {
+    lines.push(`• error: ${run.error}`);
+  }
+  for (const c of run.cases) {
+    const mark =
+      c.status !== "done"
+        ? c.status === "running"
+          ? "RUN "
+          : "….  "
+        : c.ok === true
+          ? "PASS"
+          : "FAIL";
+    const dur =
+      c.durationMs === undefined
+        ? ""
+        : ` (${(c.durationMs / 1000).toFixed(1)}s)`;
+    const err =
+      c.ok === false && c.error !== undefined && c.error !== ""
+        ? ` — ${c.error}`
+        : "";
+    lines.push(`\`${mark}\` \`${c.id}\`${dur}${err}`);
+  }
+  return lines.join("\n");
+}
+
+function truncateTyping(status: string): string {
+  if (status.length <= TYPING_STATUS_MAX) {
+    return status;
+  }
+  return `${status.slice(0, TYPING_STATUS_MAX - 1)}…`;
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+async function safeTyping(
+  binding: SlackBinding,
+  status: string
+): Promise<void> {
+  try {
+    await binding.thread.startTyping(truncateTyping(status));
+  } catch {
+    // best-effort status
+  }
+}
+
+async function safePost(binding: SlackBinding, text: string): Promise<void> {
+  try {
+    await binding.thread.post(text);
+  } catch {
+    // best-effort reply
+  }
+}
+
+/**
+ * Handle a parsed Slack eval directive against {@link HostEvalsApi}.
+ * Posts results in-thread; does not start an agent turn.
+ */
+export async function handleSlackEvalDirective(args: {
+  directive: SlackEvalDirective;
+  evals: HostEvalsApi;
+  binding: SlackBinding;
+  /** Override poll interval (tests). */
+  pollMs?: number;
+}): Promise<void> {
+  const { directive, evals, binding } = args;
+  const pollMs = args.pollMs ?? EVAL_POLL_MS;
+
+  if (directive.kind === "help") {
+    await safePost(binding, formatSlackEvalHelp());
+    return;
+  }
+
+  if (directive.kind === "list") {
+    const listed = await evals.list();
+    await safePost(binding, formatSlackEvalList(listed.evals));
+    return;
+  }
+
+  if (directive.kind === "status") {
+    const { runs, activeRunId } = await evals.listRunsWithActive();
+    const run =
+      (activeRunId === undefined ? undefined : await evals.get(activeRunId)) ??
+      runs[0];
+    if (run === undefined) {
+      await safePost(binding, "No eval runs yet. Try `eval list` then `eval`.");
+      return;
+    }
+    await safePost(binding, formatSlackEvalRunSummary(run));
+    return;
+  }
+
+  await safeTyping(binding, "Starting evals…");
+  let run: EvalRunSnapshot;
+  try {
+    run = await evals.start({
+      filterIds: directive.filterIds,
+      tags: directive.tags,
+    });
+  } catch (error) {
+    if (error instanceof EvalRunConflictError) {
+      const active = await evals.get(error.activeRunId);
+      await safePost(
+        binding,
+        active === undefined
+          ? `An eval run is already in progress (\`${error.activeRunId}\`).`
+          : `An eval run is already in progress:\n${formatSlackEvalRunSummary(active)}`
+      );
+      return;
+    }
+    if (error instanceof EvalRunEmptyError) {
+      await safePost(
+        binding,
+        "No matching evals. Try `eval list` or `eval help`."
+      );
+      return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    await safePost(binding, `Failed to start evals: ${message}`);
+    return;
+  }
+
+  await safePost(
+    binding,
+    `Started eval run \`${run.runId}\` (${run.summary.total} case(s)).`
+  );
+
+  while (run.status === "running") {
+    await safeTyping(
+      binding,
+      `Evals ${run.summary.done}/${run.summary.total}…`
+    );
+    await sleep(pollMs);
+    const next = await evals.get(run.runId);
+    if (next === undefined) {
+      await safePost(
+        binding,
+        `Eval run \`${run.runId}\` disappeared before completion.`
+      );
+      return;
+    }
+    run = next;
+  }
+
+  await safePost(binding, formatSlackEvalRunSummary(run));
+  await safeTyping(binding, "Evals done.");
+}

package/src/channels/slack/index.ts

@@ -29,6 +29,7 @@ export * from "./cursor-account.js";
 export * from "./defaults.js";
 export * from "./dispatch.js";
 export * from "./doctor.js";
+export * from "./eval-directive.js";
 export * from "./event-id-dedupe.js";
 export * from "./inbound.js";
 export * from "./init.js";

package/src/channels/slack/slack-channel.ts

@@ -138,6 +138,7 @@ export function slackChannel<const Name extends string = string>(
   const engagement = options.engagement ?? {};
   const mentionsEnabled = engagement.mentions !== false;
   const directMessagesEnabled = engagement.directMessages !== false;
+  const evalCommandsEnabled = options.evalCommands !== false;
   const channelPosts = engagement.channelPosts;
   if (channelPosts !== undefined) {
     const entries = channelPosts.allow.filter((entry) => entry.trim() !== "");
@@ -204,6 +205,7 @@ export function slackChannel<const Name extends string = string>(
       log: getLog(),
       mentionsEnabled,
       directMessagesEnabled,
+      evalCommandsEnabled,
       ...(args.hasContinuationSession === undefined
         ? {}
         : { hasContinuationSession: args.hasContinuationSession }),
@@ -342,6 +344,7 @@ export function slackChannel<const Name extends string = string>(
                   credentials,
                   host: args.host,
                   log: getLog(),
+                  evalCommandsEnabled,
                   ...(args.hasContinuationSession === undefined
                     ? {}
                     : {

package/src/channels/slack/types.ts

@@ -382,6 +382,13 @@ export interface SlackChannelOptions {
    * entry at 50 chars). Defaults to Thinking… / Working on it… / Almost there….
    */
   loadingMessages?: string[];
+  /**
+   * Built-in Slack `eval` / `eval list` / `eval status` directive that runs
+   * playground eval batches (`host.evals` / `/v1/dev/evals/runs`) without an
+   * agent turn. Defaults to `true`. Set `false` to leave `eval …` for the
+   * model handler instead.
+   */
+  evalCommands?: boolean;
   /** Optional teardown (e.g. stop example-local debouncers). Runs after Socket Mode stops. */
   onStop?: () => void | Promise<void>;
 }

package/src/connections.ts

@@ -2,11 +2,9 @@
  * `defineConnection` — authored at `agent/mcp-connections/<name>.ts`.
  *
  * A connection gives tools from an external MCP server. The filename
- * becomes the connection (server) name. Every connection is always
- * available in three places:
- * - the Cursor agent (local harness or cloud), via SDK `mcpServers`
- * - the agent-serve host, via `ctx.host.mcp` on in-process tools
- * - channel / schedule handlers, via `args.host.mcp`
+ * becomes the connection (server) name. Available to the agent (SDK
+ * `mcpServers`), host (`ctx.host.mcp`), and channel/schedule handlers.
+ * Pass `hostOnly: true` to keep it off the model (still on `host.mcp`).
  *
  * ```ts
  * import { defineConnection } from "@anysphere/agent-serve/connections";
@@ -15,6 +13,13 @@
  *   url: "https://mcp.linear.app/mcp",
  *   headers: { authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
  * });
+ *
+ * // privileged connector, model cannot call directly:
+ * export default defineConnection({
+ *   cursorAccount: true,
+ *   servers: ["anytool"],
+ *   hostOnly: true,
+ * });
  * ```
  *
  * A **Cursor account MCP connection** exposes the MCP connectors the operator