Make tool refresh best effort instead of failing save so we can't end up in a weird state

Author: Griffin Evans

packages/plugins/mcp/src/api/group.ts

@@ -101,6 +101,11 @@ const ConfigureServerPayload = Schema.Struct({
 
 const ConfigureServerResponse = Schema.Struct({
   config: McpIntegrationConfig,
+  toolsRefreshFailed: Schema.Boolean,
+});
+
+const RefreshServerToolsResponse = Schema.Struct({
+  toolsRefreshFailed: Schema.Boolean,
 });
 
 // The configureAuth payload/response — custom auth methods to merge-append
@@ -176,6 +181,13 @@ export const McpGroup = HttpApiGroup.make("mcp")
       error: [InternalError, McpConnectionError, McpToolDiscoveryError, IntegrationNotFound],
     }),
   )
+  .add(
+    HttpApiEndpoint.post("refreshServerTools", "/mcp/servers/:slug/tools/refresh", {
+      params: SlugParams,
+      success: RefreshServerToolsResponse,
+      error: [InternalError, McpConnectionError, McpToolDiscoveryError, IntegrationNotFound],
+    }),
+  )
   .add(
     HttpApiEndpoint.post("configureAuth", "/mcp/servers/:slug/auth", {
       params: SlugParams,

packages/plugins/mcp/src/api/handlers.test.ts

@@ -30,6 +30,7 @@ const failingExtension: McpPluginExtension = {
   reconcileStdioConnections: () => unused,
   getServer: () => Effect.succeed(null),
   configureServer: () => unused,
+  refreshServerTools: () => unused,
   configureAuth: () => unused,
 };
 

packages/plugins/mcp/src/api/handlers.ts

@@ -139,8 +139,15 @@ export const McpHandlers = HttpApiBuilder.group(ExecutorApiWithMcp, "mcp", (hand
       capture(
         Effect.gen(function* () {
           const ext = yield* McpExtensionService;
-          yield* ext.configureServer(path.slug, payload.config);
-          return { config: payload.config };
+          return yield* ext.configureServer(path.slug, payload.config);
+        }),
+      ),
+    )
+    .handle("refreshServerTools", ({ params: path }) =>
+      capture(
+        Effect.gen(function* () {
+          const ext = yield* McpExtensionService;
+          return yield* ext.refreshServerTools(path.slug);
         }),
       ),
     )

packages/plugins/mcp/src/react/EditMcpSource.tsx

@@ -286,6 +286,13 @@ function StdioEdit(props: {
       setError(errorMessageFromExit(exit, "Failed to update command settings"));
       return { ok: false };
     }
+    if (exit.value.toolsRefreshFailed) {
+      return {
+        ok: true,
+        summary:
+          "Command settings updated, but tools could not be refreshed. Check secrets or retry.",
+      };
+    }
     return { ok: true, summary: "Command settings updated." };
   }, [argsDraft, commandDraft, cwdDraft, doConfigure, envDraft, server.config, server.slug]);
 

packages/plugins/mcp/src/react/atoms.ts

@@ -26,5 +26,6 @@ export const probeMcpEndpoint = McpClient.mutation("mcp", "probeEndpoint");
 export const addMcpServer = McpClient.mutation("mcp", "addServer");
 export const removeMcpServer = McpClient.mutation("mcp", "removeServer");
 export const configureMcpServer = McpClient.mutation("mcp", "configureServer");
+export const refreshMcpServerTools = McpClient.mutation("mcp", "refreshServerTools");
 // Merge-append auth methods onto an integration's `authenticationTemplate`.
 export const configureMcpAuth = McpClient.mutation("mcp", "configureAuth");

packages/plugins/mcp/src/sdk/plugin.test.ts

@@ -155,6 +155,27 @@ const withStdioFixtureScript = Effect.acquireRelease(
   ({ dir }) => Effect.promise(() => Fs.rm(dir, { recursive: true, force: true })),
 );
 
+const withFlakyStdioRefreshScript = Effect.acquireRelease(
+  Effect.gen(function* () {
+    const root = Path.join(process.cwd(), ".tmp");
+    yield* Effect.promise(() => Fs.mkdir(root, { recursive: true }));
+    const dir = yield* Effect.promise(() => Fs.mkdtemp(Path.join(root, "mcp-stdio-flaky-")));
+    const script = Path.join(dir, "server.mjs");
+    const counter = Path.join(dir, "attempts.txt");
+    yield* Effect.promise(() =>
+      Fs.writeFile(
+        script,
+        `import fs from "node:fs";\nimport { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";\nimport { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";\nconst toolName = process.argv[2] ?? "two";\nconst counter = process.argv[3];\nconst previous = fs.existsSync(counter) ? Number(fs.readFileSync(counter, "utf8")) : 0;\nconst attempt = previous + 1;\nfs.writeFileSync(counter, String(attempt));\nif (attempt === 2) process.exit(1);\nconst server = new McpServer({ name: "stdio-flaky-fixture", version: "1.0.0" }, { capabilities: {} });\nserver.registerTool(toolName, { description: "Stdio flaky fixture tool", inputSchema: {} }, async () => ({ content: [{ type: "text", text: "ok" }] }));\nawait server.connect(new StdioServerTransport());\n`,
+      ),
+    );
+    return { dir, script, counter } as const;
+  }),
+  ({ dir }) => Effect.promise(() => Fs.rm(dir, { recursive: true, force: true })),
+);
+
+const readStdioAttemptCount = (counter: string) =>
+  Effect.promise(() => Fs.readFile(counter, "utf8")).pipe(Effect.map((value) => Number(value)));
+
 const seedCallToolExecutor = (input: { slug: string; callTool: CallToolResponder }) =>
   Effect.acquireRelease(
     Effect.gen(function* () {
@@ -649,6 +670,86 @@ describe("mcpPlugin", () => {
       ),
   );
 
+  it.effect("configureServer reports post-commit stdio refresh failure as a warning result", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const fixture = yield* withStdioFixtureScript;
+        const flaky = yield* withFlakyStdioRefreshScript;
+        const executor = yield* createExecutor(
+          makeTestConfig({
+            plugins: [
+              memoryCredentialsPlugin(),
+              mcpPlugin({ dangerouslyAllowStdioMCP: true }),
+            ] as const,
+          }),
+        );
+
+        yield* executor.mcp.addServer({
+          transport: "stdio",
+          name: "Stdio refresh warning",
+          slug: "stdio_refresh_warning",
+          command: process.execPath,
+          args: [fixture.script, "one"],
+        });
+
+        const result: unknown = yield* executor.mcp.configureServer("stdio_refresh_warning", {
+          transport: "stdio",
+          command: process.execPath,
+          args: [flaky.script, "two", flaky.counter],
+          authenticationTemplate: [{ slug: "none", kind: "none" }],
+        });
+
+        expect(result).toMatchObject({ toolsRefreshFailed: true });
+        expect(yield* readStdioAttemptCount(flaky.counter)).toBe(2);
+
+        const integration = yield* executor.mcp.getServer("stdio_refresh_warning");
+        expect(integration?.config).toMatchObject({
+          command: process.execPath,
+          args: [flaky.script, "two", flaky.counter],
+        });
+      }),
+    ),
+  );
+
+  it.effect("refreshServerTools retries stdio tool refresh after a warning result", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const fixture = yield* withStdioFixtureScript;
+        const flaky = yield* withFlakyStdioRefreshScript;
+        const executor = yield* createExecutor(
+          makeTestConfig({
+            plugins: [
+              memoryCredentialsPlugin(),
+              mcpPlugin({ dangerouslyAllowStdioMCP: true }),
+            ] as const,
+          }),
+        );
+        const config = {
+          transport: "stdio" as const,
+          command: process.execPath,
+          args: [flaky.script, "two", flaky.counter],
+          authenticationTemplate: [{ slug: "none" as const, kind: "none" as const }],
+        };
+
+        yield* executor.mcp.addServer({
+          transport: "stdio",
+          name: "Stdio refresh retry",
+          slug: "stdio_refresh_retry",
+          command: process.execPath,
+          args: [fixture.script, "one"],
+        });
+
+        const configureResult = yield* executor.mcp.configureServer("stdio_refresh_retry", config);
+        expect(configureResult).toMatchObject({ toolsRefreshFailed: true });
+        expect(yield* readStdioAttemptCount(flaky.counter)).toBe(2);
+
+        const refreshResult = yield* executor.mcp.refreshServerTools("stdio_refresh_retry");
+        expect(refreshResult).toMatchObject({ toolsRefreshFailed: false });
+        expect(yield* readStdioAttemptCount(flaky.counter)).toBe(4);
+      }),
+    ),
+  );
+
   it.effect("configureServer reports missing stdio secret values before preflight", () =>
     Effect.scoped(
       Effect.gen(function* () {

packages/plugins/mcp/src/sdk/plugin.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer, Option, Predicate, Result, Schema } from "effect";
+import { Cause, Effect, Layer, Option, Predicate, Result, Schema } from "effect";
 import type { HttpClient } from "effect/unstable/http";
 
 import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
@@ -1106,8 +1106,25 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
 
       const refreshStdioConnections = (integration: IntegrationSlug) =>
         Effect.gen(function* () {
+          const record = yield* ctx.core.integrations.get(integration);
+          const config = record ? parseMcpIntegrationConfig(record.config) : null;
+          if (!config || config.transport !== "stdio") {
+            return yield* new McpConnectionError({
+              transport: "stdio",
+              message: `Cannot refresh tools for MCP integration ${integration}: stdio config not found.`,
+            });
+          }
+
           const connections = yield* ctx.connections.list({ integration });
           if (connections.length === 0) {
+            const requiredVars = requiredStdioEnvVars(config);
+            if (requiredVars.length > 0) {
+              return yield* new McpConnectionError({
+                transport: "stdio",
+                message: `Cannot refresh tools because no visible connection has values for required environment variables: ${requiredVars.join(", ")}.`,
+              });
+            }
+
             yield* ctx.connections
               .create({
                 owner: "org",
@@ -1136,7 +1153,18 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
           }
 
           const failedNames = yield* Effect.forEach(connections, (connection) =>
-            ctx.connections.refresh(connection).pipe(
+            Effect.gen(function* () {
+              const values = yield* ctx.connections.resolveValues(connection);
+              const connectorInput = yield* buildConnectorInput(
+                config,
+                values,
+                String(connection.template),
+                allowStdio,
+                httpClientLayer,
+              );
+              yield* discoverTools(createMcpConnector(connectorInput));
+              yield* ctx.connections.refresh(connection);
+            }).pipe(
               Effect.as(null),
               Effect.catch(() => Effect.succeed(String(connection.name))),
             ),
@@ -1150,6 +1178,17 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
           }
         });
 
+      const refreshStdioToolsBestEffort = (integration: IntegrationSlug) =>
+        refreshStdioConnections(integration).pipe(
+          Effect.as(false),
+          Effect.catchCause((cause) =>
+            Effect.logWarning("stdio tools refresh failed after config commit").pipe(
+              Effect.annotateLogs("cause", Cause.pretty(cause)),
+              Effect.as(true),
+            ),
+          ),
+        );
+
       const configureServer = (slug: string, config: McpIntegrationConfigType) =>
         Effect.gen(function* () {
           const integration = slugFrom(slug);
@@ -1167,7 +1206,7 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
 
           if (current.transport !== "stdio") {
             yield* ctx.core.integrations.update(integration, { config });
-            return;
+            return { config, toolsRefreshFailed: false } satisfies McpConfigureServerResult;
           }
 
           if (config.transport !== "stdio") {
@@ -1183,7 +1222,7 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
           );
           if (!processConfigChanged) {
             yield* ctx.core.integrations.update(integration, { config });
-            return;
+            return { config, toolsRefreshFailed: false } satisfies McpConfigureServerResult;
           }
 
           yield* preflightStdioConfig(integration, config);
@@ -1193,13 +1232,37 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
               yield* ctx.core.integrations.update(integration, { config });
             }),
           );
-          yield* refreshStdioConnections(integration);
+          const toolsRefreshFailed = yield* refreshStdioToolsBestEffort(integration);
+          return { config, toolsRefreshFailed } satisfies McpConfigureServerResult;
         }).pipe(
           Effect.withSpan("mcp.plugin.configure_server", {
             attributes: { "mcp.integration.slug": slug },
           }),
         );
 
+      const refreshServerTools = (slug: string) =>
+        Effect.gen(function* () {
+          const integration = slugFrom(slug);
+          const record = yield* ctx.core.integrations.get(integration);
+          const current = record ? parseMcpIntegrationConfig(record.config) : null;
+          if (record === null || current === null) {
+            return yield* new IntegrationNotFoundError({ slug: integration });
+          }
+          if (current.transport !== "stdio") {
+            return yield* new McpConnectionError({
+              transport: "auto",
+              message:
+                "MCP tool refresh through the MCP server API is only supported for stdio servers.",
+            });
+          }
+          const toolsRefreshFailed = yield* refreshStdioToolsBestEffort(integration);
+          return { toolsRefreshFailed } satisfies McpRefreshServerToolsResult;
+        }).pipe(
+          Effect.withSpan("mcp.plugin.refresh_server_tools", {
+            attributes: { "mcp.integration.slug": slug },
+          }),
+        );
+
       /** Merge-append auth methods onto the integration's existing
        *  `authenticationTemplate` (custom-method-create flow), mirroring the
        *  OpenAPI/GraphQL `configureAuth`. Returns the merged array. A no-op
@@ -1245,6 +1308,7 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
         reconcileStdioConnections,
         getServer,
         configureServer,
+        refreshServerTools,
         configureAuth,
       };
     },
@@ -1575,6 +1639,15 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
 
 export type McpExtensionFailure = McpConnectionError | McpToolDiscoveryError | StorageFailure;
 
+export interface McpConfigureServerResult {
+  readonly config: McpIntegrationConfigType;
+  readonly toolsRefreshFailed: boolean;
+}
+
+export interface McpRefreshServerToolsResult {
+  readonly toolsRefreshFailed: boolean;
+}
+
 export interface McpPluginExtension {
   readonly probeEndpoint: (
     input: string | McpProbeEndpointInput,
@@ -1598,7 +1671,10 @@ export interface McpPluginExtension {
   readonly configureServer: (
     slug: string,
     config: McpIntegrationConfigType,
-  ) => Effect.Effect<void, McpExtensionFailure | IntegrationNotFoundError>;
+  ) => Effect.Effect<McpConfigureServerResult, McpExtensionFailure | IntegrationNotFoundError>;
+  readonly refreshServerTools: (
+    slug: string,
+  ) => Effect.Effect<McpRefreshServerToolsResult, McpExtensionFailure | IntegrationNotFoundError>;
   readonly configureAuth: (
     slug: string,
     input: McpConfigureAuthInput,