eve 0.90.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,7 +3,7 @@ title: "State"
3
3
  description: "Durable per-session memory with defineState: get() and update(), persisted across step boundaries."
4
4
  ---
5
5
 
6
- `defineState` is a typed, named slot of durable per-session memory for an agent. Use it when the agent has to remember something between conversation turns (a running budget, a glossary, a checklist) and you don't want to stand up an external store for it. The values survive workflow step boundaries, so they outlast crashes, redeploys, and days-long sessions.
6
+ `defineState` declares a typed, named slot of per-session memory. Use it when the agent has to remember something between turns, such as a running budget, a glossary, or a checklist, without an external store. Values survive crashes, redeploys, and days-long sessions.
7
7
 
8
8
  ```ts
9
9
  import { defineState } from "eve/context";
@@ -11,12 +11,12 @@ import { defineState } from "eve/context";
11
11
  const budget = defineState("my-agent.budget", () => ({ count: 0, cap: 25 }));
12
12
  ```
13
13
 
14
- Pass `defineState(name, initial)` a stable string `name` (namespace it to your agent) and an `initial` function that produces the starting value the first time the slot is read. You get back a `StateHandle<T>`:
14
+ Pass `defineState(name, initial)` a stable string `name`, namespaced to your agent, and an `initial` function that produces the starting value. It returns a `StateHandle<T>`:
15
15
 
16
16
  - `get()`: read the current value. Returns `initial()` on first access within a context.
17
17
  - `update(fn)`: replace the value with `fn(current)`.
18
18
 
19
- Declare the handle once at module scope and import it wherever you read or write the slot. Use it from inside a tool, hook, or other framework-managed runtime code:
19
+ Declare the handle once at module scope and import it wherever you read or write the slot:
20
20
 
21
21
  ```ts title="agent/lib/budget.ts"
22
22
  import { defineState } from "eve/context";
@@ -46,7 +46,7 @@ export default defineTool({
46
46
 
47
47
  ## Reset state between turns
48
48
 
49
- State is durable by default and does not reset between turns. If you want a clean slate every turn, overwrite it from a lifecycle [hook](../guides/hooks) on `turn.started`:
49
+ State persists across turns. For a clean slate every turn, overwrite it from a [hook](../guides/hooks) on `turn.started`:
50
50
 
51
51
  ```ts title="agent/hooks/reset-budget.ts"
52
52
  import { defineHook } from "eve/hooks";
@@ -69,20 +69,12 @@ Every [subagent](../subagents) starts with its own fresh state, whether it's a b
69
69
 
70
70
  ## State vs. connection-side storage
71
71
 
72
- `defineState` holds conversation-scoped working memory that lives and dies with
73
- the session, including counters, the current plan, and what the user has told
74
- you this conversation. It is the agent's short-term memory, persisted durably
75
- for the life of the session. For context that must outlive a session, configure
76
- a first-class [memory provider](../memory). Use the built-in file provider, a
77
- third-party provider, or a custom provider for application-specific storage and
78
- retrieval. Use a general [connection](../connections) instead when the data
79
- should be queried only through explicit model tool calls rather than recalled
80
- automatically.
72
+ `defineState` holds working memory that lives and dies with the session, such as counters, the current plan, and what the user said. For context that must outlive a session, configure a [memory provider](../memory): the built-in file provider, a third-party provider, or a custom one. Use a [connection](../connections) instead when the model should query the data only through explicit tool calls rather than recall it automatically.
81
73
 
82
74
  ## What to read next
83
75
 
84
- - Vary capabilities per session → [Dynamic capabilities](../guides/dynamic-capabilities)
85
- - How step durability works → [Execution model & durability](../concepts/execution-model-and-durability)
76
+ - Vary tools, skills, and instructions per session → [Dynamic capabilities](../guides/dynamic-capabilities)
77
+ - How turns checkpoint and resume → [Execution model & durability](../concepts/execution-model-and-durability)
86
78
  - The `ctx` accessors available alongside state → [TypeScript API Reference](../reference/typescript-api)
87
79
  - Tenant-scoped long-term memory with any provider → [Multi-tenant memory](../patterns/multi-tenant-memory)
88
80
  - First-class recall, capture, and provider tools → [Memory](../memory)
