@cursor/july 0.1.93 → 0.1.94

package/src/internal/discovery.ts

@@ -50,8 +50,10 @@ import {
   type InlineStdioConnectionConfig,
   type InstructionsDefinition,
   isInlineStdioConnection,
+  isToolEffect,
   MAX_RUNNING_TURNS_LIMIT,
   type ModelSetting,
+  normalizeConnectionEffects,
   normalizeCursorAccountServers,
   type ResolvedAgent,
   type ScheduleDefinition,
@@ -423,6 +425,7 @@ async function loadAgent(
       tools: [],
       skills: [],
       connections: [],
+      hostConnections: [],
       subagents: [],
       seedFiles: [],
     };
@@ -434,6 +437,7 @@ async function loadAgent(
     ctx,
     await resolveMcpConnectionsDir(ctx, agentDir)
   );
+  const hostConnections = await loadHostConnections(ctx, agentDir, connections);
   const seedFiles = await loadSeedFiles(ctx, agentDir);
   const subagents = await loadSubagents(ctx, join(agentDir, "subagents"));
   const runtime = resolveRuntime(ctx, agentDir, config?.runtime);
@@ -553,7 +557,7 @@ async function loadAgent(
       agentTools: tools.filter((tool) => tool.execution === "agent").length,
       skills: skills.length,
       seedFiles: seedFiles.length,
-      connections: connections.length,
+      connections: connections.length + hostConnections.length,
       subagents: subagents.length,
       hasCloudOptions: cloud !== undefined,
       hasLocalSandbox: localSandbox,
@@ -576,6 +580,7 @@ async function loadAgent(
     tools,
     skills,
     connections,
+    hostConnections,
     subagents,
     seedFiles,
   };
@@ -1143,6 +1148,26 @@ function hasAuthorizationHeader(
   );
 }
 
+function parseConnectionEffects(
+  effects: unknown
+): { ok: true; value: ToolEffect[] | undefined } | { ok: false } {
+  if (effects === undefined) {
+    return { ok: true, value: undefined };
+  }
+  const raw = typeof effects === "string" ? [effects] : effects;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return { ok: false };
+  }
+  const parsed: ToolEffect[] = [];
+  for (const value of raw) {
+    if (!isToolEffect(value)) {
+      return { ok: false };
+    }
+    parsed.push(value);
+  }
+  return { ok: true, value: normalizeConnectionEffects(parsed) };
+}
+
 function connectionHasSpawnOrRemote(connection: ConnectionDefinition): boolean {
   if ("cursorAccount" in connection && connection.cursorAccount === true) {
     return true;
@@ -1265,6 +1290,49 @@ async function resolveMcpConnectionsDir(
   return preferred;
 }
 
+async function loadHostConnections(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  modelConnections: readonly DiscoveredConnection[]
+): Promise<DiscoveredConnection[]> {
+  const hostDir = join(agentDir, "host-connections");
+  const loaded = await loadConnections(ctx, hostDir);
+  const modelNames = new Set(
+    modelConnections.map((connection) => connection.name)
+  );
+  const hostConnections: DiscoveredConnection[] = [];
+  for (const connection of loaded) {
+    if (modelNames.has(connection.name)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message: `Host connection "${connection.name}" collides with agent/mcp-connections/${connection.name}. Rename one of them.`,
+      });
+      continue;
+    }
+    if (connection.advertiseTools === true) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message:
+          "Host connections are off the model. `advertiseTools` cannot apply. Drop it.",
+      });
+      continue;
+    }
+    if (connection.auth !== undefined) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message:
+          "Host connections are off the model. `auth` cannot apply. Use static headers or `oauth: true`.",
+      });
+      continue;
+    }
+    hostConnections.push(connection);
+  }
+  return hostConnections;
+}
+
 async function loadConnections(
   ctx: DiscoveryContext,
   connectionsDir: string
@@ -1292,6 +1360,15 @@ async function loadConnections(
       continue;
     }
     const connection = definition as ConnectionDefinition;
+    if (Object.hasOwn(connection, "hostOnly")) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          "MCP connection `hostOnly` was removed. Files under `agent/mcp-connections/` are always visible to the model. Put privileged servers in `agent/host-connections/` so only host tools can call them.",
+      });
+      continue;
+    }
     if (
       isInlineStdioConnection(connection) &&
       connectionHasSpawnOrRemote(connection)
@@ -1336,24 +1413,37 @@ async function loadConnections(
       });
       continue;
     }
