@cursor/july 0.1.113 → 0.1.114

package/dist/docs/reference/connections.md

@@ -1,16 +1,15 @@
-# MCP Connections
+# MCP connections
 
-An MCP connection gives the agent tools from an MCP server. One file per
-server under `agent/mcp-connections/`, and the filename becomes the server
-name the model sees. An MCP connection default-exports `defineConnection`
-from `@cursor/july/connections`, and the transport comes in
-four shapes: remote HTTP, local stdio, the signed-in Cursor account's
-connectors, and peer agents on the same host.
+An MCP connection gives the agent tools from an MCP server. Define one
+file per server under `agent/mcp-connections/`; the filename becomes the
+server name. Default-export `defineConnection` from
+`@cursor/july/connections`. The transport is remote HTTP, local stdio,
+the signed-in Cursor account's connectors, or a peer agent on the same
+host.
 
-Put a server in `agent/host-connections/` when host tools should call it
-and the model should not. Same `defineConnection` shape. `agent-sdk mcp
-oauth` still works. The playground and the turn's MCP servers never see
-those files.
+Put a server in `agent/host-connections/` when only host tools should
+call it. Host connections use the same `defineConnection` shape and
+support `agent-sdk mcp oauth`; the model and playground don't see them.
 
 ## Remote MCP server
 
@@ -32,8 +31,7 @@ Tokens come from env vars. Never hardcode them in the file.
 For servers that speak OAuth, set `oauth: true` and authorize with the
 CLI or mid-run Connect. Tokens live in `mcp-auth.json` under the CLI
 config directory. `--store` copies them onto the deployment as
-`MCP_OAUTH_<NAME>_*` secrets. Hosted Connect lets the current
-process retry.
+`MCP_OAUTH_<NAME>_*` secrets.
 
 ```ts
 export default defineConnection({
@@ -45,24 +43,17 @@ export default defineConnection({
 ```bash
 agent-sdk mcp oauth inventory           # browser PKCE → local mcp-auth.json
 agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
-# Hosted Connect retries this process. Self-hosted stays file-only.
 ```
 
 Full walkthrough: [Host MCP OAuth](/docs/guides/mcp-oauth.md). Companion
 skill: [`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
 
-Account MCP (`cursorAccount: true`) is the right choice for connectors
-already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)
-to forward every connected connector. If the model should call those
-tools by name on local turns, set `advertiseTools: true`.
+## Per-session auth
 
-## Per-session auth (`auth`)
-
-For http/sse connections whose credential depends on **who the session is
-for** (a multi-tenant agent asserting the tenant it is acting for),
-declare an `auth` callback instead of static headers. It runs host-side
-at turn-build time with the session's `SessionInfo` and returns headers
-merged over the static ones:
+For http/sse connections whose credential depends on who the session is
+for, declare an `auth` callback instead of static headers. It runs
+host-side with the session's `SessionInfo` and returns headers merged
+over the static ones:
 
 ```ts
 export default defineConnection({
@@ -70,39 +61,31 @@ export default defineConnection({
   auth: async (session) => ({
     headers: { Authorization: `Bearer ${await grantFor(session)}` },
   }),
-  advertiseTools: true, // optional — named tools instead of meta-tools
+  advertiseTools: true,
 });
 ```
 
-The callback is evaluated on **every local turn**, including reminder
-fires and post-restart follow-ups, so the identity always comes from the
-session itself, never from state parked in memory. The model never sees a
-tenant parameter and can never choose the tenant. A callback that throws
-fails the turn: a turn never silently runs without the connection's
-identity. Local runtime only; cloud turns are refused. `host.mcp` calls
-from server tools keep the static headers only. Not combinable with
-`oauth: true`; the host OAuth provider owns the Authorization header.
+The identity always comes from the session itself, never from a tenant
+parameter the model could invent. A callback that throws fails the
+turn; a cloud turn with `auth` is refused instead of running without
+that identity. `host.mcp` calls from server tools keep the static
+headers only. You can't combine `auth` with `oauth: true`.
 
 Derive the identity from durable session facts: `session.auth`,
