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.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
package/docs/channels/mcp.mdx
CHANGED
|
@@ -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
|
|
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`.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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()`
|
|
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
|
|
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()`
|
|
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()`,
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
193
|
+
For how strategies are tried in order, see [Authentication](../guides/auth-and-route-protection).
|
|
135
194
|
|
|
136
195
|
### Public access
|
|
137
196
|
|
|
138
|
-
|
|
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
|
-
|
|
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
|
|
212
|
+
The MCP endpoint checks each request before authentication:
|
|
154
213
|
|
|
155
|
-
- Remote endpoints require HTTPS
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
243
|
+
With `agent: false`, the channel sends no `agent_*` instructions.
|
|
231
244
|
|
|
232
|
-
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
272
|
-
|
|
273
|
-
|
|
|
274
|
-
|
|
|
275
|
-
|
|
|
276
|
-
|
|
|
277
|
-
| The
|
|
278
|
-
| The
|
|
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`,
|
|
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
|
-
|
|
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()
|
|
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()
|
|
311
|
-
-
|
|
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
|
|
314
|
-
- Authored state
|
|
315
|
-
- Calls may
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
386
|
+
## Troubleshooting
|
|
353
387
|
|
|
354
|
-
|
|
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):
|
|
398
|
+
- [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): the sessions behind invocations
|