@@ -3,101 +3,67 @@ title: "MCP Connections"
3
3
  description: "Connect an eve agent to a remote MCP server, authorize it with Vercel Connect or static credentials, and control which tools the model can discover."
4
4
  ---
5
5
 
6
- MCP connections point eve at a remote MCP server you do not author. The server publishes its tools and schemas, and the model finds them with `eve__search` and calls them with `eve__tool`.
6
+ An MCP connection gives your agent the tools of a remote MCP server you don't author. It lives in one file under `agent/connections/`. The server publishes its tools, and the model finds them with `eve__search` and calls them with `eve__tool`.
7
7
 
8
- Use MCP when the service already has an MCP server, when the server owns tool schemas dynamically, or when one connection should expose a family of related remote tools. Use an [OpenAPI connection](./openapi) instead when the service publishes an HTTP API contract and you want eve to generate one tool per operation.
8
+ Use MCP when the service has an MCP server that defines its own tools, or when one connection should expose a family of related tools.
9
9
 
10
10
  ## Define an MCP connection
11
11
 
12
- Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/linear.ts` registers as `linear`, and events report its tools as `linear__<tool>`.
12
+ The filename is the connection name, so `agent/connections/linear.ts` registers as `linear`, and events report its tools as `linear__<tool>`.
13
13
 
14
14
  ```ts title="agent/connections/linear.ts"
15
15
  import { connect } from "@vercel/connect/eve";
16
16
  import { defineMcpClientConnection } from "eve/connections";
17
17
 
18
18
  export default defineMcpClientConnection({
19
- url: "https://mcp.linear.app/mcp",
20
- description: "Linear workspace: issues, projects, cycles, and comments.",
21
- auth: connect("mcp.linear.app/linear"),
19
+ url: "https://mcp.linear.app/mcp", // required: Streamable HTTP or SSE endpoint
20
+ description: "Linear workspace: issues, projects, cycles, and comments.", // required
21
+ auth: connect("mcp.linear.app/linear"), // optional: omit for a public server
22
22
  });
