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