+    const parsedEffects = parseConnectionEffects(connection.effects);
+    if (!parsedEffects.ok) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          'MCP connection `effects` must be "read", "write", or a non-empty array of those.',
+      });
+      continue;
+    }
     if (
-      connection.advertiseTools === true &&
-      isInlineStdioConnection(connection)
+      parsedEffects.value !== undefined &&
+      connection.advertiseTools !== true
     ) {
       ctx.diagnostics.push({
         severity: "error",
         path: displayPath(ctx, entryPath),
         message:
-          "MCP connection `advertiseTools` is not supported on inline `tools` connections — author those as agent/tools/ server tools instead.",
+          "MCP connection `effects` filters advertised tools; set `advertiseTools: true` or drop `effects`.",
       });
       continue;
     }
-    if (connection.advertiseTools === true && connection.hostOnly === true) {
+    if (
+      connection.advertiseTools === true &&
+      isInlineStdioConnection(connection)
+    ) {
       ctx.diagnostics.push({
         severity: "error",
         path: displayPath(ctx, entryPath),
         message:
-          "MCP connection `advertiseTools` puts the connection's tools in the model's toolset, which contradicts `hostOnly` (off the model entirely). Drop one of them.",
+          "MCP connection `advertiseTools` is not supported on inline `tools` connections — author those as agent/tools/ server tools instead.",
       });
       continue;
     }
@@ -1445,9 +1535,9 @@ async function loadConnections(
       name,
       transport,
       description: connection.description,
-      hostOnly: connection.hostOnly,
       auth: connection.auth,
       advertiseTools: connection.advertiseTools,
+      effects: parsedEffects.value,
     });
   }
   return connections;
