@cursor/july 0.1.111 → 0.1.112

package/dist/docs/guides/mcp-oauth.md

@@ -1,169 +1,159 @@
-# Host MCP OAuth
+# Connect a private MCP server with OAuth
 
-Use host MCP OAuth when your agent talks to a remote MCP server that
-speaks OAuth, and you want credentials on the serve host (or the hosted
-engine) instead of a Cursor account connector. Local login writes tokens
-next to your Cursor credentials. `--store` copies those tokens onto the
-deployment as secrets so prod can reconnect after a redeploy. Hosted
-Connect lets the current process retry.
+Host MCP OAuth lets an Agent SDK process authorize a remote MCP server
+without putting tokens in the agent's source or workspace. Use it when
+the server speaks OAuth and its credentials should belong to the serve
+host instead of a person's Cursor account.
 
-The companion skill is
-[`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
+## Use a private MCP tool locally
 
-## What can host MCP OAuth do?
+Declare the remote server, authorize it once in the browser, and start
+the agent. The next local turn can call the server's named tools with
+the credentials stored on that host.
 
-- Authorize `defineConnection({ url, oauth: true })` with a browser PKCE
-  flow (`agent-sdk mcp oauth <connection>`)
-- Keep tokens in `mcp-auth.json` under the CLI config directory, bound
-  to that connection's resource URL
-- Upsert deployment secrets with `--store` so the next deploy seeds the
-  same tokens from env. Hosted Connect lets the current process retry.
-- Use `advertiseTools: true` when local turns should call the server by
-  name. Host tools can still call it through `ctx.host.mcp`.
+```ts
+// agent/mcp-connections/inventory.ts
+import { defineConnection } from "@cursor/july/connections";
 
-Prefer a Cursor account MCP connection when the connector already lives
-in the signed-in account dashboard:
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  oauth: true,
+  advertiseTools: true,
+});
+```
 
-```ts
-defineConnection({ cursorAccount: true }) // every connected connector
-// or servers: "*" / servers: ["Linear"]
+```bash
+agent-sdk mcp oauth inventory
+agent-sdk run --dir . \
+  --message "Which east-coast warehouse has SKU-142 in stock?"
 ```
 
-Use host OAuth when the server is yours (or private to your network)
-and the host must hold tokens.
+The filename is the connection name used by the CLI and
+`ctx.host.mcp`. Changing the server URL invalidates its saved
+authorization, so run `mcp oauth` again after moving the endpoint.
 
-## How do I declare a host-OAuth connection?
+## Connect on first use
 
-Add one file under `agent/mcp-connections/` (model + host) or
-`agent/host-connections/` (host + `mcp oauth` only). The filename is the
-connection name you pass to the CLI and to `host.mcp`.
+You can also let the first unauthenticated call ask for authorization.
+The turn parks and the playground shows **Connect**. Finish the browser
+flow, return to the playground, and confirm **Connected**; the same call
+retries and the turn continues without restarting the agent.
+
+```bash
+agent-sdk serve --dir . --dev
+```
+
+Connect authorizes the process that is running now. It does not seed
+credentials for a future hosted replacement; use `--store` for that
+separate outcome.
+
+## Keep privileged tools behind a wrapper
+
+Put a connection under `agent/host-connections/` when the model should
+not receive the MCP server's tools directly. A server tool can expose
+one constrained operation while `ctx.host.mcp` keeps the broader server
+on the host.
 
 ```ts
-// agent/mcp-connections/inventory.ts
+// agent/host-connections/inventory.ts
 import { defineConnection } from "@cursor/july/connections";
 
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   oauth: true,
-  description: "Inventory MCP.",
+  tools: ["lookup_stock"],
+});
+```
+
+```ts
+// agent/tools/get_stock.ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Read stock for one approved region.",
+  inputSchema: z.object({
+    sku: z.string(),
+    region: z.enum(["us-east", "us-west"]),
+  }),
+  async execute(input, ctx) {
+    const result = await ctx.host.mcp.callTool(
+      "inventory",
+      "lookup_stock",
+      input
+    );
+    return {
+      ok: result.isError !== true,
+      stock: result.structuredContent ?? null,
+    };
+  },
 });
 ```
 
-Rules of the road:
+The model sees `get_stock`, not the unrestricted inventory server.
+Use this shape when code should own an allowlist, approval, or other
+side-effect gate.
 
-- `oauth: true` is required for `agent-sdk mcp oauth`
-- A file under `mcp-connections/` is visible to the model and to `ctx.host.mcp`. A file under `host-connections/` stays on the host.
-- Declare expected secret names on the agent when you plan to `--store`:
+## Keep OAuth across hosted replacements
+
+Declare the server's egress domain and the OAuth secret names, authorize
+from a signed-in machine, then store the credentials and redeploy. The
+next hosted process can reconnect without opening a browser.
 
 ```ts
 // agent/agent.ts
 export default defineAgent({
-  // …
   hosting: {
+    egressDomains: ["mcp.example.com"],
     secretNames: [
       "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
       "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
       "MCP_OAUTH_INVENTORY_CLIENT_ID",
     ],
-    // Hosted engines need an explicit allowlist for non-bootstrap hosts.
-    egressDomains: ["mcp.example.com"],
   },
 });
 ```
 
