@cursor/july 0.1.1

package/docs/reference/channels.md

@@ -0,0 +1,206 @@
+---
+title: "Channels"
+description: "The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies."
+---
+
+# Channels
+
+A channel is the surface an agent lives on. The built-in HTTP session
+channel is always mounted. Custom channels declare their own routes
+under `/v1/channels/<id>`. The Slack and GitHub packs are prebuilt
+channels with platform transports. This page is the authoring reference;
+for the walkthrough, see the [Webhooks guide](../guides/webhooks.md).
+
+## The built-in HTTP channel
+
+It's always mounted, under `/<slug>` in the default multi-agent layout:
+session create, follow-up, stream, stop, the sessions list, approvals,
+deterministic tool calls, health, and info. For the route-by-route
+contract, see the [HTTP API reference](./http-api.md).
+
+Author `agent/channels/http.ts` only to override its defaults:
+
+```ts
+import {
+  bearerAuth,
+  httpChannel,
+  localDevStrict,
+} from "@cursor/july/channels";
+
+export default httpChannel({
+  auth: [localDevStrict(), bearerAuth(process.env.AGENT_TOKEN ?? "")],
+  onMessage: (message, { auth }) =>
+    `[caller ${auth?.principalId ?? "anonymous"}] ${message}`,
+});
+```
+
+## Define a custom channel
+
+Author `agent/channels/<id>.ts`. The filename is the channel id and the
+route prefix:
+
+```ts
+import { defineChannel, POST } from "@cursor/july/channels";
+import { z } from "zod";
+
+export default defineChannel({
+  routes: [
+    POST("/review", {
+      description: "Review a pull request on this channel",
+      bodySchema: z.object({
+        message: z.string(),
+        prUrl: z.string().url(),
+        thread: z.string().optional(),
+      }),
+      handler: async (_req, { callTool, send, body }) => {
+        const prepared = await callTool("inspect_pr", {
+          prUrl: body.prUrl,
+        });
+        if (prepared.isError) {
+          return Response.json(
+            { error: prepared.errorMessage ?? "Could not inspect pull request" },
+            { status: 502 }
+          );
+        }
+
+        const session = await send(
+          `${body.message}\n\nRead pr.json before answering.`,
+          {
+            continuationToken: body.thread ?? `pr:${body.prUrl}`,
+            workspaceFiles: {
+              "pr.json": JSON.stringify(prepared.result, null, 2) ?? "null",
+            },
+          }
+        );
+        return Response.json({ sessionId: session.id });
+      },
+    }),
+  ],
+  events: {
+    "message.completed"(event, channel, ctx) {
+      // deliver the reply to the surface that owns this channel
+    },
+  },
+  // auth: [...], state: {...}, onStart(...), onStop(...)
+});
+```
+
+This example assumes `agent/tools/inspect_pr.ts` exists. The handler
+calls it before the model turn, so every review starts with validated PR
+data. It also derives a stable conversation key from the PR URL and
+writes the tool result to `pr.json`. Instructions can ask the model to
+inspect a PR, but host code guarantees it.
+
+## Route verbs and schemas
+
+`GET`, `POST`, `PUT`, `PATCH`, and `DELETE` helpers build routes. Their
+schemas are Zod, enforced at compile time:
+
+| Verb                     | Required schema                       |
+| ------------------------ | ------------------------------------- |
+| `GET`                    | `querySchema`                         |
+| `POST` / `PUT` / `PATCH` | `bodySchema` (optional `querySchema`) |
+| `DELETE`                 | both optional                         |
+
+Plain JSON Schema objects won't type-check; use `z.object({})` or
+`z.unknown()` for intentionally open surfaces. The host validates before
+the handler runs. Handlers receive typed `args.body` and `args.query`,
+and empty POST bodies are coerced to `{}` first. Declared schemas are
+projected on `GET /v1/info`, which powers the playground's **Try**
+buttons and composer **slash commands**.
+
+## Handler arguments
+
+Handlers receive the Fetch `Request` and an args object:
+
+| Member                              | What it is                                                                                                                                                                                                                                                                                  |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `send(message, options?)`           | Run a model turn on this channel; returns the session handle. Options: `continuationToken` (the conversation key), `workspaceFiles`, `workspaceDir`, `cloud` (attach cloud repos for this session), `auth` (defaults to the request principal), `sdkAgentId` (resume a specific SDK agent). |
+| `getSession(sessionId)`             | Look up an existing session on this channel                                                                                                                                                                                                                                                 |
+| `receive(channelDefinition, input)` | Hand off to another channel (schedules use this)                                                                                                                                                                                                                                            |
+| `callTool(name, input, options?)`   | Deterministic server-tool call ([Tools](./tools.md#call-a-tool-without-a-model-turn))                                                                                                                                                                                                       |
+| `body`, `query`, `params`           | Validated payloads and `:param` path segments                                                                                                                                                                                                                                               |
+| `auth`                              | The `AuthContext` resolved by this route's auth chain                                                                                                                                                                                                                                       |
+| `requestIp`                         | The TCP peer address                                                                                                                                                                                                                                                                        |
+| `host`                              | Shared services: `host.mcp`, `host.github`, `host.slack`, `host.reminders`                                                                                                                                                                                                                  |
+| `waitUntil(promise)`                | Background work that outlives the response                                                                                                                                                                                                                                                  |
+| `sessionUrls(request, sessionId)`   | Absolute playground + trace URLs for a session on this mount                                                                                                                                                                                                                                |
+
+## Events
+
+The `events` map subscribes the channel to stream events for the
+sessions it owns. Keys are event types from the
+[event vocabulary](./sessions.md#the-event-vocabulary), or `"*"`.
+Handlers receive `(event, channel, ctx)`, where `channel.state` is the
+per-session adapter state and `ctx` exposes session info and host
+services. This is where a channel delivers replies back to its surface.
+
+## State and lifecycle
+
+`state` declares the starting per-session adapter state (JSON), persisted
+on the session record. Routes and event handlers read and mutate it
+through `channel.state`. `onStart(args)` runs when the channel mounts. It
+receives `send`, `receive`, `callTool`, `host`, and friends; the Slack
+pack opens its Socket Mode connection here. `onStop()` runs when the
+server drains.
+
+## Auth policies
+
+Every route runs an auth-policy chain: the channel's `auth` array, or
+`[localDevStrict()]` when unset. A policy is a function
+`(request, info) => AuthContext | null` (async allowed); the first
+non-null wins, and a request no policy admits gets `401`.
+
+| Policy              | Admits                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `localDevStrict()`  | Direct loopback callers with no proxy-forwarding headers (`X-Forwarded-For`, `X-Real-IP`, `Forwarded`, and `X-Forwarded-Host` are all rejected, so tunnels and same-host reverse proxies don't silently re-expose the route), plus a loopback `Host` header, which rejects DNS-rebinding callers that reach 127.0.0.1 with a remote hostname. |
+| `localDev()`        | Like `localDevStrict()` but without the `Host` check. An explicit, weaker opt-in.                                                                                                                                                                                                                                                                          |
+| `loopbackOnly()`    | A loopback TCP peer, ignoring forwarding headers; for dev relays that legitimately carry them, like `gh webhook forward`.                                                                                                                                                                                                                                  |
+| `bearerAuth(token)` | `Authorization: Bearer <token>`, compared in constant time. Also accepts a verifier function mapping a presented token to an `AuthContext`.                                                                                                                                                                                                                |
+| `allowAll()`        | Everyone, as an `anonymous` principal. Only for surfaces protected upstream (an HMAC-verified webhook) or intentionally public.                                                                                                                                                                                                                            |
+
+The resolved `AuthContext` (`{ authenticator, principalId,
+principalType, attributes? }`) becomes the request principal. Sessions
+bind to the principal that created them, and follow-up, stream, and list
+routes enforce ownership (`403` otherwise).
+
+Server flags interact with authored auth: `--bearer-token` swaps the
+default `localDevStrict()` for `bearerAuth(...)` on channels that don't
+author their own chain, and `--allow-anonymous` swaps it for
+`allowAll()`. Authored `auth` arrays always win over both. A channel that
+declares `[localDevStrict()]` stays loopback-only even on an
+`--allow-anonymous` host.
+
+## First class channels
+
+**Slack** (`@cursor/july/channels/slack`): Socket Mode
+transport, streaming replies, engagement rules, approval cards. Author
+`agent/channels/slack.ts` with `slackChannel()`. Guide:
+[Slack](../guides/slack.md).
+
+**GitHub** (`@cursor/july/channels/github`): webhook dispatch
+with signature verification, per-event hooks returning `{ auth }` (a
+model turn), `{ task }` (host work), or `null`, and CLI tooling for
+replay and live forwarding. Author `agent/channels/github.ts` with
+`githubChannel()`. Guide: [GitHub](../guides/github.md).
+
+For other platforms like Discord or Teams, use the authored
+`defineChannel` webhook form.
+
+## Continuation semantics
+
+Channels own their continuation-token format. The built-in HTTP channel
+mints opaque rotating tokens, Slack uses `channelId:threadTs`, and PR
+automations use keys like `pr:owner/repo#N`. Same token, same durable
+session; one active continuation per session; the HTTP channel returns
+`409` for stale tokens. For the full session model, see
+[Sessions](./sessions.md).
+
+## What's next
+
+Continue with these pages:
+
+- [Webhooks guide](../guides/webhooks.md): the same API, walked through
+- [HTTP API](./http-api.md): the built-in routes precisely
+- [Sessions and streaming](./sessions.md): the events channels
+  subscribe to

package/docs/reference/cli.md

@@ -0,0 +1,257 @@
+---
+title: "CLI"
+description: "Every agentkit command and the flags that matter, from serve and run to the slack and github packs."
+---
+
+# CLI reference
+
+Run the CLI with Node 22.13+. `agentkit help` prints the
+built-in summary, and most commands print their own usage when a
+required argument is missing.
+
+| Command                                                 | Description                                           |
+| ------------------------------------------------------- | ----------------------------------------------------- |
+| [`serve`](#serve)                                       | Serve agents over HTTP (multi-agent by default)       |
+| [`chat`](#chat)                                         | Talk to a running server from the terminal            |
+| [`run`](#run)                                           | One-shot turn on an ephemeral server; JSON trajectory |
+| [`call`](#call)                                         | Call a server tool directly, no model turn            |
+| [`eval`](#eval)                                         | Run filesystem evals                                  |
+| [`trajectory`](#trajectory)                             | Summarize a saved events.ndjson                       |
+| [`init`](#init)                                         | Scaffold a project (or print the setup guide)         |
+| [`info`](#info)                                         | Print the discovered agent surface                    |
+| [`validate`](#validate)                                 | Check the project; non-zero exit on errors            |
+| [`login` / `logout` / `whoami`](#login--logout--whoami) | Manage the host's Cursor credential                   |
+| [`slack …`](#slack)                                     | Slack pack: init, manifests, doctor                   |
+| [`github …`](#github)                                   | GitHub pack: forward, replay, events, doctor          |
+
+The flags shared across commands: `--dir <path>` (project root, default
+`.`), `--json` (machine output where supported), `--url <baseUrl>`
+(target a running server instead of starting one), `--bearer-token`
+(require it on `serve`; send it from `chat`, `run`, `eval`, and `call`),
+and `--state-root <path>` (durable state directory, default
+`<dir>/.agentkit`).
+
+## serve
+
+`serve` hosts every agent under a directory, multi-agent by default.
+
+```bash
+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]
+                  [--public-url <url>] [--no-schedules] [--no-playground]
+                  [--no-docs] [--cursor-events --repo owner/name]
+```
+
+Serves every agent under `--dir`. A directory that is itself an agent
+project mounts under its directory name; a directory of projects mounts
+each child. The index lives at `/`, each agent at `/<slug>/v1/*` and
+`/<slug>/playground`. On a TTY, press Enter to restart; it reloads
+agent code.
+
+| Flag                | Meaning                                                                                                                                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--dev`             | Dev mode. Schedules and reminders never auto-fire (dispatch through `/v1/dev/...`), the playground session list widens (loopback), GitHub channels accept unsigned loopback deliveries, and Vite HMR starts when the toolchain is present. |
+| `--mode`            | `multi` (default: slugged routes plus an index) or `single` (one agent at the unslugged `/v1/*`).                                                                                                                                          |
+| `--api-key`         | Cursor API key. Falls back to `CURSOR_API_KEY`, then the stored `login` credential.                                                                                                                                                        |
+| `--bearer-token`    | Require this bearer token on API routes; replaces the loopback-only default on channels without authored auth. Mutually exclusive with `--allow-anonymous`.                                                                                |
+| `--allow-anonymous` | Admit every HTTP caller as one `anonymous` principal. Trusted networks only.                                                                                                                                                               |
+| `--public-url`      | The base URL where this host is reachable from outside. Required for peer MCP connections on cloud-runtime turns.                                                                                                                          |
+| `--no-schedules`    | Disable the cron runner outside dev mode.                                                                                                                                                                                                  |
+| `--no-playground`   | Skip the web playground (and its auto-build / HMR).                                                                                                                                                                                        |
+| `--no-docs`         | Skip the documentation site at `/docs` (and its auto-build).                                                                                                                                                                               |
+| `--cursor-events`   | Pull SCM webhook events from Cursor's `/v0/scm-events` instead of receiving webhooks. Requires a signed-in host and `--repo` (repeatable). Offset state lives under `<state-root>/cursor-events/`.                                         |
+
+## chat
+
+`chat` talks to a running server from the terminal.
+
+```bash
+agentkit chat --url http://127.0.0.1:3000/<slug>            # interactive REPL
+agentkit chat --url … --message "Is the PR ready to approve?"       # one-shot
+agentkit chat --url … --message "hello" --json              # JSON trajectory
+agentkit chat --url https://host --bearer-token "$TOKEN"    # authed server
+```
+
+Streams the reply live: text, tool calls, and a per-turn usage footer.
+`--json` requires `--message` and prints
+`{ ok, sessionId, continuationToken, trajectory }`. `--text` prints a
+compact dump, and `--no-color` forces plain output.
+
+## run
+
+`run` executes one turn on an ephemeral server and prints a JSON trajectory.
+
+```bash
+agentkit run --dir . --message "Is https://github.com/acme/checkout/pull/42 ready?"
+agentkit run --dir . --message "first" --message "then this"   # multi-turn
+agentkit run --url http://127.0.0.1:3000/<slug> --message "…"  # running server
+agentkit run --dir . --message "…" --events /tmp/run.ndjson    # custom trace path
+```
+
+The create-and-test loop in one command: start an ephemeral server
+(port 0, temp state root outside the project), send the message(s), print a
+JSON trajectory, and write an NDJSON trace (default
+`<dir>/.agentkit/traces/<sessionId>.ndjson`). Progress streams to
+stderr on a TTY.
+
+| Flag                                 | Meaning                                                                                       |
+| ------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `--message`                          | The user message; repeatable for multi-turn. `--messages-file` takes a JSON array of strings. |
+| `--session` / `--continuation-token` | Follow up an existing session on a running server.                                            |
+| `--events <file>` / `--no-events`    | Override the trace path, or skip the trace.                                                   |
+| `--text`                             | Compact text output instead of JSON.                                                          |
+| `--timeout-ms`                       | Abort a hung turn.                                                                            |
+| `--no-stream`                        | Silence live progress on stderr.                                                              |
+| `--slug`                             | Pick one agent when `--dir` mounts several.                                                   |
+
+## call
+
+`call` invokes a server tool directly, with no model turn.
+
+```bash
+agentkit call inspect_pr --dir . \
+  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
+agentkit call inspect_pr --url http://127.0.0.1:3000/<slug> --input '{…}'
+agentkit call inspect_pr --dir . --input '{…}' --session ses_…
+```
+
+Deterministic server-tool invocation through `POST /v1/tools/:toolName`:
+schema-validated, in-process, no model turn, no API key. `--session`
+runs it inside an existing session and records it on that session's
+stream (serializing with model turns). See
+[Tools](./tools.md#call-a-tool-without-a-model-turn).
+
+## eval
+
+`eval` runs the project's filesystem evals.
+
+```bash
+agentkit eval --dir . --list          # discovered datapoints
+agentkit eval --dir .                 # run all
+agentkit eval --dir . builds/checkout # one datapoint
+agentkit eval --dir . builds          # every datapoint in the file
+agentkit eval --dir . --tag smoke     # by tag (repeatable)
+agentkit eval --dir . --json          # machine-readable results
+agentkit eval --dir . --verbose       # stream t.log lines + reply snippets
+```
+
+Runs `evals/**/*.eval.{ts,js}` on an ephemeral server, or against `--url`.
+Select by exact case id, file id (a prefix), several of either, tags, or
+nothing for all. See [Evals](../evals.md).
+
+## trajectory
+
+`trajectory` summarizes a saved event stream.
+
+```bash
+agentkit trajectory --events /tmp/run.ndjson [--text]
+```
+
+Turns any saved NDJSON event stream into the same trajectory JSON `run`
+prints.
+
+## init
+
+`init` scaffolds a new project.
+
+```bash
+agentkit init ./my-agent   # scaffold package.json + agent/ + a demo tool
+agentkit init              # no directory: print the setup guide
+```
+
+Refuses to overwrite existing files.
+
+## info
+
+`info` prints the discovered agent surface.
+
+```bash
+agentkit info --dir . [--json]
+```
+
+The discovered surface: model, instructions size, tools, skills, MCP
+connections, subagents, channels and their routes, schedules, hooks, and
+diagnostics. `--json` matches `GET /v1/info`; with multiple agents it
+prints one entry per slug.
+
+## validate
+
+`validate` checks the project and sets the exit code.
+
+```bash
+agentkit validate --dir .
+```
+
+Prints diagnostics per agent and exits non-zero when any has
+error-severity diagnostics (`serve` refuses to start in that state).
+Warnings (cloud runtime combined with local-only capabilities, say) print
+without failing it.
+
+## login / logout / whoami
+
+Three commands manage the host's Cursor credential.
+
+```bash
+agentkit login [--api-key <key>] [--key-name <name>]
+agentkit whoami [--json]
+agentkit logout
+```
+
+`login` signs the host in to Cursor: browser sign-in mints a named,
+dashboard-revocable API key, and only the key is stored (the default
+name is `agentkit (<hostname>)`). It powers inference, the cloud
+runtime, and Cursor account MCP connections. `whoami` shows which credential
+is active and why: explicit flag, then `CURSOR_API_KEY`, then the
+stored login. `logout` removes the stored key.
+
+Non-production backends: login and account RPCs honor
+`CURSOR_API_BASE_URL` while the SDK harness honors `CURSOR_BACKEND_URL`.
+Set both to the same URL, or keys minted on one backend are rejected by
+the other.
+
+## slack
+
+The `slack` subcommands generate and verify the Slack side of a channel.
+
+```bash
+agentkit slack setup                              # guided checklist
+agentkit slack init --dir . --name "My Agent"     # channel + manifests + env.example
+agentkit slack init --dir . --no-prefix           # shared SLACK_* vars
+agentkit slack init --dir . --channel-posts       # + message.channels/groups events
+agentkit slack manifest --env dev|prod|both       # regenerate manifests
+agentkit slack doctor --prefix MY_AGENT           # token / connectivity checks
+```
+
+See the [Slack guide](../guides/slack.md).
+
+## github
+
+The `github` subcommands test webhook channels against real repositories.
+
+```bash
+agentkit github doctor [--install]                # gh + cli/gh-webhook extension
+agentkit github events --dir . [--json]           # per-agent URL + event list
+agentkit github forward --dir . [--repo owner/repo | --org ORG]
+agentkit github replay <pr-url|owner/repo#N> --dir .
+    [--events a,b,c|'*'] [--action …] [--conclusion …] [--comment …]
+    [--context …] [--secret …] [--dry-run] [--out DIR]
+```
+
+`forward` wraps `gh webhook forward`: repo admin required, and blank
+any env `GITHUB_TOKEN` / `GH_TOKEN` or deliveries 401. `replay`
+synthesizes GitHub-shaped payloads from read access only, the
+deterministic tier. `--slug` and `--channel` target one agent among
+several. See the [GitHub guide](../guides/github.md).
+
+## Environment variables
+
+These are the most common environment variables the CLI and the
+channel packs read.
+
+| Variable                                                                  | Meaning                                                                      |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `CURSOR_API_KEY`                                                          | The Cursor credential, checked after `--api-key` and before the stored login |
+| `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` / `GITHUB_APP_INSTALLATION_ID` | GitHub App auth for outbound API calls                                       |
+| `GITHUB_TOKEN` / `GH_TOKEN`                                               | Token auth for outbound API calls; must be blank for `github forward`        |
+| `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN`                                     | Slack tokens (single-agent); `<PREFIX>_SLACK_*` per agent otherwise          |

package/docs/reference/connections.md

@@ -0,0 +1,137 @@
+---
+title: "MCP Connections"
+description: "Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."
+---
+
+# 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.
+
+## Remote MCP server
+
+Point an MCP connection at a remote server with a URL.
+
+```ts
+import { defineConnection } from "@cursor/july/connections";
+
+export default defineConnection({
+  url: "https://mcp.linear.app/mcp",
+  headers: { authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
+});
+```
+
+Tokens come from env vars. Never hardcode them in the file.
+
+## Local stdio MCP server
+
+Run a local MCP server as a child process with `command`.
+
+```ts
+export default defineConnection({
+  command: "node",
+  args: ["--import", "tsx", "mcp/units-server.ts"],
+  // env, cwd
+});
+```
+
+This suits small purpose-built servers, like a `units` converter
+shipped next to the agent.
+
+## Cursor account MCP connection
+
+`{ cursorAccount: true }` exposes the MCP connectors the signed-in
+Cursor account already authorized (dashboard → MCP): Linear, Notion,
+Slack, and the rest, without any token configuration. Every tool executes on
+the Cursor backend with the account's stored OAuth credentials, so raw
+tokens never reach the serve host, session workspaces, or traces.
+
+```ts
+// agent/mcp-connections/cursor.ts
+export default defineConnection({ cursorAccount: true, servers: ["Linear"] });
+```
+
+The host must be signed in (`agentkit login` or `CURSOR_API_KEY`);
+`serve` fails fast at startup otherwise, and logs each connector's live
+status (`connected`, `needsAuth`, `error`) as it starts. The optional
+`servers` list restricts which connectors are exposed.
+
+Local turns and host-side calls go through a loopback bridge guarded by
+a per-startup secret. Cloud-runtime turns reach the same bridge through
+the serve `--public-url`, so `servers` filters apply there too. A
+cloud-capable agent that combines a `servers` filter with no
+`--public-url` fails at startup rather than running unfiltered. Backend
+execution covers the
+account's HTTP/SSE servers. Stdio servers can't run server-side, so
+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.
+
+## 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:
+
+```ts
+export default defineConnection({
+  agent: "weather-agent",
+  description: "Delegate weather questions to the weather agent.",
+});
+```
+
+Unknown slugs and self-references fail `serve` at startup. Resolution
+(loopback versus `--public-url`), loop caveats, and the delegation model
+are in the [Agent-to-agent guide](../guides/agent-to-agent.md).
+
+## Every MCP connection is available in three places
+
+One authored MCP connection serves three consumers.
+
+1. **Cursor agent:** Local or cloud turns see the MCP connection
+   through SDK `mcpServers`, and the model calls its tools directly.
+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 });
+     },
+   });
+   ```
+
+3. **Channel and schedule handlers:** Webhooks hit MCP servers with no
+   model turn at all, through `args.host.mcp`:
+
+   ```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.
+
+## What's next
+
+Continue with these pages:
+
+- [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