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,28 +3,28 @@ title: "MCP Channel"
3
3
  description: "Publish an eve agent as an MCP server with auth support."
4
4
  ---
5
5
 
6
- The MCP channel lets clients such as Claude Code delegate durable work to an eve agent through four tools: `agent_start`, `agent_get`, `agent_update`, and `agent_cancel`. It can also publish the agent's own tools, so a client calls them directly, and its skills, so a client reads them; see [Publish the agent's tools](#publish-the-agents-tools) and [Publish the agent's skills](#publish-the-agents-skills).
6
+ The MCP channel publishes your agent as an MCP server, so clients such as Claude Code can hand it long-running work. It lives in `agent/channels/mcp.ts`. Clients start and follow that work with four tools: `agent_start`, `agent_get`, `agent_update`, and `agent_cancel`. The channel can also [publish the agent's tools](#publish-the-agents-tools) for clients to call directly, and [its skills](#publish-the-agents-skills) for clients to read.
7
7
 
8
8
  Use an [MCP connection](../connections/mcp) instead when your eve agent needs to call someone else's MCP server.
9
9
 
10
10
  ## Configure the channel
11
11
 
12
- Create `agent/channels/mcp.ts`. Authentication is required explicitly, even during development.
12
+ Create `agent/channels/mcp.ts`. `auth` is required, even during development.
13
13
 
14
14
  ```ts title="agent/channels/mcp.ts"
15
15
  import { localDev } from "eve/channels/auth";
16
16
  import { mcpChannel } from "eve/channels/mcp";
17
17
 
18
18
  export default mcpChannel({
19
- auth: localDev(),
19
+ auth: localDev(), // required; replace before you deploy
20
20
  });
21
21
  ```
22
22
 
23
- This accepts a synthetic local principal under `eve dev` or `vercel dev` and rejects all requests in production. Before deploying, replace it with one of the production authentication modes below. `localDev()` checks the running environment, not the request hostname: accessing an `eve start` production process through localhost does not activate it.
23
+ `localDev()` accepts a stand-in local user under `eve dev` or `vercel dev`, and rejects every request in production. It checks the running environment, not the hostname, so an `eve start` production process rejects requests from localhost too. Replace it with one of the [production auth modes](#interactive-oauth) before you deploy.
24
24
 
25
25
  ### Routes
26
26
 
27
- The default Streamable HTTP endpoint is `/eve/v1/mcp`. Set `route` when the application should publish it somewhere else:
27
+ The Streamable HTTP endpoint serves `GET`, `POST`, and `DELETE` at `/eve/v1/mcp`. Set `route` to publish it elsewhere:
28
28
 
29
29
  ```ts title="agent/channels/mcp.ts"
30
30
  import { localDev } from "eve/channels/auth";
@@ -36,11 +36,70 @@ export default mcpChannel({
36
36
  });
37
37
  ```
38
38
 
39
- The channel registers `GET`, `POST`, and `DELETE` at the selected route.
39
+ ## Invoke the agent
40
+
41
+ MCP clients receive four tools:
42
+
43
+ | Tool | Input | Purpose |
44
+ | -------------- | ----------------------------- | ------------------------------------------------------------------ |
45
+ | `agent_start` | `{ message }` | Start work and immediately return an invocation ID. |
46
+ | `agent_get` | `{ invocationId }` | Read the invocation's complete current state. |
47
+ | `agent_update` | `{ invocationId, responses }` | Answer every open question or approval in the invocation together. |
48
+ | `agent_cancel` | `{ invocationId }` | Ask unfinished work to stop. |
49
+
50
+ `initialize` and `server/discover` also return `instructions` that describe these tools to the connecting model.
51
+
52
+ `agent_start` creates one eve session and returns once eve has saved the request. Keep its `invocationId`, and call `agent_get` until the invocation finishes. While the status is `working`, wait at least `pollAfterMs` between calls.
53
+
54
+ The invocation's `status` is one of:
55
+
56
+ | `status` | What to do |
57
+ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
+ | `working` | Keep polling. The optional `statusMessage` says what the agent is doing, such as a running tool's [activity label](/docs/tools#label-tool-activity) or its name. |
59
+ | `input_required` | Show each entry in `interactions`, keyed by `interactionId`. Send all the answers in one `agent_update`, one `{ interactionId, optionId?, text? }` per entry. It returns the current state. |
60
+ | `authorization_required` | Show each sign-in in `interactions`: its `signIn` URL, user code, or instructions. The invocation resumes on its own after the sign-in; keep polling. |
61
+ | `completed` | Read the optional `result`, the final assistant message. The turn and any [tasks](/docs/tools/workflows#run-calls-as-tasks-task) it started have finished. |
62
+ | `failed` | Read the structured `error`. |
63
+ | `cancelled` | The work stopped. |
64
+
65
+ A tool result with `isError: true` means eve rejected the call, so fix the call. A `failed` status means the call succeeded and the work failed, so report it. Rejected calls carry `structuredContent.error` with a stable `code`, a short `message`, and `retryable`:
66
+
67
+ | `code` | Meaning | `retryable` |
68
+ | --------------- | ---------------------------------------------------------------------------- | ----------- |
69
+ | `invalid_input` | An argument was rejected, for example an oversized `message`. | `false` |
70
+ | `not_found` | The invocation does not exist, has expired, or belongs to another caller. | `false` |
71
+ | `conflict` | The invocation is not in the expected state; read it with `agent_get` first. | `true` |
72
+ | `internal` | eve failed; `errorId` correlates with server logs. No details are exposed. | `false` |
73
+
74
+ Limits: the MCP request body is 1 MiB, `message` 64 KiB, each response `text` 16 KiB (both in UTF-8 bytes), and one `agent_update` 64 responses. Oversized bodies get a JSON-RPC `413`, and oversized fields fail input validation before any work starts.
75
+
76
+ ### Durability guarantees
77
+
78
+ - Once `agent_start` returns, the work survives restarts and redeploys. Only `agent_cancel` stops it. A dropped connection, client restart, or closed MCP session doesn't.
79
+ - `agent_start` isn't idempotent. If its response is lost, a second call starts a second invocation, so ask the user before you start again.
80
+ - `agent_update` answers one set of open requests. Re-sending accepted answers returns the current state. Different answers for a set that was already answered return `conflict`.
81
+ - `agent_cancel` asks the work to stop, so it can race with completion. Poll `agent_get` until the status is `cancelled`, `completed`, or `failed`, not only `cancelled`.
82
+
83
+ ## Invocation ownership
84
+
85
+ Every MCP operation checks `auth` again. With an authenticated policy, an invocation belongs to the caller who started it, and knowing its ID isn't enough. Bearer tokens aren't stored with the invocation or forwarded to the agent's tools.
86
+
87
+ With `none()`, every caller is the same anonymous user, so the random invocation ID works like a password. Anyone who has it can read, answer, or cancel the invocation until workflow retention expires. Keep it out of logs and URLs. Responses include `expiresAt` when the workflow backend reports a retention deadline.
88
+
89
+ ## Options
90
+
91
+ | Option | Default | What it does |
92
+ | ------------------- | ----------------------------- | ----------------------------------------------------------------------------------- |
93
+ | `auth` | Required | One auth strategy or an ordered array. Use `none()` for public access. |
94
+ | `route` | `/eve/v1/mcp` | Path of the MCP endpoint. |
95
+ | `agent` | `true` | Serves the `agent_*` tools and their instructions. |
96
+ | `tools` | `false` | Also [publishes the agent's tools](#publish-the-agents-tools). |
97
+ | `skills` | `false` | Also [publishes the agent's skills](#publish-the-agents-skills). |
98
+ | `trustedForwarders` | Refuses the header with `403` | Lets a [router name the user](#forwarded-principals) that a published tool runs as. |
40
99
 
41
100
  ## Interactive OAuth
42
101
 
43
- For an MCP client that should open a sign-in flow, configure eve as an OAuth protected resource. Wrap the access-token verifier in `oauthResource()`:
102
+ To have an MCP client open a sign-in flow, configure eve as an OAuth protected resource. Wrap the access-token verifier in `oauthResource()`:
44
103
 
45
104
  ```ts title="agent/channels/mcp.ts"
46
105
  import { oauthResource, oidc } from "eve/channels/auth";
@@ -63,11 +122,11 @@ export default mcpChannel({
63
122
  });
64
123
  ```
65
124
 
66
- The authorization server identified by `issuer` must issue tokens accepted by the wrapped verifier. `scopes` advertises what clients should request; the verifier remains responsible for signature, expiration, audience/resource, and scope enforcement.
125
+ The `issuer` must issue tokens the wrapped verifier accepts. `scopes` tells clients what to request. The verifier still checks the signature, expiration, audience, and scopes.
67
126
 
68
- `oauthResource()` does not issue tokens or run an authorization server. It decorates an ordinary inbound `AuthFn` with OAuth protected-resource metadata so `mcpChannel()` can publish discovery and add `resource_metadata` to Bearer challenges. Client registration, consent, token issuance, and authorization-server metadata remain the identity provider's responsibility.
127
+ `oauthResource()` adds protected-resource metadata to an `AuthFn`. `mcpChannel()` then publishes discovery and adds `resource_metadata` to Bearer challenges. eve doesn't run an authorization server: client registration, consent, token issuance, and authorization-server metadata belong to the identity provider.
69
128
 
70
- Most hosted MCP clients (Claude, ChatGPT, Grok, and similar) register themselves with the authorization server through Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) the first time a user connects. Choose an issuer that supports it, or pre-register each client with the issuer before the demo. If registration fails, the client stops before it ever reaches eve.
129
+ Most hosted MCP clients, such as Claude, ChatGPT, and Grok, register themselves through Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) the first time a user connects. Choose an issuer that supports it, or pre-register each client. If registration fails, the client stops before it reaches eve.
71
130
 
72
131
  ### Verify the bearer token yourself
73
132
 
@@ -99,20 +158,20 @@ export default mcpChannel({
99
158
  });
100
159
  ```
101
160
 
102
- `verifyOidc()` uses the issuer's discovery document to validate the token signature and claims. Returning `sessionAuth` accepts the request and binds invocation ownership to that verified principal. Returning `null` lets the auth walk continue; when no strategy accepts the request, eve returns `401`.
161
+ `verifyOidc()` checks the token signature and claims against the issuer's discovery document. Return `sessionAuth` to accept the request; that caller then owns the invocation. Return `null` to pass to the next strategy. When no strategy accepts, eve returns `401`.
103
162
 
104
- You can wrap any strategy in `oauthResource()`, including `vercelOidc()`, but the advertised authorization server must issue tokens that strategy accepts. `vercelOidc()` by itself is preconfigured Vercel workload identity and does not advertise an interactive login.
163
+ You can wrap any strategy in `oauthResource()`, including `vercelOidc()`, as long as the advertised authorization server issues tokens it accepts. `vercelOidc()` alone is Vercel workload identity and offers no interactive login.
105
164
 
106
165
  ### Protected-resource metadata
107
166
 
108
- By default, eve derives the metadata path from the complete MCP resource identifier according to RFC 9728:
167
+ eve derives the metadata path from the full MCP resource identifier, per RFC 9728:
109
168
 
110
169
  | MCP resource | Protected-resource metadata |
111
170
  | -------------------------------------- | --------------------------------------------------------------------------- |
112
171
  | `https://agent.example.com/eve/v1/mcp` | `https://agent.example.com/.well-known/oauth-protected-resource/eve/v1/mcp` |
113
172
  | `https://agent.example.com/mcp` | `https://agent.example.com/.well-known/oauth-protected-resource/mcp` |
114
173
 
115
- Set `resource` when the public resource identifier cannot be derived from the incoming request. Set `metadataPath` only when discovery must live at a non-derived location:
174
+ Set `resource` when the request doesn't show the public resource identifier, as behind a gateway or proxy that changes the origin or path. Set `metadataPath` to serve discovery at another path:
116
175
 
117
176
  ```ts
118
177
  oauthResource(verifyToken, {
@@ -123,19 +182,19 @@ oauthResource(verifyToken, {
123
182
  });
124
183
  ```
125
184
 
126
- The metadata endpoint serves cross-origin `GET`, `HEAD`, and `OPTIONS` requests so browser-hosted clients can discover the authorization server. MCP protocol requests remain same-origin.
185
+ The metadata endpoint serves cross-origin `GET`, `HEAD`, and `OPTIONS` requests, so browser-hosted clients can find the authorization server.
127
186
 
128
187
  ## Other authentication modes
129
188
 
130
- `mcpChannel()` accepts the same inbound auth strategies as other eve channels: Basic auth, HMAC or ECDSA JWTs, generic OIDC, Vercel OIDC, custom `AuthFn` policies, or an ordered array of them. These modes do not automatically produce an interactive login unless wrapped in `oauthResource()`; configure credentials in the MCP client out of band.
189
+ `mcpChannel()` accepts the same auth strategies as other eve channels: Basic auth, HMAC or ECDSA JWTs, generic OIDC, Vercel OIDC, and custom `AuthFn` policies. Pass one, or an ordered array. Without `oauthResource()`, they offer no interactive login, so configure credentials in the MCP client directly.
131
190
 
132
- When a protected request has no accepted credentials, eve returns a Bearer challenge. A supplied Bearer token rejected by every strategy gets `error="invalid_token"`. To report a verified caller that lacks the necessary scopes, throw `ForbiddenError` with an `error="insufficient_scope"` Bearer challenge. The MCP channel preserves that challenge and adds the protected-resource metadata URL.
191
+ A request without accepted credentials gets a Bearer challenge. The challenge has `error="invalid_token"` when the request sent a Bearer token that every strategy rejected. For a verified caller without the needed scopes, throw `ForbiddenError` with an `error="insufficient_scope"` Bearer challenge. The channel keeps that challenge and adds the protected-resource metadata URL.
133
192
 
134
- For the complete strategy and auth-walk model, see [Authentication](../guides/auth-and-route-protection).
193
+ For how strategies are tried in order, see [Authentication](../guides/auth-and-route-protection).
135
194
 
136
195
  ### Public access
137
196
 
138
- To intentionally expose the MCP endpoint without authentication, use `none()`:
197
+ Use `none()` to expose the MCP endpoint without authentication:
139
198
 
140
199
  ```ts title="agent/channels/mcp.ts"
141
200
  import { none } from "eve/channels/auth";
@@ -146,74 +205,23 @@ export default mcpChannel({
146
205
  });
147
206
  ```
148
207
 
149
- This allows anyone to invoke the agent. Every caller shares the anonymous principal, so invocation IDs become bearer capabilities until workflow retention expires: anyone holding an ID can read, answer, or cancel that invocation. Use public access only when anonymous invocation is intentional. For a public demo, prefer [Interactive OAuth](#interactive-oauth) so each caller owns their own invocations.
208
+ Anyone can then invoke the agent. See [Invocation ownership](#invocation-ownership) for what an invocation ID then allows. For a public demo, prefer [Interactive OAuth](#interactive-oauth) so each caller owns their invocations.
150
209
 
151
210
  ## HTTP security
152
211
 
153
- The MCP transport validates the request before authentication:
212
+ The MCP endpoint checks each request before authentication:
154
213
 
155
- - Remote endpoints require HTTPS; HTTP is accepted only on loopback.
214
+ - Remote endpoints require HTTPS. HTTP is accepted only on loopback.
156
215
  - `Host` must match the request URL.
157
216
  - Browser protocol requests must have an exact same-origin `Origin`.
158
217
 
159
- When a gateway or reverse proxy changes the public origin or path, set `resource` explicitly so metadata and authentication challenges advertise the client-facing MCP resource.
218
+ Only the metadata endpoint allows cross-origin requests. For a browser application, put a same-origin backend or authenticated server-side proxy in front of the MCP endpoint.
160
219
 
161
- The protected-resource metadata endpoint is intentionally CORS-readable. The MCP transport itself does not enable cross-origin browser access; place a same-origin backend or authenticated server-side proxy in front of it when a browser application needs to connect.
162
-
163
- The endpoint serves MCP `2026-07-28` directly and retains stateless `2025-11-25` Streamable HTTP compatibility. eve does not keep an MCP transport session in either mode.
164
-
165
- ## Invoke the agent
166
-
167
- MCP clients receive four tools:
168
-
169
- | Tool | Input | Purpose |
170
- | -------------- | ----------------------------- | ----------------------------------------------------------- |
171
- | `agent_start` | `{ message }` | Start durable work and immediately return an invocation ID. |
172
- | `agent_get` | `{ invocationId }` | Read the invocation's complete current state. |
173
- | `agent_update` | `{ invocationId, responses }` | Answer the complete pending human-input batch. |
174
- | `agent_cancel` | `{ invocationId }` | Request cooperative cancellation of non-terminal work. |
175
-
176
- The server also returns `instructions` from `initialize` and `server/discover` that summarize this
177
- protocol for the connecting model, so a hosted client does not have to infer it from the tool
178
- schemas alone.
179
-
180
- `agent_start` creates one eve session and returns after durable acceptance without
181
- waiting for the session continuation hook to become readable. Keep its `invocationId`, then call
182
- `agent_get` until the invocation reaches a terminal state. While the status is `working`, wait at
183
- least `pollAfterMs` before polling again.
184
-
185
- The invocation response is discriminated by `status`:
186
-
187
- - `working`: work is active; continue polling according to `pollAfterMs`. The optional `statusMessage` describes what the agent is doing right now, such as a running tool call's [activity label](/docs/tools#label-tool-activity) or its tool name, so a client can show progress.
188
- - `input_required`: present `interactions`, keyed by `interactionId`, then send the complete answer batch through `agent_update`, one `{ interactionId, optionId?, text? }` response per entry. A successful update returns the current invocation state.
189
- - `authorization_required`: present each sign-in in `interactions`: its `signIn` URL, user code, or instructions. The connection callback resumes the invocation automatically; continue polling.
190
- - `completed`: the agent's turn settled, after any [tasks](/docs/tools/workflows#run-calls-as-tasks-task) it started finished. Consume the optional `result`: the final assistant message.
191
- - `failed`: inspect the structured `error`.
192
- - `cancelled`: cancellation reached a terminal state.
193
-
194
- A tool result with `isError: true` means the call itself was rejected. A `failed` status means the call succeeded and the task itself failed. Handle them differently: correct the call in the first case, report the task failure in the second. Rejected calls carry `structuredContent.error` with a stable `code`, a short `message`, and `retryable`:
195
-
196
- | `code` | Meaning | `retryable` |
197
- | --------------- | ---------------------------------------------------------------------------- | ----------- |
198
- | `invalid_input` | An argument was rejected, for example an oversized `message`. | `false` |
199
- | `not_found` | The invocation does not exist, has expired, or belongs to another caller. | `false` |
200
- | `conflict` | The invocation is not in the expected state; read it with `agent_get` first. | `true` |
201
- | `internal` | eve failed; `errorId` correlates with server logs. No details are exposed. | `false` |
202
-
203
- Cancellation is cooperative, so call `agent_get` after `agent_cancel` until the state becomes terminal.
204
-
205
- Requests are bounded: the whole MCP request body is limited to 1 MiB, `message` to 64 KiB, each input-response `text` to 16 KiB (both measured as UTF-8 bytes, not characters), and one `agent_update` to 64 responses. Oversized bodies receive a JSON-RPC `413`; oversized fields fail input validation before any work starts.
206
-
207
- ### Durability guarantees
208
-
209
- - Once `agent_start` returns, the work is durable. A dropped HTTP connection, a client restart, or a closed MCP session does not cancel it. Only `agent_cancel` stops work.
210
- - `agent_start` is not idempotent. If its response is lost, the client has no `invocationId` to check, and a second call starts a second task. Ask the user before starting again rather than retrying blindly.
211
- - `agent_update` answers one pending batch. Re-sending the same answers after eve has accepted them returns the current invocation state; sending different answers for an already-answered batch is a conflict.
212
- - `agent_cancel` is cooperative and can race with completion. Poll `agent_get` until the status is terminal (`cancelled`, `completed`, or `failed`), not specifically `cancelled`.
220
+ The endpoint serves MCP `2026-07-28` and stateless `2025-11-25` Streamable HTTP, with no MCP transport session in either.
213
221
 
214
222
  ## Publish the agent's tools
215
223
 
216
- By default the channel serves only the `agent_*` tools. Set `tools: true` to also publish every tool the agent can run outside a conversation, and `agent: false` to stop serving the `agent_*` tools:
224
+ Set `tools: true` to also publish every tool the agent can run outside a conversation. Set `agent: false` to stop serving the `agent_*` tools:
217
225
 
218
226
  ```ts title="agent/channels/mcp.ts"
219
227
  import { localDev } from "eve/channels/auth";
@@ -221,19 +229,28 @@ import { mcpChannel } from "eve/channels/mcp";
221
229
 
222
230
  export default mcpChannel({
223
231
  auth: localDev(),
224
- tools: true,
232
+ tools: true, // omit to serve only the agent_* tools
225
233
  });
226
234
  ```
227
235
 
228
- `tools/list` returns the `agent_*` tools first, then the agent's tools in name order with their input and output JSON schemas. Framework tools, workflow and provider tools, tools without `execute`, and tools added by dynamic resolvers or subagents are not published. While `agent` is on, an agent tool named `agent_start`, `agent_get`, `agent_update`, or `agent_cancel` is not published, and eve logs a warning. With `agent: false`, the channel sends no `agent_*` instructions. Turning off `agent`, `tools`, and `skills` all at once throws, since the channel would publish nothing.
236
+ `tools/list` returns the `agent_*` tools first, then the agent's tools in name order with their input and output JSON schemas. eve doesn't publish these tools:
237
+
238
+ - framework tools, workflow tools, and provider tools;
239
+ - tools without `execute`;
240
+ - tools from dynamic resolvers or subagents; and
241
+ - while `agent` is on, an agent tool named like an `agent_*` tool. eve logs a warning.
229
242
 
230
- Each `tools/call` checks the arguments against the tool's input schema, then runs the tool as the route-authenticated caller, or as a [forwarded user](#forwarded-principals), with no model, turn, or workflow run. Every caller the channel's `auth` admits can call these tools, outside the agent's instructions, so review what becomes callable before you turn this on. Unless the call joins a [tool session](#tool-sessions), it gets its own session:
243
+ With `agent: false`, the channel sends no `agent_*` instructions.
231
244
 
232
- - Authored state starts from its initial value, and updates are not kept.
245
+ Each `tools/call` checks the arguments against the tool's input schema. It then runs the tool as the authenticated caller, or a [forwarded user](#forwarded-principals), with no model, turn, or workflow run. Every caller that the channel's `auth` accepts can call these tools, outside the agent's instructions, so review what becomes callable.
246
+
247
+ Unless the call joins a [tool session](#tool-sessions), it gets its own session:
248
+
249
+ - Authored state starts from its initial value, and updates aren't kept.
233
250
  - A sandbox the tool opens is deleted when the call ends.
234
251
  - Calls may run in parallel, and a call retried after a lost response runs again.
235
252
 
236
- A tool that cannot finish over MCP returns an error result with `isError: true` and a `structuredContent.error.code`:
253
+ A tool that can't finish over MCP returns an error result with `isError: true` and a `structuredContent.error.code`:
237
254
 
238
255
  | Code | When |
239
256
  | ------------------------ | ------------------------------------------------------------------------------------------------ |
@@ -245,13 +262,13 @@ A tool that cannot finish over MCP returns an error result with `isError: true`
245
262
 
246
263
  ### Trace context
247
264
 
248
- MCP clients send W3C trace context in each request's `params._meta`, not in HTTP headers. When a request carries a valid `_meta.traceparent`, that span becomes the parent of everything the request runs, including a published tool's `execute_tool` span. It takes precedence over any parent your platform extracted from the HTTP request's headers. A missing, malformed, or all-zero `traceparent` leaves that parent in place. `_meta.tracestate` is kept only alongside a valid `_meta.traceparent` and only up to 512 characters; a longer value is dropped.
265
+ MCP clients send W3C trace context in each request's `params._meta`. A valid `_meta.traceparent` becomes the parent of everything the request runs, including a published tool's `execute_tool` span. It takes precedence over a parent from the HTTP headers. A missing, malformed, or all-zero `traceparent` leaves the header parent in place. eve keeps `_meta.tracestate` only with a valid `traceparent`, and only up to 512 characters.
249
266
 
250
- `_meta.baggage` is never read. A caller cannot choose the trace audience, session lineage, or content capture: those come from the channel and your `tracePolicy`, as they do for conversations. The `execute_tool` span records the call's arguments and result only when that content decision allows it, and never records exception text.
267
+ eve ignores `_meta.baggage`, so callers can't set trace audience, session lineage, or content capture. Those come from the channel and your `tracePolicy`. The `execute_tool` span records arguments and result only when that policy allows content capture, and never records exception text.
251
268
 
252
269
  ### Forwarded principals
253
270
 
254
- A router that calls the channel on behalf of its own users, such as another eve agent's [`forwardPrincipal` connection](../connections/mcp#forward-the-caller-to-an-eve-agent), can name the user in the `eve-forwarded-principal` header: unpadded base64url of UTF-8 JSON `{ current, initiator? }`, at most 16 KiB. eve accepts the header only when `trustedForwarders` is set, and only from a route-authenticated forwarder the predicate accepts:
271
+ A router can call the channel on behalf of its own users, such as another eve agent's [`forwardPrincipal` connection](../connections/mcp#forward-the-caller-to-an-eve-agent). It names the user in the `eve-forwarded-principal` header: unpadded base64url of UTF-8 JSON `{ current, initiator? }`, at most 16 KiB. eve accepts the header only when `trustedForwarders` is set, and only from an authenticated router that the predicate accepts:
255
272
 
256
273
  ```ts title="agent/channels/mcp.ts"
257
274
  import { vercelOidc, vercelSubject } from "eve/channels/auth";
@@ -266,20 +283,28 @@ export default mcpChannel({
266
283
  });
267
284
  ```
268
285
 
269
- The predicate receives the verified forwarder and the principals it asserts, as the [eve channel](./eve)'s `trustedForwarders` does, so match the forwarder precisely; see [Accepting forwarded identity](../guides/auth-and-route-protection#accepting-forwarded-identity-from-another-deployment). A published tool called with an accepted header runs as the forwarded user: `ctx.session.auth.current` is that user, `ctx.session.auth.initiator` is the asserted initiator or that user, and both carry the forwarder's `principalId` in the `eve:forwarded-by` attribute. The `agent_*` tools still act as the route-authenticated caller.
286
+ The predicate receives the verified router and the users it names, as in the [eve channel](./eve)'s `trustedForwarders`. Match the router precisely; see [Accepting forwarded identity](../guides/auth-and-route-protection#accepting-forwarded-identity-from-another-deployment).
287
+
288
+ A published tool called with an accepted header runs as the forwarded user:
289
+
290
+ - `ctx.session.auth.current` is that user.
291
+ - `ctx.session.auth.initiator` is the named initiator, or that user.
292
+ - Both carry the router's `principalId` in the `eve:forwarded-by` attribute.
270
293
 
271
- | Request | Response |
272
- | ------------------------------------------------------ | ------------------------ |
273
- | No header | Runs as the route caller |
274
- | Malformed or over 16 KiB | `400` |
275
- | The predicate refuses the forwarder or what it asserts | `403` |
276
- | The forwarder is anonymous (`none()`) | `403` |
277
- | The channel has no `trustedForwarders` | `403` |
278
- | The predicate throws | `500` |
294
+ The `agent_*` tools act as the authenticated caller, not the forwarded user.
295
+
296
+ | Request | Response |
297
+ | ------------------------------------------------------ | -------------------------------- |
298
+ | No header | Runs as the authenticated caller |
299
+ | Malformed or over 16 KiB | `400` |
300
+ | The predicate refuses the router or the users it names | `403` |
301
+ | The router is anonymous (`none()`) | `403` |
302
+ | The channel has no `trustedForwarders` | `403` |
303
+ | The predicate throws | `500` |
279
304
 
280
305
  ### Tool sessions
281
306
 
282
- A tool session lets several `tools/call` requests share one sandbox, so a file one call writes is there for the next. With `tools: true`, the channel advertises the `dev.eve/tool-sessions` extension in `capabilities.extensions` of `server/discover`. A client joins a session by declaring the same extension in the request's `io.modelcontextprotocol/clientCapabilities` and sending a key of 1 to 512 characters in `_meta["dev.eve/tool-session"]`:
307
+ A tool session lets several `tools/call` requests share one sandbox, so a file one call writes is there for the next. With `tools: true`, `server/discover` advertises the `dev.eve/tool-sessions` extension in `capabilities.extensions`. To join a session, a client declares the extension in the request's `io.modelcontextprotocol/clientCapabilities`. It also sends a 1–512 character key in `_meta["dev.eve/tool-session"]`:
283
308
 
284
309
  ```json
285
310
  {
@@ -301,28 +326,29 @@ A tool session lets several `tools/call` requests share one sandbox, so a file o
301
326
  }
302
327
  ```
303
328
 
304
- eve derives the session id from the principal the call runs as (the route-authenticated caller, or a [forwarded user](#forwarded-principals) together with the verified router that forwarded them) and the key, so calls from the same principal with the same key share the session, and another caller who sends the same key gets a different one. That holds for forwarded users too: two users forwarded with the same key, or one user forwarded by two routers, get separate sessions. The router counted is the one the channel's `auth` verified, never one named in the forwarded principal. A key from a client that did not declare the extension is ignored, and the call gets its own session. Clients on the 2025-11-25 protocol send no per-request capabilities, so they always get their own session.
329
+ Calls share a session only when they have the same key and run as the same caller. That caller is the authenticated caller, or a [forwarded user](#forwarded-principals) together with the router that the channel's `auth` verified. Two forwarded users with one key, or one user forwarded by two routers, get separate sessions. eve ignores a key from a client that didn't declare the extension. Clients on the 2025-11-25 protocol send no per-request capabilities, so each call gets its own session.
305
330
 
306
- Tool sessions need an authenticated caller. With `auth: none()` every request is the same anonymous principal, so a key alone would name the session and anyone who knew it could read what another client left in the sandbox. A keyed call from an anonymous caller is therefore denied with the `denied` error code before anything runs; unkeyed anonymous calls still get a one-off session.
331
+ Tool sessions need an authenticated caller. With `auth: none()`, the key alone would name the session, so anyone who knew it could read another client's sandbox. eve denies a keyed anonymous call with the `denied` code before anything runs. Unkeyed anonymous calls get a one-off session.
307
332
 
308
333
  In a tool session:
309
334
 
310
- - The sandbox opens on the first `ctx.getSandbox()` and is kept for later calls with the same key. Concurrent first calls share one sandbox.
311
- - The sandbox is found from the session id alone. A deploy that changes the sandbox definition (the template, its snapshot, the open options in `sandbox.ts`, or its resources) keeps using the existing sandbox for the key; the current definition applies only when a sandbox is created, such as after the old one expires as below. Deployments that share a sandbox namespace, such as preview and production deployments of one Vercel project, also share the sandbox for the same principal and key.
335
+ - The sandbox opens on the first `ctx.getSandbox()`, and eve keeps it for later calls with the key. Concurrent first calls share one sandbox.
336
+ - A deploy that changes the sandbox definition (template, snapshot, open options in `sandbox.ts`, or resources) keeps the existing sandbox. The new definition applies only to a new sandbox, such as after expiry.
337
+ - Deployments that share a sandbox namespace, such as preview and production of one Vercel project, share the sandbox for the same caller and key.
312
338
  - `ctx.session.id` is the same for every call with the key.
313
- - Traces still show each call as its own run. Its `agent.run.id` and `gen_ai.conversation.id` are a fresh id for that call, not `ctx.session.id`, so traces do not link calls that share a key.
314
- - Authored state still starts from its initial value on every call, and updates are not kept. Keep data that must outlive a call in the sandbox.
315
- - Calls may still run in parallel, and nothing orders them.
339
+ - Traces show each call as its own run, with a fresh `agent.run.id` and `gen_ai.conversation.id`, so traces don't link calls that share a key.
340
+ - Authored state starts from its initial value on every call, and updates aren't kept. Keep data that must outlive a call in the sandbox.
341
+ - Calls may run in parallel, in any order.
316
342
 
317
- Tool sessions need a sandbox provider whose kept sandboxes stay bounded: Vercel Sandbox, just-bash, or a [custom provider](/docs/sandbox/custom-providers#keep-sandboxes-for-keyed-tool-calls) that sets `toolSessions: true`. On another provider, a call with a key fails with a `Sandbox provider "<name>" cannot keep a sandbox between invokeTool calls` error when the tool opens its sandbox. Tools that never open a sandbox still run. just-bash keeps its sandboxes on the local disk, so on Vercel Functions a just-bash tool session lasts only as long as the function instance.
343
+ Tool sessions need Vercel Sandbox, just-bash, or a [custom provider](/docs/sandbox/custom-providers#keep-sandboxes-for-keyed-tool-calls) that sets `toolSessions: true`. On another provider, a keyed call fails with `Sandbox provider "<name>" cannot keep a sandbox between invokeTool calls` when the tool opens its sandbox. Tools that never open one still run.
318
344
 
319
- A tool session has no end, so eve bounds how long its sandbox is kept. On Vercel Sandbox, a tool-session sandbox's saved filesystem expires a day after its last use, and each call that resumes it restarts that day. The next call with the key after that replaces it with a fresh, empty sandbox. If two calls with the key find the expired filesystem at the same time, each can replace the sandbox, and files the first one writes can be lost. Vercel only keeps the latest snapshot of the sandbox. Tool sessions use this one-day expiry whatever `snapshotExpiration` `sandbox.ts` sets; sessions that conversations start keep the authored setting.
345
+ On Vercel Sandbox, a tool-session sandbox's saved filesystem expires a day after its last use, whatever `snapshotExpiration` `sandbox.ts` sets. The next call with the key then gets a fresh, empty sandbox. If two calls find the expired filesystem at once, both can replace the sandbox, and the first one's files can be lost. Conversation sessions keep the authored `snapshotExpiration`.
320
346
 
321
- just-bash keeps tool-session sandboxes on the local disk, and nothing removes them.
347
+ just-bash keeps tool-session sandboxes on the local disk and never removes them. On Vercel Functions, a just-bash tool session lasts only as long as the function instance.
322
348
 
323
349
  ## Publish the agent's skills
324
350
 
325
- Set `skills: true` to serve the agent's skills as [SEP-2640](https://modelcontextprotocol.io/seps/2640) skills under `skill://`, so a client that calls the agent's tools can also read the workflow knowledge behind them:
351
+ Set `skills: true` to serve the agent's skills as [SEP-2640](https://modelcontextprotocol.io/seps/2640) skills under `skill://`. A client can then read the workflow knowledge behind the agent's tools:
326
352
 
327
353
  ```ts title="agent/channels/mcp.ts"
328
354
  import { localDev } from "eve/channels/auth";
@@ -335,26 +361,38 @@ export default mcpChannel({
335
361
  });
336
362
  ```
337
363
 
338
- The channel declares the `io.modelcontextprotocol/skills` extension and serves `skills/list`, `skills/get`, `resources/list`, `resources/templates/list`, `resources/read`, and `resources/directory/read`. Every caller the channel's `auth` admits can read every served skill. Each skill's entry is `skill://<name>/SKILL.md`, and its `resources` list every file with its `size` in bytes and a `sha256:` digest. `resources/list` returns one resource per served skill, its `SKILL.md`; the other files of a skill are reachable through `resources/directory/read` and the entry's `resources`, not listed there. `resources/directory/read` lists every directory of a skill, including empty ones, which return no children. `resources/templates/list` is always empty. `resources/read` returns UTF-8 text as `text` and anything else, such as images or Latin-1 files, as a base64 `blob`, byte for byte. Every skill and resource method carries the same cache hint as `tools/list`: private, for 5 minutes. The server's `resources` capability declares `listChanged: false`; eve never sends `notifications/resources/list_changed`, so a client re-reads after the hint expires. For each compiled artifact version, eve builds each skill's catalog snapshot once, listing its files and reading them to compute their sizes and digests. Only the served `SKILL.md` is kept in memory; `resources/read` reads other files from storage again, and a file removed since the snapshot is an unknown resource (`-32602`).
364
+ The channel declares the `io.modelcontextprotocol/skills` extension and serves the methods below. Every caller that the channel's `auth` accepts can read every served skill.
339
365
 
340
- A skill is served whole or not at all. eve leaves a skill out of every method, and logs one warning naming the reason, when:
366
+ | Method | Returns |
367
+ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
368
+ | `skills/list`, `skills/get` | Each skill's entry, `skill://<name>/SKILL.md`, with `resources` listing every file's `size` in bytes and `sha256:` digest |
369
+ | `resources/list` | One resource per skill, its `SKILL.md` |
370
+ | `resources/directory/read` | Every directory of a skill, including empty ones |
371
+ | `resources/templates/list` | Always empty |
372
+ | `resources/read` | UTF-8 text as `text`, anything else, such as images or Latin-1 files, as a base64 `blob` |
341
373
 
342
- - its `SKILL.md` frontmatter does not meet the Agent Skills format: a `name` of up to 64 lowercase letters, digits, and single hyphens, and a `description` of 1 to 1024 characters;
343
- - it has more than 512 files or more than 16 MiB in total;
344
- - any of its files is over 512 KiB, unreadable, or has a path that cannot be a `skill://` URI.
374
+ Every skill and resource method carries the same private, 5-minute cache hint as `tools/list`. The `resources` capability declares `listChanged: false`, so clients re-read after the hint expires. A file removed after eve indexed the skill is an unknown resource (`-32602`).
345
375
 
346
- A `SKILL.md` whose frontmatter already names the skill and has a `description` is served as authored. Otherwise, as for flat `.md` and module skills, eve serves it with frontmatter that carries the skill's name and description, and the digest describes that served document. Skills added by dynamic resolvers or subagents are not served.
376
+ eve serves a skill whole or not at all. It leaves out a skill, and logs a warning with the reason, when:
347
377
 
348
- Production builds ship skill files as eve-owned server assets, so they count toward the deployed function's size. `eve build` also drops Nitro's default `server` server-asset entry, the one that would bundle the app's `assets/` directory; eve reads only its own asset bases, and a route that reads `assets:server` storage finds it empty in production.
378
+ - Its `SKILL.md` frontmatter doesn't meet the Agent Skills format. The `name` must be up to 64 lowercase letters, digits, and single hyphens, and the `description` 1 to 1024 characters.
379
+ - It has more than 512 files or more than 16 MiB in total.
380
+ - Any of its files is over 512 KiB, unreadable, or has a path that can't be a `skill://` URI.
349
381
 
350
- ## Invocation ownership
382
+ A `SKILL.md` whose frontmatter names the skill and has a `description` is served as written. Otherwise, eve serves it with generated frontmatter that carries the name and description, as for flat `.md` and module skills. The digest covers the served document. eve doesn't serve skills from dynamic resolvers or subagents.
383
+
384
+ Production builds ship skill files as server assets, so they count toward the deployed function's size. `eve build` drops Nitro's default `server` server-asset entry, so a route that reads `assets:server` storage finds it empty in production.
351
385
 
352
- Every MCP operation reruns the configured auth policy. With authenticated policies, an invocation belongs to the principal that started it; knowing its ID is not sufficient. Bearer tokens are not stored with the invocation or forwarded to the agent's tools.
386
+ ## Troubleshooting
353
387
 
354
- With `none()`, every caller shares the anonymous principal, so the random invocation ID becomes a bearer capability. Keep it out of logs and URLs and treat it as usable until workflow retention expires. Responses include `expiresAt` when the workflow backend reports a retention deadline.
388
+ | What you see | What to do |
389
+ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
390
+ | `mcpChannel requires auth. Use none() for explicit public access.` | Set `auth`. Use `none()` only when the endpoint should be public. |
391
+ | `mcpChannel publishes nothing with agent, tools, and skills all false. Enable one.` | Turn on at least one of `agent`, `tools`, or `skills`. |
392
+ | `Sandbox provider "<name>" cannot keep a sandbox between invokeTool calls` on a keyed tool call | Use Vercel Sandbox, just-bash, or a custom provider with `toolSessions: true` for [tool sessions](#tool-sessions). |
355
393
 
356
394
  ## What to read next
357
395
 
358
396
  - [Authentication](../guides/auth-and-route-protection): configure inbound route authentication
359
397
  - [MCP connections](../connections/mcp): let an eve agent call another MCP server
360
- - [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): understand the durable sessions behind invocations
398
+ - [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): the sessions behind invocations