-Secret names follow `MCP_OAUTH_<CONNECTION>_*` where `<CONNECTION>` is
-the connection filename uppercased with non-alphanumerics turned into
-underscores (`inventory` → `MCP_OAUTH_INVENTORY_…`).
-
-## How do I authorize locally?
-
-From the agent project (Node 22.13+, not Bun):
-
-```bash
-agent-sdk mcp oauth inventory
-```
-
-What happens:
-
-1. The Agent SDK loads the connection file and checks `oauth: true`
-2. It opens the authorization URL in your browser
-3. The callback lands on `http://localhost:8787/callback`
-4. Tokens land in `mcp-auth.json` under the CLI config directory
-  (override with `AGENT_SERVE_CONFIG_DIR`)
-
-If you're already authorized, the command prints that and exits. Re-run
-it after rotating tokens on the MCP server, or after you change the
-connection URL (tokens are bound to the resource URL).
-
-## How do I store credentials on a hosted deployment?
-
-Authorize once. Then get the tokens onto the deployment.
-
-On a hosted engine, finishing Connect lets the current process retry.
-Self-hosted serve writes tokens locally only.
-
-`--store` from a signed-in laptop is the reliable way to put
-`MCP_OAUTH_*` on the next deploy. If `agent-sdk secrets list` is
-empty, run `--store` and redeploy.
-
-From a laptop, push secrets with the CLI:
-
 ```bash
 agent-sdk mcp oauth inventory --store
-# optional:
-#   --slug my-agent
-#   --team <cursor-team-id>
+agent-sdk secrets list my-agent
+agent-sdk deploy
 ```
 
-`--store` upserts:
-
-| Secret | Source |
-| --- | --- |
-| `MCP_OAUTH_<NAME>_ACCESS_TOKEN` | access token (required) |
-| `MCP_OAUTH_<NAME>_REFRESH_TOKEN` | refresh token when the server returns one |
-| `MCP_OAUTH_<NAME>_CLIENT_ID` | dynamic client id when registration returned one |
-
-You must be signed in (`agent-sdk login`) with permission to set secrets
-on that slug. Secrets apply on the **next** deploy. Run
-`agent-sdk deploy` after `--store`. A fresh pod sees `MCP_OAUTH_*`
-only after that deploy.
+`--store` writes deployment secrets; it does not restart the current
+engine. Follow the CLI or dashboard prompt to redeploy, then exercise
+the hosted agent.
 
-On the engine, when `mcp-auth.json` is empty, serve seeds the OAuth
-provider from those env vars so host MCP calls work without a browser
-on the pod.
+These credentials belong to the deployment, not to the person who
+clicked Connect. Anyone able to use that agent can reach the MCP
+capabilities you expose, so keep privileged servers host-only or narrow
+their tool list.
 
-These secrets are deployment-wide. Anyone who can list or set secrets
-on that slug, and the hosted engine's runtime env, can use them. That
-is the same blast radius as `--store`. They are not scoped to the
-caller who clicked Connect. `cursorAccount: true` tokens stay on the
-Cursor backend for the deployment service account and do not use
-`MCP_OAUTH_*`.
+## Choose where credentials live
 
-## How do host tools call the server?
+Use the credential shape that matches who should own access:
 
-```ts
-const result = await ctx.host.mcp.callTool(
-  "inventory",
-  "list_warehouses",
-  { region: "us-east" }
-);
-```
+- Choose `cursorAccount: true` for connectors already authorized under
+  MCP in the Cursor dashboard. Their tokens stay on the Cursor backend.
 
-The model can call the same server. Use a host tool when the write needs
-an allowlist or other deterministic gate.
+- Choose `url` with `oauth: true` when the serve host or hosted
+  deployment should hold OAuth credentials.
 
-## What if authorization fails?
+- Choose `url` with static `headers` when the server uses an API key or
+  bearer token instead of OAuth.
 
-| What you see | What to do |
-| --- | --- |
-| `must be defineConnection({ url, oauth: true })` | Add `oauth: true` on that connection, or pick the right connection name |
-| Callback never completes | Keep port `8787` free; finish the browser login on this machine |
-| Hosted calls unauthorized after Connect or `--store` | Confirm secrets with `agent-sdk secrets list <slug>`, then redeploy |
-| Tokens ignored after URL change | Expected: resource URL binding drops stale entries. Re-run `mcp oauth` |
+Host OAuth and per-session `auth` are different identity models and
+cannot be combined on one connection. Use per-session auth when each
+caller needs a different downstream identity.
 
-## What's next
+## Related
 
-- [MCP connections](/docs/reference/connections.md): transports, account MCP
-- [CLI](/docs/reference/cli.md#mcp-oauth): full flag list for `mcp oauth`
-- [Deployment](/docs/deployment.md): secrets, egress, and hosted engines
-- [Fix common agent problems](/docs/troubleshooting.md): more symptom → fix tables
+- [`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md): the
+  companion setup procedure for coding agents
+- [MCP connections](/docs/reference/connections.md): transports, account
+  connectors, per-session auth, and tool filtering
+- [CLI reference](/docs/reference/cli.md#mcp-oauth): OAuth command flags
+  and browser callback behavior
+- [Deployment](/docs/deployment.md): hosted secrets and egress
+- [Troubleshooting](/docs/troubleshooting.md): authorization symptoms and
+  remedies