The Open Framework for Building Agents
feat(eve): configure MCP protocol discovery per connection (#3307)
Sam Kobef74fe8f281
diff --git a/.changeset/quiet-mcp-handshake.md b/.changeset/quiet-mcp-handshake.mdnew file mode 100644index 000000000..cd4a2da72--- /dev/null+++ b/.changeset/quiet-mcp-handshake.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Add `protocolVersionDiscovery` to MCP client connections. Set it to `false` to use the initialization handshake for servers that reject modern discovery, while keeping discovery enabled by default.diff --git a/docs/connections/mcp.mdx b/docs/connections/mcp.mdxindex 36b3e6ad1..cc7c21565 100644--- a/docs/connections/mcp.mdx+++ b/docs/connections/mcp.mdx@@ -24,6 +24,20 @@ export default defineMcpClientConnection({The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself: it is the main signal `connection_search` uses when deciding which connection to query.+## Configure protocol discovery++eve discovers the server's MCP protocol by default. If a server requires the older `initialize` handshake, disable discovery for that connection:++```ts+export default defineMcpClientConnection({+ url: "https://mcp.example.com/mcp",+ description: "Search support cases",+ protocolVersionDiscovery: false,+});+```++With `protocolVersionDiscovery: false`, the client skips `server/discover` and starts with `initialize`, proposing `2025-11-25` and negotiating a supported handshake-based version. This is a per-connection setting; omitting it or setting it to `true` keeps discovery enabled. Remove the override when the server supports discovery. The setting also applies to connections returned by dynamic resolvers.+## Use Vercel Connect for OAuthFor OAuth-backed MCP servers, use the shared [Vercel Connect flow](../connections#interactive-oauth-via-vercel-connect), then pass the returned connector UID to `connect()`. Keep the MCP runtime URL and Connect service identifier distinct. For example, Linear uses `https://mcp.linear.app/mcp` as the MCP endpoint and `mcp.linear.app` when creating the connector.diff --git a/packages/eve/extension-contracts/compatibility/connection/v17.ts b/packages/eve/extension-contracts/compatibility/connection/v17.tsnew file mode 100644index 000000000..908425a11--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/connection/v17.ts@@ -0,0 +1,19 @@+import { defineDynamic, defineMcpClientConnection } from "#public/connections/index.js";++export const support = defineMcpClientConnection({+ description: "Search support cases",+ url: "https://support.example.com/mcp",+ auth: { getToken: async () => ({ token: "fixture-token" }) },+});++export default defineDynamic({+ events: {+ "session.started": (_event, ctx) =>+ defineMcpClientConnection({+ description: "Search tenant support cases",+ url: "https://support.example.com/mcp",+ instanceKey: ctx.session.id,+ headers: { "X-Session": ctx.session.id },+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/tool/v37.ts b/packages/eve/extension-contracts/compatibility/tool/v37.tsnew file mode 100644index 000000000..75ca1333d--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/tool/v37.ts@@ -0,0 +1,16 @@+import { z } from "zod";++import { defineTool } from "#public/tools/index.js";++export default defineTool({+ description: "Report the active session.",+ inputSchema: z.object({}),+ outputSchema: z.object({+ sessionId: z.string(),+ turnId: z.string(),+ }),+ execute: (_input, ctx) => ({+ sessionId: ctx.session.id,+ turnId: ctx.session.turn.id,+ }),+});diff --git a/packages/eve/extension-contracts/reports/connection/v18.json b/packages/eve/extension-contracts/reports/connection/v18.jsonnew file mode 100644index 000000000..5bbef0348--- /dev/null+++ b/packages/eve/extension-contracts/reports/connection/v18.json@@ -0,0 +1,16 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "connection",+ "epoch": 18,+ "sha256": "34735b87e8e21874c7f381002df7d004f6f4b59c1d9c62e5ef5e2cf3f5bd015c",+ "exports": [+ "ConnectionAuthorizationFailedError",+ "ConnectionAuthorizationRequiredError",+ "defineDynamic",+ "defineInteractiveAuthorization",+ "defineMcpClientConnection",+ "defineOpenAPIConnection",+ "isConnectionAuthorizationFailedError",+ "isConnectionAuthorizationRequiredError"+ ]+}diff --git a/packages/eve/extension-contracts/reports/tool/v38.json b/packages/eve/extension-contracts/reports/tool/v38.jsonnew file mode 100644index 000000000..1935d5dcb--- /dev/null+++ b/packages/eve/extension-contracts/reports/tool/v38.json@@ -0,0 +1,20 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "tool",+ "epoch": 38,+ "sha256": "fd22a33086be69904746395fc1d13f35a38c957ab90bb079445cc02756dce23e",+ "exports": [+ "defaultWebSearch",+ "defineTool",+ "defineWorkflowTool",+ "disableTool",+ "experimental_workflow",+ "isDisabledToolSentinel",+ "isExperimentalWorkflowToolDefinition",+ "isWebSearchToolDefinition",+ "toolOutput",+ "toolOutputPart",+ "toolResultFrom",+ "webSearch"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex e6dbf13dd..6b20f0cc2 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -22,8 +22,8 @@ interface ExtensionCapabilityContract {const EXTENSION_CAPABILITY_CONTRACTS = {extension: { current: 1, supported: [1], dropped: {} },tool: {- current: 37,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 28, 29, 30, 31, 32, 34, 35, 36, 37],+ current: 38,+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 28, 29, 30, 31, 32, 34, 35, 36, 37, 38],dropped: {14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",15: "TaskExec replaces stageEffect with send",@@ -81,8 +81,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},connection: {- current: 17,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17],+ current: 18,+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18],dropped: {9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",10: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",diff --git a/packages/eve/src/internal/authored-definition/connection.test.ts b/packages/eve/src/internal/authored-definition/connection.test.tsindex 1d7eac241..27b1cd5b3 100644--- a/packages/eve/src/internal/authored-definition/connection.test.ts+++ b/packages/eve/src/internal/authored-definition/connection.test.ts@@ -25,6 +25,20 @@ function authProvider(auth: ConnectionAuthDefinition | undefined): ConnectionAut}describe("normalizeMcpClientConnectionDefinition", () => {+ it.each([undefined, true, false])("preserves protocolVersionDiscovery %s", (value) => {+ const result = normalizeMcpClientConnectionDefinition(+ validInput({ protocolVersionDiscovery: value }),+ MSG,+ );+ expect(result.protocolVersionDiscovery).toBe(value);+ });++ it.each([null, "false", 0, {}])("rejects a non-boolean protocolVersionDiscovery: %j", (value) => {+ expect(() =>+ normalizeMcpClientConnectionDefinition(validInput({ protocolVersionDiscovery: value }), MSG),+ ).toThrow('"protocolVersionDiscovery" must be a boolean.');+ });+describe("happy path", () => {it("accepts a valid definition with a getToken function", () => {const result = normalizeMcpClientConnectionDefinition(validInput(), MSG);diff --git a/packages/eve/src/internal/authored-definition/connection.ts b/packages/eve/src/internal/authored-definition/connection.tsindex dbe54cd47..458c97b95 100644--- a/packages/eve/src/internal/authored-definition/connection.ts+++ b/packages/eve/src/internal/authored-definition/connection.ts@@ -20,6 +20,7 @@ const KNOWN_TOP_LEVEL_KEYS = ["description","headers","instanceKey",+ "protocolVersionDiscovery","toolCall","tools","url",@@ -93,6 +94,13 @@ export function normalizeMcpClientConnectionDefinition(url: record.url as string,};+ if (record.protocolVersionDiscovery !== undefined) {+ if (typeof record.protocolVersionDiscovery !== "boolean") {+ throw new Error(`${message} "protocolVersionDiscovery" must be a boolean.`);+ }+ result.protocolVersionDiscovery = record.protocolVersionDiscovery;+ }+if (record.instanceKey !== undefined) {result.instanceKey = record.instanceKey as string;}diff --git a/packages/eve/src/public/definitions/connections/mcp.ts b/packages/eve/src/public/definitions/connections/mcp.tsindex 59f8198e3..0eea62781 100644--- a/packages/eve/src/public/definitions/connections/mcp.ts+++ b/packages/eve/src/public/definitions/connections/mcp.ts@@ -28,6 +28,12 @@ export interface McpClientConnectionDefinition {* Must support Streamable HTTP or SSE transport.*/readonly url: string;+ /**+ * Whether to discover the server's protocol before initialization.+ * Defaults to enabled. Set to false for servers that require the older+ * initialize handshake; that handshake still negotiates a supported version.+ */+ readonly protocolVersionDiscovery?: boolean;/*** Human-readable summary of the connection and its tools.*diff --git a/packages/eve/src/runtime/connections/mcp-client.integration.test.ts b/packages/eve/src/runtime/connections/mcp-client.integration.test.tsnew file mode 100644index 000000000..fcb6f0179--- /dev/null+++ b/packages/eve/src/runtime/connections/mcp-client.integration.test.ts@@ -0,0 +1,175 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++import {+ ROOT_COMPILED_AGENT_NODE_ID,+ type CompiledConnectionDefinition,+} from "#compiler/manifest.js";+import { normalizeMcpClientConnectionDefinition } from "#internal/authored-definition/connection.js";+import { defineMcpClientConnection } from "#public/definitions/connections/mcp.js";+import {+ resolveConnectionDefinition,+ resolveDynamicConnectionValue,+} from "#runtime/resolve-connection.js";+import { McpConnectionClient } from "#runtime/connections/mcp-client.js";++describe.each(["static", "dynamic"] as const)(+ "%s MCP protocol configuration with the bundled client",+ (kind) => {+ const requests: { method: string; protocolVersion: string | null }[] = [];+ let client: McpConnectionClient;+ let discoveryError: { code: number; message: string; data?: unknown } | undefined;+ let initializeError: { code: number; message: string } | undefined;++ async function createClient(protocolVersionDiscovery?: boolean) {+ const authored = defineMcpClientConnection({+ description: "Support cases",+ headers: { Authorization: "Bearer fixture-token", "X-Workspace": "fixture-workspace" },+ instanceKey: "fixture-workspace",+ protocolVersionDiscovery,+ url: "https://mcp.example.com/mcp",+ });+ const normalized = normalizeMcpClientConnectionDefinition(authored, "Invalid connection:");+ const compiled: CompiledConnectionDefinition = {+ connectionName: "plain",+ description: normalized.description,+ logicalPath: "connections/plain.ts",+ protocol: "mcp",+ sourceId: "connections/plain",+ sourceKind: "module",+ url: normalized.url,+ };+ const resolved =+ kind === "dynamic"+ ? resolveDynamicConnectionValue(authored, compiled)+ : await resolveConnectionDefinition(+ compiled,+ {+ nodes: {+ [ROOT_COMPILED_AGENT_NODE_ID]: {+ modules: { [compiled.sourceId]: { default: authored } },+ },+ },+ },+ undefined,+ );+ client = new McpConnectionClient(resolved);+ return client;+ }++ beforeEach(() => {+ requests.length = 0;+ discoveryError = {+ code: -32022,+ data: {+ requested: "2026-07-28",+ supported: ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"],+ },+ message: "Unsupported protocol version",+ };+ initializeError = undefined;++ // Replace only HTTP I/O: eve's connection, bundled SDK, and protocol parsing stay real.+ vi.stubGlobal("fetch", async (input: string | URL | Request, init?: RequestInit) => {+ const request = new Request(input, init);+ expect(request.url).toBe("https://mcp.example.com/mcp");+ expect(request.headers.get("Authorization")).toBe("Bearer fixture-token");+ expect(request.headers.get("X-Workspace")).toBe("fixture-workspace");+ expect(request.method).toBe("POST");+ const message = (await request.json()) as {+ id?: number;+ method: string;+ params?: { name?: string; protocolVersion?: string };+ };+ const protocolVersion = request.headers.get("MCP-Protocol-Version");+ requests.push({ method: message.method, protocolVersion });++ let result: Record<string, unknown>;+ switch (message.method) {+ case "server/discover":+ if (discoveryError !== undefined) {+ return Response.json({ jsonrpc: "2.0", id: message.id, error: discoveryError });+ }+ result = { capabilities: { tools: {} }, supportedVersions: ["2026-07-28"] };+ break;+ case "initialize":+ expect(protocolVersion).toBe("2025-11-25");+ expect(message.params?.protocolVersion).toBe("2025-11-25");+ if (initializeError !== undefined) {+ return Response.json({ jsonrpc: "2.0", id: message.id, error: initializeError });+ }+ result = {+ capabilities: { tools: {} },+ protocolVersion: "2025-11-25",+ serverInfo: { name: "support-fixture", version: "1.0.0" },+ };+ break;+ case "notifications/initialized":+ return new Response(null, { status: 202 });+ case "tools/list":+ result = {+ tools: [{ name: "getMyUser", inputSchema: { type: "object", properties: {} } }],+ };+ break;+ case "tools/call":+ expect(message.params?.name).toBe("getMyUser");+ result = { content: [{ type: "text", text: "fixture-user" }] };+ break;+ default:+ throw new Error(`Unexpected MCP method: ${message.method}`);+ }+ return Response.json({+ jsonrpc: "2.0",+ id: message.id,+ result: protocolVersion === "2026-07-28" ? { ...result, resultType: "complete" } : result,+ });+ });+ });++ afterEach(async () => {+ await client?.close();+ vi.unstubAllGlobals();+ });++ it("initializes and calls Plain-style tools with discovery disabled", async () => {+ await createClient(false);+ await expect(client.getToolMetadata()).resolves.toEqual([+ expect.objectContaining({ name: "getMyUser" }),+ ]);+ await expect(client.executeTool("getMyUser", {}, { callId: "read-user" })).resolves.toEqual({+ content: [{ type: "text", text: "fixture-user" }],+ isError: false,+ });+ expect(requests).toEqual([+ { method: "initialize", protocolVersion: "2025-11-25" },+ { method: "notifications/initialized", protocolVersion: "2025-11-25" },+ { method: "tools/list", protocolVersion: "2025-11-25" },+ { method: "tools/call", protocolVersion: "2025-11-25" },+ ]);+ });++ it.each([undefined, true])("keeps discovery enabled when the option is %s", async (option) => {+ await createClient(option);+ discoveryError = undefined;+ await expect(client.getToolMetadata()).resolves.toEqual([+ expect.objectContaining({ name: "getMyUser" }),+ ]);+ expect(requests).toEqual([+ { method: "server/discover", protocolVersion: "2026-07-28" },+ { method: "tools/list", protocolVersion: "2026-07-28" },+ ]);+ });++ it("preserves Plain's version error when discovery is not disabled", async () => {+ await createClient();+ await expect(client.connect()).rejects.toMatchObject(discoveryError!);+ expect(requests).toEqual([{ method: "server/discover", protocolVersion: "2026-07-28" }]);+ });++ it("propagates a failed handshake without retrying it or switching transports", async () => {+ await createClient(false);+ initializeError = { code: -32603, message: "Initialization failed" };+ await expect(client.connect()).rejects.toMatchObject(initializeError);+ expect(requests).toEqual([{ method: "initialize", protocolVersion: "2025-11-25" }]);+ });+ },+);diff --git a/packages/eve/src/runtime/connections/mcp-client.test.ts b/packages/eve/src/runtime/connections/mcp-client.test.tsindex 157934fc1..92d6e4b85 100644--- a/packages/eve/src/runtime/connections/mcp-client.test.ts+++ b/packages/eve/src/runtime/connections/mcp-client.test.ts@@ -73,6 +73,31 @@ describe("McpConnectionClient", () => {createMCPClient.mockReset();});+ it.each([false, true])(+ "preserves protocol discovery %s when switching to SSE",+ async (protocolVersionDiscovery) => {+ createMCPClient.mockRejectedValueOnce({ response: { status: 405 } });+ createMCPClient.mockResolvedValueOnce({ close: vi.fn() });+ const client = new McpConnectionClient(makeConnection({ protocolVersionDiscovery }));+ await client.connect();+ expect(createMCPClient).toHaveBeenCalledTimes(2);+ expect(createMCPClient).toHaveBeenNthCalledWith(+ 1,+ expect.objectContaining({+ protocolVersionDiscovery,+ transport: expect.objectContaining({ type: "http" }),+ }),+ );+ expect(createMCPClient).toHaveBeenNthCalledWith(+ 2,+ expect.objectContaining({+ protocolVersionDiscovery,+ transport: expect.objectContaining({ type: "sse" }),+ }),+ );+ },+ );+it("hides provided arguments from schemas and adds resolved values at execution", async () => {const execute = vi.fn().mockResolvedValue({ ok: true });const toolsFromDefinitions = vi.fn().mockReturnValue({ lookup: { execute } });@@ -171,6 +196,7 @@ describe("McpConnectionClient", () => {await expect(mcpClient.connect()).resolves.toBe(client);expect(createMCPClient).toHaveBeenCalledTimes(1);expect(createMCPClient).toHaveBeenCalledWith({+ protocolVersionDiscovery: undefined,transport: {headers: {Authorization: "Bearer test-token",@@ -197,6 +223,7 @@ describe("McpConnectionClient", () => {await expect(mcpClient.connect()).resolves.toBe(client);expect(createMCPClient).toHaveBeenNthCalledWith(1, {+ protocolVersionDiscovery: undefined,transport: {headers: { Authorization: "Bearer test-token" },type: "http",@@ -204,6 +231,7 @@ describe("McpConnectionClient", () => {},});expect(createMCPClient).toHaveBeenNthCalledWith(2, {+ protocolVersionDiscovery: undefined,transport: {headers: { Authorization: "Bearer test-token" },type: "sse",@@ -228,6 +256,7 @@ describe("McpConnectionClient", () => {await expect(mcpClient.connect()).resolves.toBe(client);expect(createMCPClient).toHaveBeenCalledTimes(2);expect(createMCPClient).toHaveBeenNthCalledWith(2, {+ protocolVersionDiscovery: undefined,transport: {headers: { Authorization: "Bearer test-token" },type: "sse",@@ -250,6 +279,7 @@ describe("McpConnectionClient", () => {await expect(mcpClient.connect()).resolves.toBe(client);expect(createMCPClient).toHaveBeenCalledTimes(2);expect(createMCPClient).toHaveBeenNthCalledWith(2, {+ protocolVersionDiscovery: undefined,transport: {headers: { Authorization: "Bearer test-token" },type: "sse",@@ -274,6 +304,7 @@ describe("McpConnectionClient", () => {await expect(mcpClient.connect()).resolves.toBe(client);expect(createMCPClient).toHaveBeenCalledTimes(2);expect(createMCPClient).toHaveBeenNthCalledWith(2, {+ protocolVersionDiscovery: undefined,transport: {headers: { Authorization: "Bearer test-token" },type: "sse",@@ -293,6 +324,7 @@ describe("McpConnectionClient", () => {await expect(mcpClient.connect()).rejects.toBe(error);expect(createMCPClient).toHaveBeenCalledTimes(1);expect(createMCPClient).toHaveBeenCalledWith({+ protocolVersionDiscovery: undefined,transport: {headers: { Authorization: "Bearer test-token" },type: "http",diff --git a/packages/eve/src/runtime/connections/mcp-client.ts b/packages/eve/src/runtime/connections/mcp-client.tsindex 474e9a18a..8ecb362ed 100644--- a/packages/eve/src/runtime/connections/mcp-client.ts+++ b/packages/eve/src/runtime/connections/mcp-client.ts@@ -76,6 +76,7 @@ export class McpConnectionClient implements ConnectionClient {try {return await createMCPClient({+ protocolVersionDiscovery: this.#connection.protocolVersionDiscovery,transport: { type: "http", url, headers },});} catch (error) {@@ -83,6 +84,7 @@ export class McpConnectionClient implements ConnectionClient {throw error;}return await createMCPClient({+ protocolVersionDiscovery: this.#connection.protocolVersionDiscovery,transport: { type: "sse", url, headers },});}diff --git a/packages/eve/src/runtime/resolve-connection.ts b/packages/eve/src/runtime/resolve-connection.tsindex 6760326a1..5ed77eac6 100644--- a/packages/eve/src/runtime/resolve-connection.ts+++ b/packages/eve/src/runtime/resolve-connection.ts@@ -83,6 +83,7 @@ export async function resolveConnectionDefinition(instanceId: string;logicalPath: string;protocol: ResolvedConnectionDefinition["protocol"];+ protocolVersionDiscovery?: boolean;sourceId: string;sourceKind: "module";spec?: ResolvedConnectionDefinition["spec"];@@ -126,6 +127,13 @@ export async function resolveConnectionDefinition(}}+ if (definition.protocol === "mcp" && resolvedRecord.protocolVersionDiscovery !== undefined) {+ if (typeof resolvedRecord.protocolVersionDiscovery !== "boolean") {+ throw new Error('"protocolVersionDiscovery" must be a boolean.');+ }+ result.protocolVersionDiscovery = resolvedRecord.protocolVersionDiscovery;+ }+if (hasHeaders) {result.headers = resolvedRecord.headers as Readonly<HeadersDefinition>;}@@ -232,6 +240,7 @@ export function resolveDynamicConnectionValue(sourceId: source.sourceId,sourceKind: "module" as const,toolCall: normalized.toolCall,+ protocolVersionDiscovery: normalized.protocolVersionDiscovery,tools: normalized.tools,url: normalized.url,});diff --git a/packages/eve/src/runtime/types.ts b/packages/eve/src/runtime/types.tsindex a0b45d684..51d6c71aa 100644--- a/packages/eve/src/runtime/types.ts+++ b/packages/eve/src/runtime/types.ts@@ -101,6 +101,7 @@ export type ResolvedScheduleDefinition = Readonly<* server that requires no authentication (e.g. localhost) may omit both.*/export interface ResolvedConnectionDefinition extends ResolvedModuleSourceRef {+ readonly protocolVersionDiscovery?: boolean;readonly approval?: Approval;readonly authorization?: Readonly<AuthorizationDefinition> | ConnectionAuthResolver;readonly connectionName: string;