-`session.id`, or your channel's own session state. Do **not** key it off
-`session.continuationKey`: the HTTP channel rotates the continuation key
-after every accepted follow-up, so a tenant mapping keyed on it silently
-breaks mid-conversation. (Channels that mint stable, parseable tokens by
-design are the exception.)
-
-`auth` works attached or advertised. Advertised connections open
-per-operation clients with the evaluated headers. Attached connections
-ride the turn's SDK `mcpServers`, passed on **every send** rather than
-pinned on the cached per-session agent handle, so a rotated credential is
-live on the very next turn. A stateful stdio server cannot share a
-process with an attached `auth` connection. Advertise the auth
-connection instead.
-
-## Advertise a connection's tools by name (`advertiseTools`) {#advertise-tools}
-
-Set `advertiseTools: true` when the model should call an MCP server's tools
-by name. The Agent SDK preserves each tool's name, description, input and
-output schemas, and MCP annotations.
+`session.id`, or your channel's own session state. Do not key it off
+`session.continuationKey`. The HTTP channel rotates that key after every
+accepted follow-up, so a tenant mapping keyed on it breaks
+mid-conversation.
+
+`auth` works attached or advertised. Advertise the auth connection
+instead of attaching it next to a stateful stdio server.
+
+## Advertise tools {#advertise-tools}
+
+Set `advertiseTools: true` when the model should call an MCP server's
+tools by name. The Agent SDK preserves each tool's description, input
+and output schemas, and MCP annotations. Exposed names normalize invalid
+characters and add numeric suffixes to avoid collisions.
 
 ```ts
 export default defineConnection({
@@ -112,20 +95,22 @@ export default defineConnection({
 });
 ```
 