23
23
  ```
24
24
 
25
- The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself: eve lists it next to the connection name, and it is the main signal the model uses to decide which connection to search.
26
-
27
- ## Configure protocol discovery
25
+ Write the `description` for the model. eve lists it next to the connection name, and the model uses it to decide which connection to search.
28
26
 
29
- eve discovers the server's MCP protocol by default. If a server rejects discovery with an unsupported protocol version error (`-32022`) and lists a handshake-based version eve supports, eve falls back to `initialize` with the newest version both sides support. If a server requires the older `initialize` handshake and does not report a supported version, disable discovery for that connection:
27
+ ### Options
30
28
 
31
- ```ts
32
- export default defineMcpClientConnection({
33
- url: "https://mcp.example.com/mcp",
34
- description: "Search support cases",
35
- protocolVersionDiscovery: false,
36
- });
37
- ```
29
+ The [shared connection options](../connections#options) apply, with `tools` as the filter. MCP adds these:
38
30
 
39
- With `protocolVersionDiscovery: false`, the client skips `server/discover` and starts with `initialize`, proposing `2025-11-25` and negotiating a supported handshake-based version. This is a per-connection setting; omitting it or setting it to `true` keeps discovery enabled. Remove the override when the server supports discovery. The setting also applies to connections returned by dynamic resolvers.
31
+ | Field | Default | What it does |
32
+ | -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
33
+ | `protocolVersionDiscovery` | `true` | Set `false` for a server that needs the `initialize` handshake. See [protocol discovery](#configure-protocol-discovery). |
34
+ | `forwardPrincipal` | `false` | Send the turn's user to another eve agent. See [Forward the caller](#forward-the-caller-to-an-eve-agent). |
35
+ | `experimental.events` | None | Run your code when the server sends an event. See [Events](#events-experimental). |
40
36
 
41
37
  ## Use Vercel Connect for OAuth
42
38
 
43
- For OAuth-backed MCP servers, use the shared [Vercel Connect flow](../connections#interactive-oauth-via-vercel-connect), then pass the returned connector UID to `connect()`. Keep the MCP runtime URL and Connect service identifier distinct. For example, Linear uses `https://mcp.linear.app/mcp` as the MCP endpoint and `mcp.linear.app` when creating the connector.
39
+ For an MCP server that uses OAuth, follow the shared [Vercel Connect flow](../connections#interactive-oauth-via-vercel-connect) and pass the connector UID to `connect()`. The MCP URL and the Connect service identifier differ. Linear uses `https://mcp.linear.app/mcp` as the endpoint and `mcp.linear.app` when you create the connector.
44
40
 
45
- `connect("...")` is user-scoped by default and requires an authenticated user on the active eve session. Use `connect({ connector, principalType: "app" })` when the server should act as the agent instead. The connections overview covers connector setup, session requirements, app and user scope, callback behavior, and troubleshooting.
41
+ By default, `connect("...")` uses each user's own sign-in, so the session needs a signed-in user. Use `connect({ connector, principalType: "app" })` to have the server act as the agent.
46
42
 
47
43
  ## When eve asks for sign-in
48
44
 
49
- eve asks the user to sign in only when the MCP server asks for it. When a connection has `auth` but no token yet, because its `getToken` throws `ConnectionAuthorizationRequiredError`, eve connects without an `Authorization` header and lists the server's tools. Any other error from `getToken` still fails the connection.
45
+ eve asks the user to sign in only when the MCP server asks for it. When the user has no token yet, `getToken` throws `ConnectionAuthorizationRequiredError`. eve then connects without an `Authorization` header and lists the server's tools. Any other `getToken` error fails the connection.
50
46
 
51
47
  - **The server rejects every request without a token.** Most hosted OAuth servers, such as Linear, GitHub, and Notion, answer `initialize` or `tools/list` with HTTP `401`. `eve__search` lists the connection as one result named after it, such as `linear`. Calling that name with `eve__tool({ name: "linear" })`, or any of its tools with `eve__tool`, asks the user to sign in.
52
48
  - **The server lists tools without a token.** `eve__search` returns its tools with no prompt, and `eve__tool` runs tools the server answers anonymously. Sign-in starts only when a tool call comes back with HTTP `401`, or with an error result that carries a `WWW-Authenticate` challenge in `_meta["mcp/www_authenticate"]`.
53
49
 
54
- After the user signs in, the turn resumes and the model makes the call again. eve reconnects with the token and reloads the tool list, which may now include tools the server hides from anonymous callers. A connection that already has a token sends it on every request, as before.
50
+ After the user signs in, the turn continues and the model retries the call. eve reconnects with the token and reloads the tool list, which may include tools the server hides from anonymous callers. Once a connection has a token, it sends the token on every request.
55
51
 
56
- eve resolves credentials before each MCP HTTP request, including requests on an existing client. When the cached token's `expiresAt` has passed, eve calls the token provider again. If the server rejects a bearer with HTTP `401`, eve evicts the cached token, asks the provider for another token, and retries the request once before asking for sign-in.
52
+ A server that leaves protected tools out of its anonymous `tools/list` never triggers sign-in, because the model can't find those tools. A server that supports anonymous use should list every tool and refuse the protected calls.
57
53
 
58
- Eviction clears eve's cached access token and calls the provider's optional `evict` hook. The provider controls whether it retains a refresh grant for silent renewal. Missing grants and rejected replacement tokens still use the normal authorization flow; HTTP `403` permission failures do not trigger token refresh or retries.
59
-
60
- A server that leaves protected tools out of its anonymous `tools/list` never triggers sign-in, because the model cannot find those tools. Servers that support anonymous use should list every tool and refuse the protected calls.
54
+ eve reuses a token until its `expiresAt` passes, then calls the token provider again. On HTTP `401`, eve calls the provider's optional `evict` hook, gets a new token, and retries once before it asks for sign-in. The provider decides whether to keep a refresh grant to renew tokens without a prompt. HTTP `403` never triggers a refresh or retry.
61
55
 
62
56
  ## Static tokens and headers
63
57
 
64
- MCP connections accept the shared connection `auth` and `headers` options. Use `auth.getToken` for a bearer token, `headers` for another scheme, and resolver functions when credentials or routing depend on the caller. See [Static-token auth](../connections#static-token-auth), [Headers](../connections#headers), and [Per-caller auth and headers](../connections#per-caller-auth-and-headers) for the canonical examples and token-lifecycle behavior.
65
-
66
- ## Application-provided tool arguments
67
-
68
- Some MCP servers require arguments that belong to the application rather than the model. For example, UCP servers expect the agent profile in `arguments.meta` on every tool call. Configure those values with `toolCall.providedArguments`:
69
-
70
- ```ts title="agent/connections/storefront.ts"
71
- import { defineMcpClientConnection } from "eve/connections";
72
-
73
- const profileUrl = "https://agent.example.com/.well-known/ucp";
74
-
75
- export default defineMcpClientConnection({
76
- url: "https://store.example.com/api/ucp/mcp",
77
- description: "Storefront catalog, carts, checkouts, and orders.",
78
- toolCall: {
79
- providedArguments: {
80
- meta: ({ session }) => ({
81
- "ucp-agent": {
82
- profile: `${profileUrl}?session=${encodeURIComponent(session.id)}`,
83
- },
84
- }),
85
- },
86
- },
87
- });
88
- ```
89
-
90
- Values may be JSON values, promises, or callbacks. Callbacks receive the active session context, the bare remote `toolName`, and a replay-stable `callId` that is unique to the tool call. Use `callId` when the remote server needs an idempotency key.
91
-
92
- eve treats configured keys as application-owned: it removes them from every remote tool's model-facing input schema and adds their resolved values immediately before execution. They apply to every tool call on the connection and replace any conflicting model value. Approval policies continue to receive only the model-authored input.
58
+ MCP connections accept the shared `auth` and `headers` options. Use `auth.getToken` for a bearer token, `headers` for another scheme, and resolver functions when credentials or routing depend on the caller. See [Static-token auth](../connections#static-token-auth), [Headers](../connections#headers), and [Per-caller auth and headers](../connections#per-caller-auth-and-headers).
93
59
 
94
60
  ## No auth
95
61
 
96
- Omit `auth` and `headers` only for an intentionally public or loopback MCP server. See [No auth](../connections#no-auth) for the shared connection behavior and security boundary.
62
+ Omit `auth` and `headers` only for an intentionally public or loopback MCP server. See [No auth](../connections#no-auth).
97
63
 
98
64
  ## Tool filters
99
65
 
100
- MCP servers can expose broad read and write surfaces. Narrow what the model can discover with exactly one of `tools.allow` or `tools.block`:
66
+ Narrow which server tools the model can discover with exactly one of `tools.allow` or `tools.block`:
101
67
 
102
68
  ```ts title="agent/connections/linear.ts"
103
69
  import { connect } from "@vercel/connect/eve";
@@ -111,17 +77,17 @@ export default defineMcpClientConnection({
111
77
  });
112
78
  ```
113
79
 
114
- Prefer `allow` for the smallest safe surface, especially when the server exposes write tools. Use `block` when the server has a broad stable surface and only a few tools should be hidden.
80
+ Prefer `allow` for the smallest safe surface, especially when the server exposes write tools. Use `block` to hide a few tools from a broad, stable surface.
115
81
 
116
82
  ## Approval gates
117
83
 
118
- Use the shared `approval` option to gate every tool served by an MCP connection. The [connections overview](../connections#per-connection-approval) defines the `never()`, `once()`, `always()`, and `auto()` helpers; [Human-in-the-loop](../human-in-the-loop#approvals) defines the pause-and-resume contract.
84
+ The shared `approval` option applies to every tool on an MCP connection. The [connections overview](../connections#per-connection-approval) defines the `never()`, `once()`, `always()`, and `auto()` helpers. [Human-in-the-loop](../human-in-the-loop#approvals) explains how a call waits for a person.
119
85
 
120
86
  ### Gate specific tools by name or input
121
87
 
122
- A remote MCP server usually mixes read tools with destructive or publishing ones, so a blanket `always()` would prompt on every harmless call. Pass a custom policy instead — the same [`Approval`](/docs/human-in-the-loop#approvals) shape authored tools use — to gate only the calls that matter. The policy receives `{ session, toolName, toolInput, toolAnnotations, callId, abortSignal }` and returns an approval status, synchronously or as a promise.
88
+ With `always()`, a server that mixes read tools with destructive ones prompts on every harmless call. Pass a custom policy instead, the same [`Approval`](/docs/human-in-the-loop#approvals) shape authored tools use, to ask only for the calls that matter. The policy receives `{ session, toolName, toolInput, toolAnnotations, callId, abortSignal }` and returns an approval status, directly or as a promise.
123
89
 
124
- This connection always gates deletes, gates a publish only when the call actually schedules a post, and lets everything else through:
90
+ This connection always asks before a delete, asks before a publish only when the call schedules a post, and lets everything else run:
125
91
 
126
92
  ```ts title="agent/connections/social.ts"
127
93
  import { defineMcpClientConnection } from "eve/connections";
@@ -154,16 +120,20 @@ export default defineMcpClientConnection({
154
120
  });
155
121
  ```
156
122
 
157
- Two details are specific to connection tools:
123
+ Two details differ from authored tools:
158
124
 
159
- - **`toolName` arrives qualified**, not as the bare remote name. An MCP tool surfaces to the policy as `<connection>__<tool>` (e.g. `social__delete_draft`), so match the bare tool name with `.includes()` or `.endsWith()` rather than `===`.
160
- - **`toolInput` is the raw input the model produced**, typed as `Record<string, unknown> | undefined`. With an authored tool you define the `inputSchema`, so its approval policy gets input typed and checked against your schema; a connection tool's schema is published by the remote MCP server, not you, so the shape is one you neither own nor can rely on. It is also `undefined` whenever the model's input isn't an object. Read nested fields defensively — as `publishesNow` does — instead of trusting the shape.
125
+ - **`toolName` is qualified** as `<connection>__<tool>`, such as `social__delete_draft`, so match the bare name with `.includes()` or `.endsWith()` rather than `===`.
126
+ - **`toolInput` is the model's raw input**, typed as `Record<string, unknown> | undefined`. The remote server owns the schema, so you can't rely on its shape, and it is `undefined` when the input isn't an object. Read nested fields defensively, as `publishesNow` does.
161
127
 
162
- Return `"user-approval"` (or `true`) to pause for a person and `"not-applicable"` (or `false`) to run without a prompt; return `"approved"` or `"denied"` to decide automatically without involving anyone.
128
+ | Return | Effect |
129
+ | ----------------------------- | ---------------------------- |
130
+ | `"user-approval"` or `true` | Pause for a person |
131
+ | `"not-applicable"` or `false` | Run without a prompt |
132
+ | `"approved"` or `"denied"` | Decide without asking anyone |
163
133
 
164
134
  ### Gate by the server's tool annotations
165
135
 
166
- Many MCP servers declare [tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool) such as `readOnlyHint` and `destructiveHint` for each tool. eve passes what the server declared for the called tool as `toolAnnotations`, typed as `ConnectionToolAnnotations` from `eve/tools/approval`. It is `undefined` when the server declares none, so keep a fallback:
136
+ Many MCP servers declare [tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool) such as `readOnlyHint` and `destructiveHint`. eve passes the called tool's annotations as `toolAnnotations`, typed as `ConnectionToolAnnotations` from `eve/tools/approval`. It is `undefined` when the server declares none, so keep a fallback:
167
137
 
168
138
  ```ts title="agent/connections/linear.ts"
169
139
  import { connect } from "@vercel/connect/eve";
@@ -180,13 +150,63 @@ export default defineMcpClientConnection({
180
150
  });
181
151
  ```
182
152
 
183
- Annotations are hints from the server, not guarantees. Trust them only as far as you trust the server that sent them.
153
+ Annotations are hints, not guarantees. Trust them only as far as you trust the server.
154
+
155
+ [Human-in-the-loop](/docs/human-in-the-loop#approvals) covers every status, how long an approval lasts, and `session.auth`.
156
+
157
+ ## Control result size
158
+
159
+ An MCP tool call returns the tool's `structuredContent` when the server sends it. Otherwise it returns the result's text, parsed as JSON when the tool declares no output schema. Image, audio, and resource content reaches the model as file parts, and a result with `isError: true` fails the call with its text. MCP connections have no per-result transform like an authored tool's [`toModelOutput`](/docs/tools#shape-what-the-model-sees-with-tomodeloutput).
160
+
161
+ When a remote tool returns more than the model needs, narrow the result at the server. Add a search or summary tool, or return a handle another call can use to fetch a smaller slice.
162
+
163
+ If you don't control the server, replace that operation with an authored tool that calls an equivalent upstream API. The authored tool can store the full payload outside model context and return only the needed fields through `toModelOutput`. Hide the original with [`tools.block`](#tool-filters) so the model doesn't see duplicate tools.
164
+
165
+ ## Application-provided tool arguments
166
+
167
+ Some MCP servers require arguments that come from the application, not the model. For example, UCP servers expect the agent profile in `arguments.meta` on every tool call. Set those values with `toolCall.providedArguments`:
168
+
169
+ ```ts title="agent/connections/storefront.ts"
170
+ import { defineMcpClientConnection } from "eve/connections";
171
+
172
+ const profileUrl = "https://agent.example.com/.well-known/ucp";
173
+
174
+ export default defineMcpClientConnection({
175
+ url: "https://store.example.com/api/ucp/mcp",
176
+ description: "Storefront catalog, carts, checkouts, and orders.",
177
+ toolCall: {
178
+ providedArguments: {
179
+ meta: ({ session }) => ({
180
+ "ucp-agent": {
181
+ profile: `${profileUrl}?session=${encodeURIComponent(session.id)}`,
182
+ },
183
+ }),
184
+ },
185
+ },
186
+ });
187
+ ```
188
+
189
+ Values may be JSON values, promises, or callbacks. Callbacks receive the session context, the bare remote `toolName`, and a `callId`. The `callId` is unique to the tool call and stays the same if eve runs the call again, so it works as an idempotency key.
190
+
191
+ The model doesn't see these keys in any tool's input schema. eve adds their values just before each call and overwrites any value the model sent. Approval policies see only the model's input.
192
+
193
+ ## Configure protocol discovery
194
+
195
+ By default, eve first asks the server which MCP protocol version it speaks. A server can answer with an unsupported protocol version error (`-32022`) that lists a handshake version eve supports. eve then uses `initialize` with the newest version both sides support. If the server needs the `initialize` handshake but lists no supported version, turn discovery off:
196
+
197
+ ```ts
198
+ export default defineMcpClientConnection({
199
+ url: "https://mcp.example.com/mcp",
200
+ description: "Search support cases",
201
+ protocolVersionDiscovery: false,
202
+ });
203
+ ```
184
204
 
185
- [Human-in-the-loop](/docs/human-in-the-loop#approvals) covers the full set of statuses, scoped approval state and `session.auth`, and how a gated call pauses and resumes durably.
205
+ With `protocolVersionDiscovery: false`, eve skips `server/discover` and starts with `initialize`. It proposes `2025-11-25` and agrees on a version the server supports. Dynamic connections can return this option too.
186
206
 
187
207
  ## Forward the caller to an eve agent
188
208
 
189
- When the server is another eve agent's [`mcpChannel`](../channels/mcp), set `forwardPrincipal: true` so its published tools run as the user of the current turn instead of as this deployment:
209
+ When the server is another eve agent's [`mcpChannel`](../channels/mcp), set `forwardPrincipal: true` so its tools run as the current turn's user instead of as this deployment:
190
210
 
191
211
  ```ts title="agent/connections/specialist.ts"
192
212
  import { defineMcpClientConnection } from "eve/connections";
@@ -199,19 +219,15 @@ export default defineMcpClientConnection({
199
219
  });
200
220
  ```
201
221
 
202
- eve sends the turn's user, and its initiator when that differs, in the `eve-forwarded-principal` header on every request. A turn with no caller, or an anonymous one, sends no header. The server must trust this deployment's route-authenticated identity in `trustedForwarders`; otherwise it refuses the request with `403`. See [Forwarded principals](../channels/mcp#forwarded-principals). A request carrying the header fails rather than follow a redirect, so the header never reaches another host. A principal over 16 KiB encoded fails the call before it is sent; trim its attributes.
203
-
204
- Authenticate the connection as this deployment, with a stable service credential, like the token above, not with user-scoped `connect("...")` or a per-caller resolver. eve resolves `auth` and `headers` once when it opens the client, but one client can serve turns from different users in a shared session, so the header is what names the user on each request. The server trusts the forwarder by that service identity, and grants the user's own access to downstream services itself.
205
-
206
- ## Control result size
222
+ The `eve-forwarded-principal` header on every request names the turn's user, and the person who started the session when that differs. An anonymous turn, or one with no caller, sends no header. The server must list the identity this deployment authenticates as in `trustedForwarders`, or it refuses the request with `403`. See [Forwarded principals](../channels/mcp#forwarded-principals).
207
223
 
208
- An MCP tool call returns the tool's `structuredContent` when the server sends it. Otherwise it returns the result's text, parsed as JSON when the tool declares no output schema. Image, audio, and resource content reaches the model as file parts, and a result with `isError: true` fails the call with its text. MCP connections do not expose a per-result transform equivalent to an authored tool's [`toModelOutput`](/docs/tools#shape-what-the-model-sees-with-tomodeloutput).
224
+ A request that carries the header fails instead of following a redirect, so the header never reaches another host. If the encoded user is over 16 KiB, the call fails before it is sent; trim the user's attributes.
209
225
 
210
- When a remote tool returns more data than the model needs, narrow the result at the MCP server. Prefer a purpose-built search or summary tool, or return a stable handle that another call can use to fetch a smaller slice. If you do not control the server and an equivalent upstream API is available, replace only that operation with an authored tool that stores the full payload outside model context and projects the needed fields through `toModelOutput`. Block the original MCP operation through [`tools.block`](#tool-filters) so the model does not see duplicate tools.
226
+ Authenticate the connection as this deployment with a fixed service credential, like the token above. Don't use a user's `connect("...")` sign-in or a per-caller resolver. eve can reuse the same `auth` and `headers` for different users in a shared session. The header names the user on each request, and the server decides what that user can reach.
211
227
 
212
228
  ## Events (experimental)
213
229
 
214
- An MCP connection can watch the server's events and run your code when one arrives. Vercel Connect holds the upstream subscription and forwards each event to your agent; eve runs your callback.
230
+ An MCP connection can watch the server's events and run your code when one arrives. Vercel Connect holds the subscription and forwards each event to your agent.
215
231
 
216
232
  Requirements:
217
233
 
@@ -221,7 +237,7 @@ Requirements:
221
237
 
222
238
  ### Handle events
223
239
 
224
- Add `experimental: { events: { ... } }` to the connection. In this example, a user asks the agent to "watch the support inbox and draft replies to new bug reports". The model subscribes to Bird's `email_mailbox.message_received` event for that mailbox. Each new email then starts a turn in the same conversation, with instructions to triage it:
240
+ Add `experimental: { events: { ... } }` to the connection. In this example, a user asks the agent to "watch the support inbox and draft replies to new bug reports". The model subscribes to Bird's `email_mailbox.message_received` event for that mailbox. Each new email starts a turn in the same conversation with instructions to triage it:
225
241
 
226
242
  ```ts title="agent/connections/bird.ts"
227
243
  import { connect } from "@vercel/connect/eve";
@@ -251,13 +267,13 @@ export default defineMcpClientConnection({
251
267
  });
252
268
  ```
253
269
 
254
- The model does the work with the connection's own tools: it reads the thread, drafts the reply, and waits for the user's approval in the conversation. `turnPolicy: "queue"` lets a burst of emails run one turn after another instead of interrupting the user.
270
+ The model does the work with the connection's tools, then waits for the user's approval in the conversation. `turnPolicy: "queue"` runs a burst of emails one turn after another instead of interrupting the user.
255
271
 
256
- `onEvent` is required. Defining it does not subscribe to anything: the model subscribes at runtime.
272
+ `onEvent` is required. Defining it doesn't subscribe to anything; the model subscribes while it works.
257
273
 
258
- Callbacks run outside any conversation, as the user who subscribed (`auth`). Nothing enters a session unless you call `attachSession(sessionId).send(...)`, and `attachSession` never creates a session.
274
+ Callbacks run outside any conversation, as the user who subscribed (`auth`). Nothing reaches a session unless you call `attachSession(sessionId).send(...)`, and `attachSession` never creates a session.
259
275
 
260
- Each delivery runs in its own durable workflow, so callbacks can run concurrently, out of order, and more than once. Use `deliveryId` to deduplicate side effects:
276
+ Callbacks can run concurrently, out of order, and more than once. Use `deliveryId` to deduplicate side effects:
261
277
 
262
278
  ```ts
263
279
  async onEvent({ event, deliveryId }) {
@@ -305,31 +321,31 @@ experimental: {
305
321
  | `events_get_subscription` | `{ id }` | The subscription, or unknown once ended |
306
322
  | `events_unsubscribe` | `{ id }` | `{ id, status: "stopping" }` |
307
323
 
308
- There is one subscribe action per event the server offers; its description names the event. `ttlMs` is required: an integer from `120000` (2 minutes) to `31536000000` (365 days), or `null` to watch until stopped. `expiresAt` is the resulting deadline, or `null`.
324
+ Each event the server offers gets one subscribe action, whose description names the event. `ttlMs` is required: an integer from `120000` (2 minutes) to `31536000000` (365 days), or `null` to watch until stopped. `expiresAt` is the resulting deadline, or `null`.
309
325
 
310
326
  - **Pending.** If Connect has not confirmed in time, subscribe returns the `id` with `status: "pending"`. Call get with that `id` later.
311
327
  - **Repeats.** Subscribing again to the same event with the same arguments from the same session returns the existing watch. Another session gets its own watch.
312
- - **Stopping.** Get and stop accept the `id` from any of the creator's sessions. After stop, eve keeps retrying Connect's unsubscribe until cleanup completes; until then get still reports the watch and stop can be called again.
328
+ - **Stopping.** Get and stop accept the `id` from any of the creator's sessions. Until Connect confirms the unsubscribe, get still reports the watch and stop can be called again.
313
329
  - **Lifetime.** A watch outlives the session that created it. It ends on stop, at `expiresAt`, or when the upstream subscription terminates.
314
330
 
315
- `tools.allow` and `tools.block` apply to these actions. An allow list hides any event action it does not name, so copy the exact `events_subscribe_<hash>` names from `eve__search`. `toolCall.providedArguments` does not apply to event actions.
331
+ `tools.allow` and `tools.block` apply to these actions, so an allow list must name the exact `events_subscribe_<hash>` names from `eve__search`. `toolCall.providedArguments` doesn't apply to them.
316
332
 
317
333
  ### Receiver
318
334
 
319
- eve mounts `POST /eve/v1/hooks/:connectionName`, under any configured agent or public prefix. It accepts only Connect's delivery token and only deliveries for a live watch's subscription; it answers `410` once the watch has ended. The callback's identity always comes from the saved watch, never from the event payload.
335
+ eve serves `POST /eve/v1/hooks/:connectionName`, under any configured agent or public prefix. It accepts only requests that carry Connect's token, and only for a watch that is still active. It answers `410` once the watch has ended. The callback's `auth` always comes from the saved watch, never from the event body.
320
336
 
321
337
  ## Troubleshooting
322
338
 
323
- | Symptom | Check |
324
- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
325
- | `principal_required` | A user-scoped `connect("...")` ran without an authenticated user. Return `principalType: "user"` from route auth, or use app-scoped auth. |
326
- | The model does not find the remote tool | Improve the connection `description`, then check `tools.allow` / `tools.block`. |
327
- | OAuth works locally but fails after deploy | Attach the Connect connector to the deployed Vercel project and verify the UID in `connect("...")`. |
328
- | The server rejects requests | Confirm the MCP URL, transport support, auth scheme, required headers, and application-provided arguments. |
339
+ | What you see | What to do |
340
+ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
341
+ | `principal_required` | `connect("...")` needs a signed-in user, and the session had none. Return `principalType: "user"` from route auth, or use app-scoped auth. |
342
+ | The model does not find the remote tool | Improve the connection `description`, then check `tools.allow` / `tools.block`. |
343
+ | OAuth works locally but fails after deploy | Attach the Connect connector to the deployed Vercel project and verify the UID in `connect("...")`. |
344
+ | The server rejects requests | Confirm the MCP URL, transport support, auth scheme, required headers, and application-provided arguments. |
329
345
 
330
346
  ## What to read next
331
347
 
332
348
  - [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
333
- - [OpenAPI connections](./openapi): generate tools from OpenAPI operations.
349
+ - [OpenAPI connections](./openapi): use one when the service publishes an HTTP API contract and you want one tool per operation.
334
350
  - [Authentication](../guides/auth-and-route-protection): establish the caller identity required by user-scoped auth.
335
351
  - [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.