@@ -1459,7 +1549,6 @@ async function loadInlineStdioConnection(
   entryPath: string,
   connection: InlineStdioConnectionConfig & {
     description?: string;
-    hostOnly?: boolean;
   }
 ): Promise<DiscoveredConnection | undefined> {
   const tools = connection.tools;
@@ -1510,7 +1599,6 @@ async function loadInlineStdioConnection(
       name,
       transport,
       description: connection.description,
-      hostOnly: connection.hostOnly,
     };
   } catch (error) {
     ctx.diagnostics.push({
@@ -1562,6 +1650,7 @@ async function warnUnsupportedSubagentSlots(
     ["tools", "tools"],
     ["skills", "skills"],
     ["mcp-connections", "MCP connections"],
+    ["host-connections", "host MCP connections"],
     ["connections", "MCP connections"],
     ["subagents", "nested subagents"],
     ["channels", "channels"],
@@ -1670,8 +1759,8 @@ function checkGrokBotRuntimeLimitations(
   }
   if (counts.connections > 0) {
     error(
-      displayPath(ctx, join(agentDir, "mcp-connections")),
-      "MCP connections are not wired into grokbot turns yet. Remove them or run the agent on the local runtime."
+      displayPath(ctx, agentDir),
+      "MCP connections (agent/mcp-connections/ or agent/host-connections/) are not wired into grokbot turns yet. Remove them or run the agent on the local runtime."
     );
   }
   if (counts.subagents > 0) {
@@ -2256,6 +2345,7 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       description: tool.description,
       execution: tool.execution,
       needsApproval: tool.needsApproval,
+      effect: tool.effect,
       inputSchema: tool.inputSchema,
     })),
     skills: agent.skills.map((skill) => ({
@@ -2265,8 +2355,8 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
     connections: agent.connections.map((connection) => ({
       name: connection.name,
       transport: connectionTransportLabel(connection.transport),
-      hostOnly: connection.hostOnly,
       advertiseTools: connection.advertiseTools,
+      effects: connection.effects,
       cursorAccountServers:
         "cursorAccount" in connection.transport
           ? (connection.transport.servers ?? "*")
@@ -2448,6 +2538,7 @@ async function warnUnknownSlots(
     "tools",
     "skills",
     "mcp-connections",
+    "host-connections",
     // Legacy slot name; resolveMcpConnectionsDir warns and still loads it.
     "connections",
     "subagents",
@@ -2457,7 +2548,7 @@ async function warnUnknownSlots(
     "ab",
     "sandbox",
     "lib",
-    // Vite playground custom tool chips (examples/*/agent/playground/tools).
+    // Vite playground custom tool chips (agent/playground/tools).
     "playground",
   ]);
   for (const entry of await sortedEntries(agentDir)) {

package/src/internal/fixtures/units-server.ts

@@ -0,0 +1,52 @@
+/**
+ * Tiny stdio MCP server used by mcp-host tests.
+ *
+ * Exposed as the `units` connection so the host can list and call tools
+ * over a real stdio transport.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const server = new McpServer({
+  name: "weather-units",
+  version: "0.1.0",
+});
+
+server.tool(
+  "celsius_to_fahrenheit",
+  "Convert a temperature from Celsius to Fahrenheit.",
+  { value: z.number().describe("Temperature in °C") },
+  async ({ value }) => {
+    const fahrenheit = Math.round((value * 9) / 5 + 32);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ celsius: value, fahrenheit }),
+        },
+      ],
+    };
+  }
+);
+
+server.tool(
+  "fahrenheit_to_celsius",
+  "Convert a temperature from Fahrenheit to Celsius.",
+  { value: z.number().describe("Temperature in Fahrenheit") },
+  async ({ value }) => {
+    const celsius = Math.round(((value - 32) * 5) / 9);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ fahrenheit: value, celsius }),
+        },
+      ],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/internal/hosted-delivery.ts

@@ -170,6 +170,19 @@ export async function dispatchHostedAdmission(
   };
 }
 
+function withServerTiming(response: Response, durationMs: number): Response {
+  const headers = new Headers(response.headers);
+  headers.set(
+    "Server-Timing",
+    `agent_sdk;desc="hosted";dur=${Math.max(0, durationMs).toFixed(1)}`
+  );
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
 export function registerHostedDeliveryRoute(input: {
   router: Router;
   base: string;
@@ -215,22 +228,29 @@ export function registerHostedDeliveryRoute(input: {
     pattern: `${input.base}${HOSTED_ADMISSION_PATH}`,
     auth: [auth],
     handler: async (request) => {
+      const startedAt = performance.now();
+      const finish = (response: Response) =>
+        withServerTiming(response, performance.now() - startedAt);
       const delivery = parseHostedAdmission(await readJsonObject(request));
       if (delivery === undefined) {
-        return errorResponse(
-          400,
-          "invalid_hosted_admission",
-          "Expected a supported Agent SDK hosted-admission envelope."
+        return finish(
+          errorResponse(
+            400,
+            "invalid_hosted_admission",
+            "Expected a supported Agent SDK hosted-admission envelope."
+          )
         );
       }
       const channel = input.channels.find(
         (candidate) => candidate.id === delivery.channelId
       );
       if (channel === undefined) {
-        return errorResponse(
-          404,
-          "channel_not_found",
-          `No channel named "${delivery.channelId}" is mounted.`
+        return finish(
+          errorResponse(
+            404,
+            "channel_not_found",
+            `No channel named "${delivery.channelId}" is mounted.`
+          )
         );
       }
       const admitted = await dispatchHostedAdmission({
@@ -239,7 +259,7 @@ export function registerHostedDeliveryRoute(input: {
         args: input.buildHandlerArgs(delivery.channelId),
       });
       if (admitted.pendingSend === undefined) {
-        return admitted.response;
+        return finish(admitted.response);
       }
       pruneExpired();
       const admissionToken = randomBytes(24).toString("hex");
@@ -247,12 +267,14 @@ export function registerHostedDeliveryRoute(input: {
         send: admitted.pendingSend,
         expiresAt: Date.now() + pendingTtlMs,
       });
-      return Response.json({
-        ok: true,
-        v: HOSTED_DELIVERY_PROTOCOL_VERSION,
-        outcome: "send",
-        admissionToken,
-      });
+      return finish(
+        Response.json({
+          ok: true,
+          v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+          outcome: "send",
+          admissionToken,
+        })
+      );
     },
   });
   input.router.add({
@@ -260,31 +282,41 @@ export function registerHostedDeliveryRoute(input: {
     pattern: `${input.base}${HOSTED_EXECUTION_PATH}`,
     auth: [auth],
     handler: async (request) => {
+      const startedAt = performance.now();
+      const finish = (response: Response) =>
+        withServerTiming(response, performance.now() - startedAt);
+
       const execution = parseHostedExecution(await readJsonObject(request));
       if (execution === undefined) {
-        return errorResponse(
-          400,
-          "invalid_hosted_execution",
-          "Expected a supported Agent SDK hosted-execution envelope."
+        return finish(
+          errorResponse(
+            400,
+            "invalid_hosted_execution",
+            "Expected a supported Agent SDK hosted-execution envelope."
+          )
         );
       }
       pruneExpired();
       const admitted = pending.get(execution.admissionToken);
       if (admitted === undefined) {
-        return errorResponse(
-          409,
-          "hosted_admission_unavailable",
-          "The hosted admission token is missing or expired."
+        return finish(
+          errorResponse(
+            409,
+            "hosted_admission_unavailable",
+            "The hosted admission token is missing or expired."
+          )
         );
       }
       if (
         admitted.sessionPublicId !== undefined &&
         admitted.sessionPublicId !== execution.sessionPublicId
       ) {
-        return errorResponse(
-          409,
-          "hosted_admission_session_mismatch",
-          "The hosted admission token is already bound to another session."
+        return finish(
+          errorResponse(
+            409,
+            "hosted_admission_session_mismatch",
+            "The hosted admission token is already bound to another session."
+          )
         );
       }
       admitted.sessionPublicId = execution.sessionPublicId;
@@ -321,7 +353,7 @@ export function registerHostedDeliveryRoute(input: {
         };
       })();
       const reply = await admitted.execution;
-      return Response.json(reply.body, { status: reply.status });
+      return finish(Response.json(reply.body, { status: reply.status }));
     },
   });
 }

package/src/internal/mcp-endpoint.ts

@@ -252,9 +252,9 @@ function buildToolMcpServer(
  * travels in the turn's MCP config or lands on the VM.
  *
  * The engine gates access twice, mirroring the authored server-tool path:
- * only bridgeable names (`isCloudBridgedConnection`) — `hostOnly`
- * connections and unknown names stay unreachable from a VM even with a
- * valid endpoint credential — and only while the bound session has a turn
+ * only bridgeable names (`isCloudBridgedConnection`) — unknown names
+ * stay unreachable from a VM even with a valid endpoint credential —
+ * and only while the bound session has a turn
  * in flight (`hasActiveTurn`), so a credential that persists on a VM after
  * its turn cannot keep calling host connectors. Listing forwards per
  * request, so a server that adds tools mid-session (`tools/list_changed`,

package/src/internal/mcp-host.ts

@@ -1,12 +1,13 @@
 /**
- * Host-side MCP clients for authored `agent/mcp-connections/*`.
+ * Host-side MCP clients for authored `agent/mcp-connections/*` and
+ * `agent/host-connections/*`.
  *
- * Every connection is always available in three places:
- * - the Cursor agent, via SDK `mcpServers` (local harness or cloud)
- * - the agent-serve host, for in-process server tools through
- *   {@link HostMcpRegistry} on {@link ToolContext.host}.mcp
- * - channel / webhook route handlers through
- *   {@link HostMcpRegistry} on {@link ChannelHandlerArgs.host}.mcp
+ * Model-visible connections (`mcp-connections/`) are available in three
+ * places: SDK `mcpServers`, in-process server tools through
+ * {@link HostMcpRegistry} on {@link ToolContext.host}.mcp, and channel /
+ * webhook handlers through {@link HostMcpRegistry} on
+ * {@link ChannelHandlerArgs.host}.mcp. Host connections skip the model
+ * and stay on `host.mcp` plus `mcp oauth`.
  */
 
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";

package/src/internal/peer-connections.ts

@@ -37,7 +37,10 @@ export function collectPeerConnections(
   const bySlug = new Map<string, PeerConnectionRef[]>();
   for (const { slug, project } of mounts) {
     const refs: PeerConnectionRef[] = [];
-    for (const connection of project.agent.connections) {
+    for (const connection of [
+      ...project.agent.connections,
+      ...(project.agent.hostConnections ?? []),
+    ]) {
       if (!isPeerConnectionTransport(connection.transport)) {
         continue;
       }

package/src/internal/playground/static.ts

@@ -96,9 +96,7 @@ export function renderPlaygroundAsset(file: string): Response {
 }
 
 /** Slack surface summary for the host home / `GET /v1/agents`. */
-export type AgentIndexSlack =
-  | { kind: "cursor-account"; handle: string }
-  | { kind: "socket" };
+export type AgentIndexSlack = { kind: "socket" };
 
 /** One row on the host home page and `GET /v1/agents`. */
 export interface AgentIndexEntry {

package/src/internal/resolved-connections.ts

@@ -46,13 +46,13 @@ export function validateMountConnectionsConfig(args: {
     return;
   }
   const label = args.slug === "" ? args.project.name : args.slug;
-  const hostOnlyNames = new Set(
-    agent.connections
-      .filter((connection) => connection.hostOnly === true)
-      .map((connection) => connection.name)
+  const hostConnectionNames = new Set(
+    (args.project.agent.hostConnections ?? []).map(
+      (connection) => connection.name
+    )
   );
   const filteredRefs = args.accountRefs.filter(
-    (ref) => ref.servers !== undefined && !hostOnlyNames.has(ref.name)
+    (ref) => ref.servers !== undefined && !hostConnectionNames.has(ref.name)
   );
   if (filteredRefs.length === 0) {
     return;
@@ -140,10 +140,8 @@ export function resolveMountConnections(args: {
 
   if (cloudCapable) {
     const hostOauthNames = agent.connections
-      .filter(
-        (connection) =>
-          connection.hostOnly !== true &&
-          isHostOauthConnectionTransport(connection.transport)
+      .filter((connection) =>
+        isHostOauthConnectionTransport(connection.transport)
       )
       .map((connection) => connection.name);
     if (hostOauthNames.length > 0) {
@@ -154,7 +152,7 @@ export function resolveMountConnections(args: {
             )}) reach cloud turns through the host connection bridge; their tokens stay on this serve host.`
           : `[agent-sdk] warning: agent "${label}" has host-OAuth MCP connections (${hostOauthNames.join(
               ", "
-            )}) whose tokens live on this serve host; cloud-runtime turns omit them. Mark them \`hostOnly: true\` and call them from host tools, or drop \`oauth\` and authorize the server another way.`
+            )}) whose tokens live on this serve host; cloud-runtime turns omit them. Serve with a cloud tools URL so they reach turns through the host connection bridge, or drop \`oauth\` and authorize the server another way.`
       );
     }
   }