feat(agent): add remote MCP servers CLI param for agent-server (#1151)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: skoob13

packages/agent/src/server/agent-server.ts

@@ -595,7 +595,7 @@ export class AgentServer {
 
     const sessionResponse = await clientConnection.newSession({
       cwd: this.config.repositoryPath,
-      mcpServers: [],
+      mcpServers: this.config.mcpServers ?? [],
       _meta: {
         sessionId: payload.run_id,
         taskRunId: payload.run_id,

packages/agent/src/server/bin.ts

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import { z } from "zod";
 import { AgentServer } from "./agent-server.js";
+import { mcpServersSchema } from "./schemas.js";
 
 const envSchema = z.object({
   JWT_PUBLIC_KEY: z
@@ -45,6 +46,10 @@ program
   .requiredOption("--repositoryPath <path>", "Path to the repository")
   .requiredOption("--taskId <id>", "Task ID")
   .requiredOption("--runId <id>", "Task run ID")
+  .option(
+    "--mcpServers <json>",
+    "MCP servers config as JSON array (ACP McpServer[] format)",
+  )
   .action(async (options) => {
     const envResult = envSchema.safeParse(process.env);
 
@@ -60,6 +65,29 @@ program
 
     const mode = options.mode === "background" ? "background" : "interactive";
 
+    let mcpServers: z.infer<typeof mcpServersSchema> | undefined;
+    if (options.mcpServers) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(options.mcpServers);
+      } catch {
+        program.error("--mcpServers must be valid JSON");
+        return;
+      }
+
+      const result = mcpServersSchema.safeParse(parsed);
+      if (!result.success) {
+        const errors = result.error.issues
+          .map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`)
+          .join("\n");
+        program.error(
+          `--mcpServers validation failed (only remote http/sse servers are supported):\n${errors}`,
+        );
+        return;
+      }
+      mcpServers = result.data;
+    }
+
     const server = new AgentServer({
       port: parseInt(options.port, 10),
       jwtPublicKey: env.JWT_PUBLIC_KEY,
@@ -70,6 +98,7 @@ program
       mode,
       taskId: options.taskId,
       runId: options.runId,
+      mcpServers,
     });
 
     process.on("SIGINT", async () => {

packages/agent/src/server/schemas.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import { mcpServersSchema } from "./schemas.js";
+
+describe("mcpServersSchema", () => {
+  it("accepts a valid HTTP server", () => {
+    const result = mcpServersSchema.safeParse([
+      {
+        type: "http",
+        name: "my-server",
+        url: "https://mcp.example.com",
+        headers: [{ name: "Authorization", value: "Bearer tok" }],
+      },
+    ]);
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual([
+      {
+        type: "http",
+        name: "my-server",
+        url: "https://mcp.example.com",
+        headers: [{ name: "Authorization", value: "Bearer tok" }],
+      },
+    ]);
+  });
+
+  it("accepts a valid SSE server", () => {
+    const result = mcpServersSchema.safeParse([
+      {
+        type: "sse",
+        name: "sse-server",
+        url: "https://sse.example.com/events",
+        headers: [],
+      },
+    ]);
+    expect(result.success).toBe(true);
+  });
+
+  it("defaults headers to empty array when omitted", () => {
+    const result = mcpServersSchema.safeParse([
+      { type: "http", name: "no-headers", url: "https://example.com" },
+    ]);
+    expect(result.success).toBe(true);
+    expect(result.data?.[0].headers).toEqual([]);
+  });
+
+  it("accepts multiple servers", () => {
+    const result = mcpServersSchema.safeParse([
+      { type: "http", name: "a", url: "https://a.com" },
+      { type: "sse", name: "b", url: "https://b.com" },
+    ]);
+    expect(result.success).toBe(true);
+    expect(result.data).toHaveLength(2);
+  });
+
+  it("accepts an empty array", () => {
+    const result = mcpServersSchema.safeParse([]);
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual([]);
+  });
+
+  it("rejects stdio servers", () => {
+    const result = mcpServersSchema.safeParse([
+      {
+        type: "stdio",
+        name: "local",
+        command: "/usr/bin/mcp",
+        args: [],
+      },
+    ]);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects servers with no type", () => {
+    const result = mcpServersSchema.safeParse([
+      { name: "missing-type", url: "https://example.com" },
+    ]);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects servers with empty name", () => {
+    const result = mcpServersSchema.safeParse([
+      { type: "http", name: "", url: "https://example.com" },
+    ]);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects servers with invalid url", () => {
+    const result = mcpServersSchema.safeParse([
+      { type: "http", name: "bad-url", url: "not-a-url" },
+    ]);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects servers with missing url", () => {
+    const result = mcpServersSchema.safeParse([
+      { type: "http", name: "no-url" },
+    ]);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects non-array input", () => {
+    expect(mcpServersSchema.safeParse("not-array").success).toBe(false);
+    expect(mcpServersSchema.safeParse({}).success).toBe(false);
+    expect(mcpServersSchema.safeParse(null).success).toBe(false);
+  });
+
+  it("rejects headers with missing fields", () => {
+    const result = mcpServersSchema.safeParse([
+      {
+        type: "http",
+        name: "bad-headers",
+        url: "https://example.com",
+        headers: [{ name: "X-Key" }],
+      },
+    ]);
+    expect(result.success).toBe(false);
+  });
+});

packages/agent/src/server/schemas.ts

@@ -1,5 +1,21 @@
 import { z } from "zod";
 
+const httpHeaderSchema = z.object({
+  name: z.string(),
+  value: z.string(),
+});
+
+const remoteMcpServerSchema = z.object({
+  type: z.enum(["http", "sse"]),
+  name: z.string().min(1, "MCP server name is required"),
+  url: z.string().url("MCP server url must be a valid URL"),
+  headers: z.array(httpHeaderSchema).default([]),
+});
+
+export const mcpServersSchema = z.array(remoteMcpServerSchema);
+
+export type RemoteMcpServer = z.infer<typeof remoteMcpServerSchema>;
+
 export const jsonRpcRequestSchema = z.object({
   jsonrpc: z.literal("2.0"),
   method: z.string(),

packages/agent/src/server/types.ts

@@ -1,4 +1,5 @@
 import type { AgentMode } from "../types.js";
+import type { RemoteMcpServer } from "./schemas.js";
 
 export interface AgentServerConfig {
   port: number;
@@ -11,4 +12,5 @@ export interface AgentServerConfig {
   taskId: string;
   runId: string;
   version?: string;
+  mcpServers?: RemoteMcpServer[];
 }