Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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);