@cursor/july 0.1.9 → 0.1.11

package/docs/guides/mcp-oauth.md

@@ -0,0 +1,157 @@
+---
+title: "Host MCP OAuth"
+description: "Authorize defineConnection({ url, oauth: true }) with agentkit mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments."
+---
+
+# Host MCP 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 them onto the
+deployment as secrets so prod can reconnect after a redeploy.
+
+The companion skill is
+[`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
+
+## What can host MCP OAuth do?
+
+- Authorize `defineConnection({ url, oauth: true })` with a browser PKCE
+  flow (`agentkit mcp oauth <connection>`)
+- Keep tokens in `~/.config/agent-serve/mcp-auth.json`, bound to that
+  connection's resource URL
+- Upsert deployment secrets with `--store` so hosted engines seed the
+  same tokens from env
+- Keep privileged servers off the model with `hostOnly: true` while
+  tools still call them through `ctx.host.mcp`
+
+Prefer a Cursor account MCP connection
+(`defineConnection({ cursorAccount: true, servers: […] })`) when the
+connector already lives in the signed-in account dashboard. Use host
+OAuth when the server is yours (or private to your network) and the host
+must hold tokens.
+
+## How do I declare a host-OAuth connection?
+
+Add one file under `agent/mcp-connections/`. The filename is the
+connection name you pass to the CLI and to `host.mcp`.
+
+```ts
+// agent/mcp-connections/inventory.ts
+import { defineConnection } from "@cursor/july/connections";
+
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  oauth: true,
+  hostOnly: true,
+  description:
+    "Inventory MCP (privileged). Call only from host tools, not the model.",
+});
+```
+
+Rules of the road:
+
+- `oauth: true` is required for `agentkit mcp oauth`
+- `hostOnly: true` hides the server from the model; `ctx.host.mcp` and
+  channel handlers still see it
+- Declare expected secret names on the agent when you plan to `--store`:
+
+```ts
+// agent/agent.ts
+export default defineAgent({
+  // …
+  hosting: {
+    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
+agentkit mcp oauth inventory
+```
+
+What happens:
+
+1. agentkit loads `agent/mcp-connections/inventory.ts` 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 `~/.config/agent-serve/mcp-auth.json` (override the
+   config dir 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 push secrets to the deployment:
+
+```bash
+agentkit mcp oauth inventory --store
+# optional:
+#   --slug my-agent
+#   --team <cursor-team-id>
+```
+
+`--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 (`agentkit login`) with permission to set secrets
+on that slug. Secrets apply on the **next** deploy; run
+`agentkit deploy` (or wait for your usual deploy path) after `--store`.
+
+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.
+
+## How do host tools call the server?
+
+Keep privileged calls on the host:
+
+```ts
+const result = await ctx.host.mcp.callTool(
+  "inventory",
+  "list_warehouses",
+  { region: "us-east" }
+);
+```
+
+The model never sees `hostOnly` tools in its MCP namespace list. If the
+agent asks to "check IDE MCP" or run `mcp_auth`, point it at your host
+tool instead.
+
+## What if authorization fails?
+
+| 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 `--store` | Confirm secrets with `agentkit secrets list <slug>`, then redeploy |
+| Tokens ignored after URL change | Expected: resource URL binding drops stale entries. Re-run `mcp oauth` |
+
+## What's next
+
+- [MCP connections](../reference/connections.md): transports, `hostOnly`, account MCP
+- [CLI](../reference/cli.md#mcp-oauth): full flag list for `mcp oauth`
+- [Deployment](../deployment.md): secrets, egress, and hosted engines
+- [Fix common agent problems](../troubleshooting.md): more symptom → fix tables

package/docs/reference/cli.md

@@ -43,6 +43,7 @@ also provide `agentkit slack help` and `agentkit github help`.
 | [`rotate-token`](#rotate-token)                         | Replace a deployment's alias token                             |
 | [`rotate-pod-credential`](#rotate-pod-credential)       | Replace a deployment's pod credential                          |
 | [`secrets`](#secrets)                                   | Manage deployment secrets                                      |
+| [`mcp oauth`](#mcp-oauth)                               | Authorize host MCP OAuth; optional `--store` to deployment secrets |
 | [`slack ...`](#slack)                                   | Set up and check Slack channels                                |
 | [`github ...`](#github)                                 | Forward, replay, and inspect GitHub webhook channels           |
 
@@ -86,6 +87,7 @@ agentkit serve [--dir <path>] [--port 3000] [--host 127.0.0.1] [--dev]
                   [--mode multi|single] [--api-key <key>]
                   [--state-root <path>] [--bearer-token <secret> | --allow-anonymous]
                   [--allow-anonymous-cursor-github]
+                  [--allow-anonymous-cursor-account-mcp]
                   [--public-url <url>] [--no-schedules] [--no-playground]
                   [--no-docs] [--cursor-events --repo owner/name]...
 ```
@@ -109,6 +111,7 @@ Unless `--state-root` is set, each mount uses
 | `--bearer-token` | Require this bearer token on routes without authored auth. Mutually exclusive with `--allow-anonymous`. |
 | `--allow-anonymous` | Admit every caller as one `anonymous` principal. Use only behind a trusted network boundary. |
 | `--allow-anonymous-cursor-github` | Allow anonymous callers to drive sessions holding a Cursor account's repo-scoped GitHub credential. Use only behind an authenticating proxy. |
+| `--allow-anonymous-cursor-account-mcp` | Allow anonymous callers to drive Cursor account MCP connectors (`defineConnection({ cursorAccount: true })`). Use only behind an authenticating proxy (hosted alias token counts). |
 | `--public-url` | Set the externally reachable host URL. Cloud-runtime peer connections need it to call back into this server. |
 | `--no-schedules` | Disable the cron runner outside dev mode. |
 | `--no-playground` | Skip the web playground and its build or HMR process. |
@@ -558,6 +561,33 @@ The command returns only the masked key and revokes the old credential
 immediately. Redeploy at once to inject the replacement; the current
 pod can't authenticate to Cursor in between.
 
+## mcp oauth
+
+`mcp oauth` authorizes a `defineConnection({ url, oauth: true })`
+connection with a browser PKCE flow. Tokens are written to
+`mcp-auth.json` under the agent-serve config dir (default
+`~/.config/agent-serve`). Pass `--store` to upsert matching
+`MCP_OAUTH_<CONNECTION>_*` secrets on the hosted deployment.
+
+```bash
+agentkit mcp oauth <connection> [--dir .] [--store] [--slug <slug>] [--team <id>]
+```
+
+`<connection>` is the `agent/mcp-connections/<connection>.ts` basename.
+`--slug` defaults to the `--dir` basename. `--team` defaults to the
+signed-in account's team. You need `agentkit login` (or `--api-key`)
+before `--store`.
+
+Secret names are `MCP_OAUTH_<NAME>_ACCESS_TOKEN`,
+`_REFRESH_TOKEN`, and `_CLIENT_ID` (`<NAME>` is the connection id in
+upper snake case). Declare them in `hosting.secretNames` so deploy
+validation expects them. Secrets apply on the next deploy.
+
+Tokens are bound to the connection's resource URL. Changing the URL
+invalidates the local entry; run `mcp oauth` again.
+
+See the [Host MCP OAuth guide](../guides/mcp-oauth.md).
+
 ## secrets
 
 `secrets` manages environment secrets for a deployment.

package/docs/reference/connections.md

@@ -27,6 +27,33 @@ export default defineConnection({
 
 Tokens come from env vars. Never hardcode them in the file.
 
+## Host MCP OAuth
+
+For servers that speak OAuth, set `oauth: true` and authorize with the
+CLI. Tokens live in `~/.config/agent-serve/mcp-auth.json`. `--store`
+copies them onto the hosted deployment as `MCP_OAUTH_<NAME>_*` secrets.
+
+```ts
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  oauth: true,
+  hostOnly: true, // model cannot call; host.mcp still can
+});
+```
+
+```bash
+agentkit mcp oauth inventory           # browser PKCE → local mcp-auth.json
+agentkit mcp oauth inventory --store   # also upsert deployment secrets
+```
+
+Full walkthrough: [Host MCP OAuth](../guides/mcp-oauth.md). Companion
+skill: [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
+
+Use `hostOnly: true` when only deterministic host tools should call the
+server (deploys, admin APIs). Account MCP
+(`cursorAccount: true`) stays the right choice for connectors already
+linked in the Cursor dashboard.
+
 ## Local stdio MCP server
 
 Run a local MCP server as a child process with `command`.
@@ -72,8 +99,10 @@ author a `{ command }` MCP connection for those.
 > [!CAUTION]
 > Whoever can talk to the agent can drive these connectors, because they
 > are ordinary agent tools. `serve` refuses to start when
-> `--allow-anonymous` is combined with account MCP connections. Prefer
-> `--bearer-token` on shared hosts.
+> `--allow-anonymous` is combined with account MCP connections unless you
+> also pass `--allow-anonymous-cursor-account-mcp` (trusted boundary only —
+> e.g. an SSO proxy or the hosted alias token). Prefer `--bearer-token` on
+> shared hosts.
 
 ## Peer MCP connection
 
@@ -132,6 +161,7 @@ lazily on first use.
 
 Continue with these pages:
 
+- [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, `--store`, `hostOnly`
 - [Agent-to-agent](../guides/agent-to-agent.md): peers in depth
 - [Tools](./tools.md): authored tools that wrap MCP connections
 - [Webhooks](../guides/webhooks.md): calling MCP connections from handlers

package/docs/reference/prompt.md

@@ -0,0 +1,47 @@
+---
+title: "prompt"
+description: "Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors."
+---
+
+# `prompt`
+
+Authoring helper for long strings that live next to indented TypeScript:
+tool descriptions, reminder `prompt` fields, GitHub channel `context`,
+and error messages.
+
+```ts
+import { prompt } from "@cursor/july";
+// or: import { prompt } from "@cursor/july/prompt";
+```
+
+## `prompt\`…\``
+
+Returns a single dedented string. Common leading whitespace is stripped;
+a leading newline after the opening backtick is dropped so the usual
+multiline form stays readable in source.
+
+```ts
+throw new Error(prompt`
+  It is outside business hours (Mon–Fri 9am–5pm ET).
+  Use request_author_approval, or pass approval=human_request.
+`);
+```
+
+Blank lines inside the body are preserved. Relative indentation after the
+common prefix is kept (handy for nested bullet lists).
+
+When interpolating multi-line values (for example a list of services), give
+those lines the same indent as the `prompt` body so dedent stays consistent.
+
+## `prompt.lines\`…\``
+
+Same dedent rules, but returns `string[]` — one entry per line. Use this
+where an API wants separate lines (for example GitHub channel `context`):
+
+```ts
+context: prompt.lines`
+  Merged PR detected: ${pr.url} by ${author}.
+
+  Call plan_deploy, then follow its nextStep.
+`
+```

package/docs/reference/tools.md

@@ -39,6 +39,27 @@ code that runs it. With a Zod `inputSchema`, the input is validated before
 `execute` runs and the input type is inferred. A plain JSON Schema
 object is forwarded as-is and the input arrives as raw JSON.
 
+For multi-line descriptions, reminder prompts, and error messages, use
+[`prompt`](./prompt.md) so the string can sit indented with the surrounding
+TypeScript:
+
+```ts
+import { prompt } from "@cursor/july";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: prompt`
+    Inspect a pull request before approval.
+    Prefer this over guessing from the title alone.
+  `,
+  inputSchema: z.object({ prUrl: z.string().url() }),
+  async execute({ prUrl }) {
+    return { prUrl };
+  },
+});
+```
+
 ### The `ctx` parameter
 
 `execute` receives a `ctx` with the runtime accessors:

package/docs/troubleshooting.md

@@ -63,6 +63,17 @@ Match your symptom below. Keep the commands as `agentkit`; see
 | The bot ignores ordinary channel posts | Default engagement is mentions and DMs only. Enable `engagement.channelPosts` with an allowlist, and subscribe the app to `message.channels` / `message.groups`. |
 | Approve / Deny buttons do nothing | Re-import a Slack app manifest with interactivity enabled. Channels that post approval cards need `toolApprovals: true` (and `interactivity: true` when you compose events by hand). |
 
+## What if host MCP OAuth fails?
+
+| What you see | What to do |
+| --- | --- |
+| `must be defineConnection({ url, oauth: true })` | The connection file needs `oauth: true`, or you passed the wrong connection name to `agentkit mcp oauth`. |
+| Local auth works; hosted calls unauthorized | Run `agentkit mcp oauth <name> --store`, confirm names with `agentkit secrets list <slug>`, then redeploy. |
+| Model asks for `mcp_auth` or IDE MCP for a privileged server | That connection is likely `hostOnly`. Call it from a host tool via `ctx.host.mcp`, and update instructions. |
+
+See [Host MCP OAuth](./guides/mcp-oauth.md) and
+[`skills/mcp-auth/SKILL.md`](../skills/mcp-auth/SKILL.md).
+
 ## What if schedules, reminders, or approvals stall?
 
 | What you see | What to do |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -103,6 +103,13 @@
       "import": "./dist/hooks.js",
       "default": "./dist/hooks.js"
     },
+    "./prompt": {
+      "anysphere-source": "./src/prompt.ts",
+      "bun": "./src/prompt.ts",
+      "types": "./dist/prompt.d.ts",
+      "import": "./dist/prompt.js",
+      "default": "./dist/prompt.js"
+    },
     "./evals": {
       "anysphere-source": "./src/evals.ts",
       "bun": "./src/evals.ts",
@@ -213,4 +220,4 @@
     "vitest": "^4.0.18",
     "zustand": "^5.0.9"
   }
-}
+}

package/skills/create-agent/SKILL.md

@@ -15,8 +15,9 @@ Stand up one new agent project via a short interview, scaffold it, get
 channels working
 with the user, prove a turn runs end-to-end, and set up the improvement loop.
 Sibling skills: `framework-map` for orientation, `setup-slack` for Slack
-wiring, `github` for webhook-driven agents, `evals` for the eval API,
-`ab` for live A/B metrics, `hillclimb` for iteration once the agent runs.
+wiring, `mcp-auth` for host MCP OAuth, `github` for webhook-driven
+agents, `evals` for the eval API, `ab` for live A/B metrics, `hillclimb`
+for iteration once the agent runs.
 
 Read `framework-map/SKILL.md` first if you haven't; treat the package
 `AGENTS.md` and `README.md` as ground truth for
@@ -91,7 +92,10 @@ Defaults that make first cuts good:
 - **Tool per file**, filename = tool name the model sees. Prefer
   `execution: "server"` with a zod `inputSchema`; use `execution: "agent"`
   (script) only when the tool must run where the agent runs (or runtime is
-  cloud). Gate side-effecting tools with `needsApproval: true`.
+  cloud). Gate side-effecting tools with `needsApproval: true`. For long
+  tool descriptions, reminder prompts, channel `context`, and errors, use
+  `prompt\`…\`` / `prompt.lines\`…\`` from `@cursor/july` (dedents indented
+  multi-line strings).
 - **Env prefix** for Slack tokens = upper-snake slug (`my-agent` →
   `MY_AGENT_SLACK_*`); `agentkit slack init` derives it for you.
 - **Host prep beats model wandering:** when the purpose has a deterministic

package/skills/framework-map/SKILL.md

@@ -139,6 +139,7 @@ folder mounts every sibling agent too.
 - Live A/B metrics → `packages/agent-serve/skills/ab/SKILL.md`
 - GitHub webhooks → `packages/agent-serve/skills/github/SKILL.md`
 - Slack → `packages/agent-serve/skills/setup-slack/SKILL.md`
+- Host MCP OAuth → `packages/agent-serve/skills/mcp-auth/SKILL.md`
 - Local triage → `packages/agent-serve/skills/debug/SKILL.md`
 - Measured improvement → `packages/agent-serve/skills/hillclimb/SKILL.md`
 - Dogfood / deploy → `packages/agent-serve/skills/operate/SKILL.md`

package/skills/mcp-auth/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: agentkit-mcp-auth
+description: >-
+  Authorize host MCP OAuth for defineConnection({ url, oauth: true }):
+  agentkit mcp oauth, local mcp-auth.json, --store deployment secrets,
+  hostOnly, and egress. Read when wiring or debugging MCP auth.
+---
+
+# Host MCP OAuth (mcp auth)
+
+Use this skill when a human asks to authorize a remote MCP server on an
+agentkit host, store credentials for Cursor-managed hosting, or debug
+`host.mcp` auth failures for `oauth: true` connections.
+
+Sibling skills: `framework-map` for layout, `create-agent` when scaffolding,
+`debug` for unrelated local failures, `operate` for deploy/secrets ops.
+
+Docs: `docs/guides/mcp-oauth.md`, `docs/reference/connections.md`,
+`docs/reference/cli.md#mcp-oauth`.
+
+## When to use host OAuth vs account MCP
+
+| Need | Use |
+| --- | --- |
+| Connector already in Cursor dashboard (Linear, Notion, …) | `defineConnection({ cursorAccount: true, servers: […] })` |
+| Remote URL that speaks OAuth; host must hold tokens | `defineConnection({ url, oauth: true })` + this skill |
+| Static bearer / API key | `headers` / env on a plain `{ url }` connection |
+
+Prefer `hostOnly: true` when only host tools / channel handlers should
+call the server (admin APIs, privileged writes). The model will not see
+those tools.
+
+## Goal checklist
+
+- [ ] `agent/mcp-connections/<name>.ts` with `url` + `oauth: true` (+ `hostOnly` if privileged)
+- [ ] `hosting.secretNames` lists `MCP_OAUTH_<NAME>_{ACCESS_TOKEN,REFRESH_TOKEN,CLIENT_ID}` when you will `--store`
+- [ ] Hosted engines that reach non-bootstrap hosts declare `hosting.egressDomains`
+- [ ] Local: `agentkit mcp oauth <name>` succeeds
+- [ ] Hosted: `agentkit mcp oauth <name> --store` then redeploy; `secrets list` shows the names
+
+## Phase 0 — Author the connection (agent)
+
+```ts
+// agent/mcp-connections/inventory.ts
+import { defineConnection } from "@cursor/july/connections";
+
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  oauth: true,
+  hostOnly: true,
+  description: "Privileged inventory MCP; call via ctx.host.mcp only.",
+});
+```
+
+In `agent/agent.ts`:
+
+```ts
+hosting: {
+  egressDomains: ["mcp.example.com"], // if hosted + non-bootstrap host
+  secretNames: [
+    "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
+    "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
+    "MCP_OAUTH_INVENTORY_CLIENT_ID",
+  ],
+},
+```
+
+Naming: connection file `inventory.ts` → env prefix `MCP_OAUTH_INVENTORY`.
+Do **not** put `CURSOR_*` or hosted-storage names in `secretNames`.
+
+Wire privileged calls through host tools:
+
+```ts
+await ctx.host.mcp.callTool("inventory", "list_warehouses", {
+  region: input.region,
+});
+```
+
+Update instructions so the model does not hunt IDE MCP namespaces or
+`mcp_auth` for `hostOnly` servers.
+
+## Phase 1 — Local authorize (agent + human)
+
+```bash
+cd <agent-project>
+agentkit mcp oauth <connection>
+```
+
+Human completes the browser login. Callback:
+`http://localhost:8787/callback`. Tokens:
+`~/.config/agent-serve/mcp-auth.json` (or `$AGENT_SERVE_CONFIG_DIR`).
+
+Already authorized → command prints that and exits 0. URL change →
+re-run; resource URL binding drops the old entry.
+
+## Phase 2 — Store on the deployment (agent + human)
+
+Requires `agentkit login` (or `CURSOR_API_KEY`) and deploy rights.
+
+```bash
+agentkit mcp oauth <connection> --store [--slug <slug>] [--team <id>]
+agentkit secrets list <slug>
+agentkit deploy   # or your usual deploy; secrets apply next deploy
+```
+
+`--store` upserts access (required), refresh (if present), and client id
+(if present). It does not remove unrelated secrets.
+
+## Phase 3 — Verify (agent)
+
+Local:
+
+```bash
+agentkit validate --dir .
+agentkit call <tool-that-uses-host.mcp> --dir .
+# or exercise the same path from the playground
+```
+
+Hosted: confirm egress allowlist includes the MCP host, secrets exist,
+redeploy completed, then exercise the same host tool once.
+
+## Failure table
+
+| Symptom | Fix |
+| --- | --- |
+| `must be defineConnection({ url, oauth: true })` | Wrong connection name, or missing `oauth: true` |
+| `Unknown MCP connection` | Filename under `agent/mcp-connections/` must match CLI arg |
+| Callback hang | Free port 8787; finish browser flow on this machine |
+| Hosted 401 / unauthorized | `secrets list`; re-run `--store`; redeploy |
+| Model invents `mcp_auth` / IDE MCP | Connection is `hostOnly`; fix instructions + use host tools |
+| Tokens ignored after URL edit | Expected; run `mcp oauth` again for the new resource URL |
+
+## Don't
+
+- Don't put raw OAuth tokens in git or in connection source files
+- Don't add `BUGBOTDB_URL` / `AGENT_SERVE_DEPLOYMENT_ID` to `secretNames`
+- Don't use Bun for the CLI (use Node / `tsx`)
+- Don't expect `--store` alone to restart a running engine; redeploy