The Open Framework for Building Agents
refactor(eve): align MCP routes and protected-resource metadata (#2114)
Allen Zhoucb2fa2a9f511
diff --git a/.changeset/tidy-mcp-routes.md b/.changeset/tidy-mcp-routes.mdnew file mode 100644index 000000000..81f4680e3--- /dev/null+++ b/.changeset/tidy-mcp-routes.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Configure MCP channel endpoints with `route`, default them to `/eve/v1/mcp`, and derive OAuth protected-resource metadata paths from the MCP resource identifier.diff --git a/packages/eve/src/internal/invocation/mcp-agent-channel.scenario.test.ts b/packages/eve/src/internal/invocation/mcp-agent-channel.scenario.test.tsindex f713c2b0f..d520a956a 100644--- a/packages/eve/src/internal/invocation/mcp-agent-channel.scenario.test.ts+++ b/packages/eve/src/internal/invocation/mcp-agent-channel.scenario.test.ts@@ -205,7 +205,7 @@ async function mcpRequest(headers["mcp-protocol-version"] = MCP_PROTOCOL_VERSION;if (typeof params.name === "string") headers["mcp-name"] = params.name;}- return await fetch(new URL("/mcp", serverUrl), {+ return await fetch(new URL("/eve/v1/mcp", serverUrl), {body: JSON.stringify({id: crypto.randomUUID(),jsonrpc: "2.0",diff --git a/packages/eve/src/public/channels/mcp.test.ts b/packages/eve/src/public/channels/mcp.test.tsindex c2a27284d..25fbad3c1 100644--- a/packages/eve/src/public/channels/mcp.test.ts+++ b/packages/eve/src/public/channels/mcp.test.ts@@ -28,9 +28,9 @@ describe("mcpChannel", () => {it("publishes task-mode durable invocation compatibility tools", async () => {const channel = mcpChannel({ auth: none() });expect(channel.routes.map((route) => `${route.method} ${route.path}`)).toEqual([- "GET /mcp",- "POST /mcp",- "DELETE /mcp",+ "GET /eve/v1/mcp",+ "POST /eve/v1/mcp",+ "DELETE /eve/v1/mcp",]);const postRoute = channel.routes[1]!;if (postRoute.transport === "websocket") throw new Error("expected HTTP route");@@ -225,12 +225,12 @@ describe("mcpChannel", () => {scopes: ["agent:invoke"],},),- path: "/delegate",+ route: "/delegate",});expect(channel.routes.map((route) => `${route.method} ${route.path}`)).toEqual([- "GET /.well-known/oauth-protected-resource",- "HEAD /.well-known/oauth-protected-resource",- "OPTIONS /.well-known/oauth-protected-resource",+ "GET /.well-known/oauth-protected-resource/delegate",+ "HEAD /.well-known/oauth-protected-resource/delegate",+ "OPTIONS /.well-known/oauth-protected-resource/delegate","GET /delegate","POST /delegate","DELETE /delegate",@@ -239,7 +239,7 @@ describe("mcpChannel", () => {const metadataRoute = channel.routes[0]!;if (metadataRoute.transport === "websocket") throw new Error("expected HTTP route");const metadata = await metadataRoute.handler(- requestWithHost("https://private.example/.well-known/oauth-protected-resource"),+ requestWithHost("https://private.example/.well-known/oauth-protected-resource/delegate"),{} as never,);await expect(metadata.json()).resolves.toEqual({@@ -258,7 +258,7 @@ describe("mcpChannel", () => {expect(response.status).toBe(401);const challenge = response.headers.get("www-authenticate");expect(challenge).toContain(- 'resource_metadata="https://agent.example/.well-known/oauth-protected-resource"',+ 'resource_metadata="https://agent.example/.well-known/oauth-protected-resource/delegate"',);expect(challenge).toContain('Basic realm="eve"');expect(challenge).toContain('scope="agent:invoke"');@@ -277,7 +277,7 @@ describe("mcpChannel", () => {const genericRoute = genericChannel.routes[4]!;if (genericRoute.transport === "websocket") throw new Error("expected HTTP route");const generic = await genericRoute.handler(- requestWithHost("https://agent.example/mcp", { method: "POST" }),+ requestWithHost("https://agent.example/eve/v1/mcp", { method: "POST" }),{} as never,);expect(generic.status).toBe(403);@@ -301,7 +301,7 @@ describe("mcpChannel", () => {const scopedRoute = scopedChannel.routes[4]!;if (scopedRoute.transport === "websocket") throw new Error("expected HTTP route");const scoped = await scopedRoute.handler(- requestWithHost("https://agent.example/mcp", { method: "POST" }),+ requestWithHost("https://agent.example/eve/v1/mcp", { method: "POST" }),{} as never,);const scopedChallenge = scoped.headers.get("www-authenticate");@@ -310,7 +310,7 @@ describe("mcpChannel", () => {expect(scopedChallenge).toContain('scope="agent:admin"');expect(scopedChallenge).not.toContain('scope="agent:invoke"');expect(scopedChallenge).toContain(- 'resource_metadata="https://agent.example/.well-known/oauth-protected-resource"',+ 'resource_metadata="https://agent.example/.well-known/oauth-protected-resource/eve/v1/mcp"',);expect(scopedChallenge?.match(/\bBearer\b/g)).toHaveLength(1);});@@ -328,7 +328,7 @@ describe("mcpChannel", () => {const route = channel.routes[4]!;if (route.transport === "websocket") throw new Error("expected HTTP route");const response = await route.handler(- requestWithHost("https://agent.example/mcp", {+ requestWithHost("https://agent.example/eve/v1/mcp", {headers: { authorization: "Bearer expired-token" },method: "POST",}),@@ -340,7 +340,7 @@ describe("mcpChannel", () => {expect(challenge).toContain('error="invalid_token"');expect(challenge).toContain('scope="agent:invoke"');expect(challenge).toContain(- 'resource_metadata="https://agent.example/.well-known/oauth-protected-resource"',+ 'resource_metadata="https://agent.example/.well-known/oauth-protected-resource/eve/v1/mcp"',);expect(challenge?.match(/\bBearer\b/g)).toHaveLength(1);});@@ -348,12 +348,12 @@ describe("mcpChannel", () => {it("derives the protected resource from the public request origin", async () => {const channel = mcpChannel({auth: oauthResource(() => null, { issuer: "https://issuer.example" }),- path: "/delegate",+ route: "/delegate",});const route = channel.routes[0]!;if (route.transport === "websocket") throw new Error("expected HTTP route");const response = await route.handler(- requestWithHost("https://agent.example/.well-known/oauth-protected-resource"),+ requestWithHost("https://agent.example/.well-known/oauth-protected-resource/delegate"),{} as never,);await expect(response.json()).resolves.toEqual({@@ -362,6 +362,20 @@ describe("mcpChannel", () => {});});+ it("allows overriding the protected-resource metadata path", () => {+ const channel = mcpChannel({+ auth: oauthResource(() => null, {+ issuer: "https://issuer.example",+ metadataPath: "/.well-known/custom-resource",+ }),+ });+ expect(channel.routes.slice(0, 3).map((route) => `${route.method} ${route.path}`)).toEqual([+ "GET /.well-known/custom-resource",+ "HEAD /.well-known/custom-resource",+ "OPTIONS /.well-known/custom-resource",+ ]);+ });+it("serves protected-resource metadata to cross-origin browser clients", async () => {const channel = mcpChannel({auth: oauthResource(() => null, { issuer: "https://issuer.example" }),@@ -380,7 +394,7 @@ describe("mcpChannel", () => {const origin = "https://client.example";const get = await getRoute.handler(- requestWithHost("https://agent.example/.well-known/oauth-protected-resource", {+ requestWithHost("https://agent.example/.well-known/oauth-protected-resource/eve/v1/mcp", {headers: { origin },}),{} as never,@@ -389,7 +403,7 @@ describe("mcpChannel", () => {expect(get.headers.get("access-control-allow-origin")).toBe("*");const head = await headRoute.handler(- requestWithHost("https://agent.example/.well-known/oauth-protected-resource", {+ requestWithHost("https://agent.example/.well-known/oauth-protected-resource/eve/v1/mcp", {headers: { origin },method: "HEAD",}),@@ -401,7 +415,7 @@ describe("mcpChannel", () => {expect(await head.text()).toBe("");const options = await optionsRoute.handler(- requestWithHost("https://agent.example/.well-known/oauth-protected-resource", {+ requestWithHost("https://agent.example/.well-known/oauth-protected-resource/eve/v1/mcp", {headers: {"access-control-request-headers": "authorization, mcp-protocol-version","access-control-request-method": "GET",diff --git a/packages/eve/src/public/channels/mcp.ts b/packages/eve/src/public/channels/mcp.tsindex 184ed54b4..685d77566 100644--- a/packages/eve/src/public/channels/mcp.ts+++ b/packages/eve/src/public/channels/mcp.ts@@ -43,8 +43,8 @@ import {export interface McpChannelInput {/** Existing eve route-auth policy. Use `none()` for explicit public access. */readonly auth: AuthFn<Request> | readonly AuthFn<Request>[];- /** Streamable HTTP endpoint path. Defaults to `/mcp`. */- readonly path?: string;+ /** Override the default MCP route path (`/eve/v1/mcp`). */+ readonly route?: string;}/** Public MCP channel exposing durable agent invocation compatibility tools. */@@ -62,7 +62,7 @@ export function mcpChannel(input: McpChannelInput): McpChannel {if (input?.auth === undefined) {throw new Error("mcpChannel requires auth. Use none() for explicit public access.");}- const path = input.path ?? "/mcp";+ const path = input.route ?? "/eve/v1/mcp";const oauth = readOAuthResourceOptions(input.auth);const routes = [GET(@@ -85,7 +85,7 @@ export function mcpChannel(input: McpChannelInput): McpChannel {}function protectedResourceMetadataRoutes(options: OAuthResourceOptions, resourcePath: string) {- const metadataPath = options.metadataPath ?? "/.well-known/oauth-protected-resource";+ const metadataPath = protectedResourceMetadataPath(options, resourcePath);return [GET(metadataPath, async (request) =>protectedResourceMetadataResponse(request, options, resourcePath, false),@@ -97,6 +97,17 @@ function protectedResourceMetadataRoutes(options: OAuthResourceOptions, resource] as const;}+function protectedResourceMetadataPath(+ options: OAuthResourceOptions,+ resourcePath: string,+): string {+ if (options.metadataPath !== undefined) return options.metadataPath;+ const path = options.resource === undefined ? resourcePath : new URL(options.resource).pathname;+ return path === "/"+ ? "/.well-known/oauth-protected-resource"+ : `/.well-known/oauth-protected-resource${path}`;+}+function protectedResourceMetadataResponse(request: Request,options: OAuthResourceOptions,@@ -149,7 +160,7 @@ function addResourceChallenge(options: OAuthResourceOptions,): Response {if (response.status !== 401 && response.status !== 403) return response;- const metadataPath = options.metadataPath ?? "/.well-known/oauth-protected-resource";+ const metadataPath = protectedResourceMetadataPath(options, new URL(request.url).pathname);const publicBase = options.resource ?? new URL(request.url).origin;const metadataUrl = new URL(metadataPath, publicBase).toString();const headers = new Headers(response.headers);