feat(mcp): give a bot MCP servers of your own

server/contracts.ts

@@ -194,6 +194,11 @@ export interface SendTurnInput {
     /** dweb network daemon: an MCP proxy exposing dweb status, repo, and
      * opencode model access as tools. url is the dweb HTTP base. */
     dweb?: { url: string };
+    /** The user's own stdio MCP servers for this bot, already filtered to
+     * the enabled ones and keyed by `mcpKey(name)`. Unlike every other
+     * entry here the harness does not own these processes' behaviour — it
+     * only spawns what the user configured. */
+    custom?: Array<{ key: string; command: string; args: string[]; env: Record<string, string> }>;
   };
   cwd?: string;
 }

server/drivers/acp/core.ts

@@ -247,6 +247,10 @@ export function createAcpDriver(support: AcpSupport): ProviderDriver<AcpConfig>
         if (agents) {
           servers.push({ name: "agents", command: agents.command, args: agents.args, env: acpEnv(agents.env) });
         }
+        for (const custom of turn.integrations?.custom ?? []) {
+          if (servers.some((server) => server.name === custom.key)) continue;
+          servers.push({ name: custom.key, command: custom.command, args: custom.args, env: acpEnv(custom.env) });
+        }
         const composio = turn.integrations?.composio;
         if (composio) {
           servers.push({

server/drivers/claude.test.ts

@@ -343,6 +343,32 @@ describe("ClaudeDriver turns (fake CLI)", () => {
     expect(seen.argv[seen.argv.indexOf("--allowedTools") + 1]).toContain("mcp__dweb");
   });
 
+  it("mounts the user's own MCP servers and pre-allows their tools", async () => {
+    await create();
+    const dump = join(scratch, "dump.json");
+    process.env.FAKE_CLAUDE_DUMP = dump;
+
+    await instance.adapter.sendTurn({
+      threadId: "t-custom-mcp",
+      text: "hi",
+      integrations: {
+        custom: [{ key: "filesystem", command: "npx", args: ["-y", "server-filesystem"], env: { TOKEN: "s3cret" } }],
+      },
+    });
+    await recorder.until((e) => e.type === "turn.completed");
+
+    const seen = JSON.parse(readFileSync(dump, "utf8"));
+    expect(seen.mcpConfig.mcpServers.filesystem).toMatchObject({
+      command: "npx",
+      args: ["-y", "server-filesystem"],
+      env: { TOKEN: "s3cret" },
+    });
+    // a headless acceptEdits run silently denies anything unlisted
+    expect(seen.argv[seen.argv.indexOf("--allowedTools") + 1]).toContain("mcp__filesystem");
+    // the value rides in the private config file, never on argv
+    expect(JSON.stringify(seen.argv)).not.toContain("s3cret");
+  });
+
   // the harness gates both the integration and the prompt hint on
   // capabilities.composioMcp, so the flag and the mount must agree — a bot
   // told about tools its driver never mounted burns the turn hunting

server/drivers/claude.ts

@@ -626,6 +626,14 @@ export const ClaudeDriver: ProviderDriver<ClaudeConfig> = {
       // accepts a FILE for this flag, so the secrets go in a 0600 file that
       // is removed when the turn settles.
       let mcpConfigPath: string | null = null;
+      // The user's own servers, last so a custom name can never displace a
+      // harness integration; parseMcpServers already refused duplicates
+      // among the custom ones themselves.
+      for (const server of turn.integrations?.custom ?? []) {
+        if (server.key in mcpServers) continue;
+        mcpServers[server.key] = { command: server.command, args: server.args, env: { ...server.env } };
+        allowed.push(`mcp__${server.key}`);
+      }
       if (Object.keys(mcpServers).length) {
         mcpConfigPath = join(mkdtempSync(join(tmpdir(), "omb-mcp-")), "mcp.json");
         writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers }), { mode: 0o600 });

server/index.test.ts

@@ -436,6 +436,43 @@ describe("harness HTTP API", () => {
     }
   });
 
+  it("keeps a custom MCP server's env values off the wire", async () => {
+    const bot = (await api("POST", "/api/bots")).body.bot;
+    try {
+      const saved = await api("PATCH", `/api/bots/${bot.id}`, {
+        mcpServers: [{ name: "Filesystem", command: "npx", args: ["-y", "srv"], env: { TOKEN: "s3cret" } }],
+      });
+      expect(saved.status).toBe(200);
+      // the value is stored, but a payload only ever carries the key name
+      expect(saved.body.bot.mcpServers[0].env).toEqual({ TOKEN: true });
+      expect(JSON.stringify(saved.body)).not.toContain("s3cret");
+      const listed = await api("GET", "/api/bots");
+      expect(JSON.stringify(listed.body)).not.toContain("s3cret");
+
+      // an editor that never saw the value can still save: `true` means
+      // "keep what is stored", and the id survives the rename
+      const id = saved.body.bot.mcpServers[0].id;
+      const renamed = await api("PATCH", `/api/bots/${bot.id}`, {
+        mcpServers: [{ id, name: "Documents", command: "npx", args: ["-y", "srv"], env: { TOKEN: true } }],
+      });
+      expect(renamed.status).toBe(200);
+      expect(renamed.body.bot.mcpServers[0].id).toBe(id);
+      expect(renamed.body.bot.mcpServers[0].name).toBe("Documents");
+
+      // two servers that fold onto one name are refused where a person reads it
+      const collision = await api("PATCH", `/api/bots/${bot.id}`, {
+        mcpServers: [
+          { name: "My Files", command: "a" },
+          { name: "my-files", command: "b" },
+        ],
+      });
+      expect(collision.status).toBe(400);
+      expect(collision.body.error).toMatch(/same name/i);
+    } finally {
+      await api("DELETE", `/api/bots/${bot.id}`);
+    }
+  });
+
   it("keeps direct-message channels folderless at the API boundary", async () => {
     const attempted = await api("PATCH", "/api/groups/test-dm", { cwd: home });
     expect(attempted.status).toBe(400);

server/index.ts

@@ -12,6 +12,7 @@ import { botAvatarUrlFromStoredPath } from "../shared/bot-avatar.ts";
 
 import { approvalKey, autoVerdict } from "./auto-approve.ts";
 import { appendDecision, readDecisions } from "./decision-log.ts";
+import { enabledMcpServers, mcpKey, parseMcpServers, redactMcpServers } from "./mcp-servers.ts";
 import { validateBotCwd } from "./bot-cwd.ts";
 import { attachmentExists, extensionForMime, IMAGE_MAX_BYTES, readAttachment, saveImage, type SavedAttachment } from "./attachments.ts";
 import {
@@ -271,8 +272,13 @@ store.seedIfEmpty();
 const wireTask = ({ resumeCursors, lastInstanceId, ...task }: TaskRecord) => task;
 
 const wireBot = (bot: NonNullable<ReturnType<typeof store.bot>>) => {
-  const { resumeCursors, tasks, ...rest } = bot;
-  return { ...rest, avatarUrl: rest.avatarUrl ?? null, ...(tasks ? { tasks: tasks.map(wireTask) } : {}) };
+  const { resumeCursors, tasks, mcpServers, ...rest } = bot;
+  // The ONE projection every bot payload passes through, which is why the
+  // env values are dropped here: a second stripping site is a second place to
+  // forget one. `undefined` is omitted by JSON, so a bot with no servers is
+  // wired exactly as it was before.
+  const wiredMcp = mcpServers ? redactMcpServers(mcpServers) : undefined;
+  return { ...rest, avatarUrl: rest.avatarUrl ?? null, mcpServers: wiredMcp, ...(tasks ? { tasks: tasks.map(wireTask) } : {}) };
 };
 
 /** Profile URLs are app-owned references, not merely strings with a trusted
@@ -1459,6 +1465,15 @@ async function startTurn(
       // tools that would fail on every call or spawn an unnecessary proxy.
       const dwebUrl = process.env.DWEB_URL?.trim();
       if (dwebUrl) integrations.dweb = { url: dwebUrl };
+      const custom = enabledMcpServers(bot.mcpServers);
+      if (custom.length) {
+        integrations.custom = custom.map((server) => ({
+          key: mcpKey(server.name),
+          command: server.command,
+          args: server.args,
+          env: server.env,
+        }));
+      }
       const wants = opts?.runOn === "cloud" ? "cloud" : bot.computer; // cloud routine overrides the MAUS default
       // Cloud routines always use Box/BoxAgent. The per-bot backend applies
       // only to ordinary turns that mount a computer into the local agent.
@@ -3524,6 +3539,14 @@ const server = createServer(async (req, res) => {
       for (const key of ["modelSelection", "unread", "computer", "cloudBackend", "color", "mascotExpression", "pinned", "hidden"] as const) {
         if (body[key] !== undefined) patch[key] = body[key];
       }
+      if (body.mcpServers !== undefined) {
+        // Parsed against what is STORED, so an editor that only ever saw
+        // `env: { KEY: true }` can save without sending the value back —
+        // and so a rename keeps the id it arrived with.
+        const parsed = parseMcpServers(body.mcpServers, store.bot(m[1])?.mcpServers ?? []);
+        if (!parsed.ok) return json(res, 400, { error: parsed.error });
+        patch.mcpServers = parsed.servers;
+      }
       // one pinned message per thread; null/"" clears. The id is not
       // validated against the transcript here — a pin whose message was
       // edited to another branch or deleted simply resolves to nothing.

server/mcp-servers.test.ts

@@ -0,0 +1,109 @@
+// The invariants a custom MCP server has to hold, taken from the review of
+// the earlier attempt (PR #61): a name can never become a routing identity,
+// two servers can never collide into one, and an env value can never leave
+// the server.
+import { describe, expect, it } from "vitest";
+
+import {
+  enabledMcpServers,
+  mcpKey,
+  parseMcpServers,
+  redactMcpServers,
+  type McpServerSpec,
+  type McpServersInput,
+} from "./mcp-servers.ts";
+
+let n = 0;
+const ids = () => `id-${++n}`;
+const spec = (over: Partial<McpServerSpec> = {}): McpServerSpec => ({
+  id: "stored-1",
+  name: "Filesystem",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem"],
+  env: { TOKEN: "s3cret" },
+  enabled: true,
+  ...over,
+});
+
+describe("mcpKey", () => {
+  it("folds a label into something an agent can prefix a tool with", () => {
+    expect(mcpKey("Filesystem")).toBe("filesystem");
+    expect(mcpKey("My Files (work)")).toBe("my-files-work");
+    expect(mcpKey("  spaced  out  ")).toBe("spaced-out");
+  });
+});
+
+describe("parseMcpServers", () => {
+  // Half of these cases feed shapes the type forbids — which is the point:
+  // this parser IS the boundary, and a hand-written PATCH never typechecks.
+  // SAFETY: the cast reaches only the runtime schema under test.
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters
+  const parse = (value: unknown, existing: McpServerSpec[] = []) =>
+    parseMcpServers(value as McpServersInput, existing, ids);
+
+  it("accepts a minimal server and fills in the rest", () => {
+    const out = parse([{ name: "files", command: "npx" }]);
+    expect(out.ok).toBe(true);
+    if (!out.ok) return;
+    expect(out.servers[0]).toMatchObject({ name: "files", command: "npx", args: [], env: {}, enabled: true });
+    expect(out.servers[0].id).toMatch(/^id-/);
+  });
+
+  it("refuses two servers that would answer to the same name", () => {
+    const out = parse([
+      { name: "My Files", command: "a" },
+      { name: "my files", command: "b" },
+    ]);
+    expect(out.ok).toBe(false);
+    if (out.ok) return;
+    expect(out.error).toMatch(/same name/i);
+  });
+
+  it("keeps a server's id across a rename, so a turn cannot be re-pointed", () => {
+    const stored = spec({ id: "stored-1", name: "Filesystem" });
+    const out = parse([{ id: "stored-1", name: "Documents", command: "npx" }], [stored]);
+    expect(out.ok).toBe(true);
+    if (!out.ok) return;
+    expect(out.servers[0].id).toBe("stored-1");
+    expect(out.servers[0].name).toBe("Documents");
+  });
+
+  it("keeps a stored env value when the editor sends it back untouched", () => {
+    const stored = spec();
+    const out = parse([{ id: "stored-1", name: "Filesystem", command: "npx", env: { TOKEN: true } }], [stored]);
+    expect(out.ok).toBe(true);
+    if (!out.ok) return;
+    expect(out.servers[0].env).toEqual({ TOKEN: "s3cret" });
+  });
+
+  it("refuses a placeholder env value with nothing stored behind it", () => {
+    const out = parse([{ name: "files", command: "npx", env: { TOKEN: true } }]);
+    expect(out.ok).toBe(false);
+    if (out.ok) return;
+    expect(out.error).toMatch(/TOKEN/);
+  });
+
+  it("rejects the shapes a hand-written PATCH gets wrong", () => {
+    expect(parse("nope").ok).toBe(false);
+    expect(parse([{ command: "npx" }]).ok).toBe(false);
+    expect(parse([{ name: "files" }]).ok).toBe(false);
+    expect(parse([{ name: "files", command: "npx", args: "-y" }]).ok).toBe(false);
+    expect(parse([{ name: "files", command: "npx", env: { A: 3 } }]).ok).toBe(false);
+    expect(parse([{ name: "   ", command: "npx" }]).ok).toBe(false);
+  });
+});
+
+describe("redactMcpServers", () => {
+  it("replaces every env value with a marker, keeping the names", () => {
+    const wire = redactMcpServers([spec({ env: { TOKEN: "s3cret", REGION: "eu" } })]);
+    expect(wire[0].env).toEqual({ TOKEN: true, REGION: true });
+    expect(JSON.stringify(wire)).not.toContain("s3cret");
+  });
+});
+
+describe("enabledMcpServers", () => {
+  it("drops the disabled ones and tolerates a bot with none", () => {
+    expect(enabledMcpServers([spec({ id: "a" }), spec({ id: "b", enabled: false })]).map((s) => s.id)).toEqual(["a"]);
+    expect(enabledMcpServers(undefined)).toEqual([]);
+  });
+});