-A listing failure, invalid tool name, or name collision fails the turn.
-Advertised tools follow the same runtime support as server tools. They cannot
-be called through the direct tool API.
+A listing or authentication failure fails the turn by default. Set
+`optional: true` to omit an unavailable connection instead. Advertised
+tools follow the same runtime support as server tools, and [direct tool
+calls](/docs/reference/tools.md#call-a-tool-without-a-model-turn) use the same names.
 
-In a dry-run session, MCP tools marked read-only run normally. Tools marked
-as writes are stubbed. Tools without effect annotations are unavailable.
+In a dry-run session, MCP tools marked read-only run normally. Tools
+marked as writes are stubbed. Tools without effect annotations are
+unavailable.
 
-## Restrict which tools a connection serves
+## Filter connection tools
 
 Use `tools` the same way you allowlist harness tools on the agent. When
 set, the connection serves only those names. Use `disallowedTools` to
-drop names instead. The two combine as deny-wins, same as the Cursor
-SDK. The model and `host.mcp` only see what remains. On a model-visible
-connection, set `advertiseTools: true` so the raw server is not attached.
+drop names instead. The two combine as deny-wins. The model and
+`host.mcp` only see what remains. A model-visible filter requires
+`advertiseTools: true`.
 
 ```ts
 export default defineConnection({
@@ -133,7 +118,9 @@ export default defineConnection({
   advertiseTools: true,
   tools: ["search_skus", "get_stock"],
 });
+```
 
+```ts
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   advertiseTools: true,
@@ -142,9 +129,9 @@ export default defineConnection({
 ```
 
 Names are the server's `tools/list` names. Unknown names are omitted. A
-filter that matches nothing on the server fails the turn. Combine with
-`effects: "read"` to keep only the listed tools the server classifies as
-reads.
+filter that matches nothing on the server fails the turn unless
+`optional: true`. Combine with `effects: "read"` to keep only the listed
+tools the server classifies as reads.
 
 A list of names is an allowlist. An object of handlers authors TypeScript
 tools. On `host-connections/`, a name list restricts `host.mcp` without
@@ -162,12 +149,8 @@ export default defineConnection({
 });
 ```
 
-This suits small purpose-built servers, like a `units` converter
-shipped next to the agent.
-
-To run TypeScript in the agent environment (including a repo-less cloud
-VM), author the tools on the connection instead. The Agent SDK packages
-them as stdio MCP. You write `execute`. The Agent SDK speaks the protocol.
+To run TypeScript in the agent environment, including a repo-less cloud
+VM, author the tools on the connection instead. You write `execute`:
 
 ```ts
 export default defineConnection({
@@ -185,12 +168,12 @@ export default defineConnection({
 ## Cursor account MCP connection
 
 `{ cursorAccount: true }` forwards the MCP connectors the signed-in
-Cursor account already authorized (dashboard → MCP): Linear, Notion,
-Slack, and the rest. You don't configure tokens. Every tool runs on the
+Cursor account already authorized (dashboard → MCP), such as Linear,
+Notion, and Slack. You don't configure tokens. Every tool runs on the
 Cursor backend with the account's stored OAuth credentials, so raw
-tokens never reach the serve host, session workspaces, or traces.
+tokens never reach the serving host, session workspaces, or traces.
 
-By default the agent gets **every** connected HTTP/SSE connector on the
+By default the agent gets every connected HTTP/SSE connector on the
 account. Pass `servers: "*"` (or `["*"]`) for the same all-connectors
 behavior in an explicit form. Pass a name list when you want a smaller
 set.
@@ -201,12 +184,9 @@ export default defineConnection({
   cursorAccount: true,
   advertiseTools: true,
 });
-// same, spelled out:
-export default defineConnection({
-  cursorAccount: true,
-  servers: "*",
-  advertiseTools: true,
-});
+```
+
+```ts
 // only Linear:
 export default defineConnection({
   cursorAccount: true,
@@ -217,17 +197,15 @@ export default defineConnection({
 
 Name the file `account.ts`. `cursor.ts` collides with the IDE `cursor`
 MCP namespace. `advertiseTools: true` puts connector tools on local
-turns by name. Without it they sit behind harness meta-tools.
+turns by name.
 
 The host must be signed in (`agent-sdk login`, `CURSOR_API_KEY`, or
-`CURSOR_SERVICE_ACCOUNT_KEY`).
-`serve` fails fast at startup otherwise, and logs each connector's live
-status (`connected`, `needsAuth`, `error`) as it starts.
+`CURSOR_SERVICE_ACCOUNT_KEY`). `serve` fails at startup otherwise.
 
 Filtered account connections work on managed cloud deployments. A
-self-hosted cloud agent with a concrete `servers` list needs `--public-url`.
-Serve fails instead of ignoring the filter. Use a `{ command }` connection
-for stdio servers.
+self-hosted cloud agent with a concrete `servers` list needs
+`--public-url`. Serve fails instead of ignoring the filter. Use a
+`{ command }` connection for stdio servers.
 
 > [!CAUTION]
 > Whoever can talk to the agent can drive these connectors, because they
@@ -237,11 +215,11 @@ for stdio servers.
 > for example an SSO proxy or the hosted alias token). Prefer
 > `--bearer-token` on shared hosts.
 
-## Peer MCP connection
+## Peer MCP connection {#peer-mcp-connection}
 
 `{ agent: "<slug>" }` addresses another agent mounted on the same serve
-host. The model gets the peer's `ask` and `check` (and `call_tool`)
-tools and can delegate work to it:
+host. The model gets the peer's `ask` and `check` tools, plus
+`call_tool` when the peer has server tools, and can delegate work to it:
 
 ```ts
 export default defineConnection({
@@ -253,48 +231,34 @@ export default defineConnection({
 Unknown slugs and self-references fail `serve` at startup. Walkthrough:
 [Peer agents](/docs/guides/agent-to-agent.md#delegate-a-question-to-a-specialist).
 
-## Every model-visible MCP connection is available in three places
-
-A file under `agent/mcp-connections/` serves three consumers. Host
-connections skip the first one.
-
-1. **Cursor agent:** Attached connections ride SDK `mcpServers` behind
-   harness MCP meta-tools. Set `advertiseTools: true` so local turns see
-   named tools.
-2. **Server tools:** Deterministic host code composes MCP calls
-   through `ctx.host.mcp`:
-
-   ```ts
-   export default defineTool({
-     description: "Search Linear issues.",
-     inputSchema: z.object({ query: z.string() }),
-     async execute({ query }, ctx) {
-       return ctx.host.mcp.callTool("linear", "list_issues", { query });
-     },
-   });
-   ```
+## Call MCP from host code
 
-3. **Channel and schedule handlers:** Webhooks hit MCP servers with no
-   model turn at all, through `args.host.mcp`:
+A file under `agent/mcp-connections/` is available to the Cursor agent,
+to server tools through `ctx.host.mcp`, and to channel and schedule
+handlers through `args.host.mcp`. Host connections skip the model.
 
-   ```ts
-   POST("/sync", {
-     bodySchema: z.object({}),
-     handler: async (_req, { host }) => {
-       const result = await host.mcp.callTool("linear", "list_issues", {});
-       return Response.json(result);
-     },
-   });
-   ```
-
-The host registry is small: `host.mcp.names()` lists MCP connection names,
-and `listTools(name)` / `callTool(name, tool, args)` open the client
-lazily on first use.
+```ts
+// agent/tools/search_linear.ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Search Linear issues.",
+  inputSchema: z.object({ query: z.string() }),
+  async execute({ query }, ctx) {
+    return ctx.host.mcp.callTool("linear", "list_issues", { query });
+  },
+});
+```
 
-## What's next
+`host.mcp.names()` lists connection names.
+`listTools(name)` / `callTool(name, tool, args)` call into a named
+connection.
 
-Continue with these pages:
+## Related
 
 - [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
 - [Tools](/docs/reference/tools.md): authored tools that wrap MCP connections
 - [Webhooks](/docs/guides/webhooks.md): calling MCP connections from handlers
+- [Peer agents](/docs/guides/agent-to-agent.md): when a specialist is its
+  own agent