refactor(connections): extract manager.ts as shared configured layer

Introduce connections/manager.ts that holds the configured pool, schema,
and IntegrationProvider as a singleton. Both the dev-server API and MCP
tools now use the same functions (assignConnection, resolveCredentials,
etc.) instead of maintaining separate pools and wrappers.

- Delete resolve-credentials.ts; move resolveCredentials + getAddConnectionUrl
  to manager.ts, move MCP-specific error hints to tool error handlers
- Add real-time connection change notifications: manager notifies listeners
  on assign/unassign, dev-server broadcasts via WebSocket, frontend refetches
- Remove credentials_page_url from list_connections output (redundant with
  get_connection error hints which include workflow/node deep links)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cevian

packages/core/dev-ui/src/hooks/useConnections.ts

@@ -38,6 +38,13 @@ export function useConnections() {
     fetchConnections();
   }, [fetchConnections]);
 
+  // Refetch when notified of external changes (e.g. MCP tool assigned a connection)
+  useEffect(() => {
+    const handler = () => { fetchConnections(); };
+    window.addEventListener("connections-changed", handler);
+    return () => window.removeEventListener("connections-changed", handler);
+  }, [fetchConnections]);
+
   const upsert = useCallback(
     async (mapping: Omit<ConnectionMapping, "updated_at">) => {
       await fetch("/dev/api/connections", {

packages/core/dev-ui/src/hooks/useDAGSocket.ts

@@ -111,6 +111,10 @@ export function useDAGSocket() {
               new CustomEvent("spawned", { detail: message.data.pid }),
             );
             break;
+
+          case "connections-changed":
+            window.dispatchEvent(new CustomEvent("connections-changed"));
+            break;
         }
       } catch {
         // Ignore malformed messages

packages/core/dev-ui/src/types.ts

@@ -50,7 +50,8 @@ export type WSMessage =
   // PTY messages (server → client)
   | { type: "pty-data"; data: string }
   | { type: "pty-exit"; data: { code: number } }
-  | { type: "pty-spawned"; data: { pid: number } };
+  | { type: "pty-spawned"; data: { pid: number } }
+  | { type: "connections-changed" };
 
 // ---- Run History types ----
 

packages/core/src/cli/mcp/lib/resolve-credentials.ts

@@ -2,7 +2,7 @@ import type { ApiFactory } from "@tigerdata/mcp-boilerplate";
 import { execFile } from "node:child_process";
 import { z } from "zod";
 import type { ConnectionCredentials } from "../../../types.js";
-import { resolveCredentials } from "../lib/resolve-credentials.js";
+import { resolveCredentials } from "../../../connections/manager.js";
 import type { ServerContext } from "../types.js";
 
 const DEFAULT_TIMEOUT = 120_000;

packages/core/src/cli/mcp/sandbox-tools/bash.ts

@@ -1,7 +1,7 @@
 import type { ApiFactory } from "@tigerdata/mcp-boilerplate";
 import { z } from "zod";
 import type { ServerContext } from "../types.js";
-import { assignConnection } from "../lib/resolve-credentials.js";
+import { assignConnection } from "../../../connections/manager.js";
 
 const inputSchema = {
   integration_id: z

packages/core/src/cli/mcp/tools/assignConnection.ts

@@ -1,7 +1,7 @@
 import type { ApiFactory } from "@tigerdata/mcp-boilerplate";
 import { z } from "zod";
 import type { ServerContext } from "../types.js";
-import { resolveCredentials } from "../lib/resolve-credentials.js";
+import { resolveCredentials, getAddConnectionUrl } from "../../../connections/manager.js";
 
 const inputSchema = {
   integration_id: z
@@ -74,8 +74,12 @@ export const getConnectionFactory: ApiFactory<
           access_token: credentials.token,
         };
       } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const credentialsUrl = getAddConnectionUrl(integration_id, workflow_name, node_name);
+        const urlHint = credentialsUrl ? ` Add a connection at: ${credentialsUrl}` : "";
         return {
-          error: err instanceof Error ? err.message : String(err),
+          error: `${msg} Use list_connections to check for existing connections, ` +
+            `then assign_connection to assign one.${urlHint}`,
         };
       }
     },

packages/core/src/cli/mcp/tools/getConnection.ts

@@ -1,7 +1,7 @@
 import type { ApiFactory } from "@tigerdata/mcp-boilerplate";
 import { z } from "zod";
 import type { ServerContext } from "../types.js";
-import { createProvider, getCredentialsPageUrl } from "../lib/resolve-credentials.js";
+import { getProvider } from "../../../connections/manager.js";
 
 const inputSchema = {
   integration_id: z
@@ -18,16 +18,11 @@ const outputSchema = {
       display_name: z.string().describe("Human-readable name for the connection"),
     }),
   ).describe("Available connections for this integration"),
-  credentials_page_url: z
-    .string()
-    .optional()
-    .describe("URL to the Dev UI Credentials page where new connections can be added"),
   error: z.string().optional().describe("Error message if listing failed"),
 } as const;
 
 type OutputSchema = {
   connections: Array<{ connection_id: string; display_name: string }>;
-  credentials_page_url?: string;
   error?: string;
 };
 
@@ -49,19 +44,16 @@ export const listConnectionsFactory: ApiFactory<
     },
     fn: async ({ integration_id }): Promise<OutputSchema> => {
       try {
-        const provider = await createProvider();
-        const connections = await provider.listConnections(integration_id);
+        const connections = await getProvider().listConnections(integration_id);
         return {
           connections: connections.map((c) => ({
             connection_id: c.connection_id,
             display_name: c.display_name,
           })),
-          credentials_page_url: getCredentialsPageUrl(integration_id),
         };
       } catch (err) {
         return {
           connections: [],
-          credentials_page_url: getCredentialsPageUrl(integration_id),
           error: `Failed to list connections: ${err instanceof Error ? err.message : String(err)}`,
         };
       }

packages/core/src/cli/mcp/tools/listConnections.ts

@@ -1,7 +1,7 @@
 import type { ApiFactory } from "@tigerdata/mcp-boilerplate";
 import { z } from "zod";
 import type { ServerContext } from "../types.js";
-import { createProvider } from "../lib/resolve-credentials.js";
+import { getProvider } from "../../../connections/manager.js";
 
 const inputSchema = {} as const;
 
@@ -36,8 +36,7 @@ export const listIntegrationsFactory: ApiFactory<
     },
     fn: async (): Promise<OutputSchema> => {
       try {
-        const provider = await createProvider();
-        const integrations = await provider.listIntegrations();
+        const integrations = await getProvider().listIntegrations();
         return { integrations };
       } catch (err) {
         return {

packages/core/src/cli/mcp/tools/listIntegrations.ts

@@ -7,6 +7,17 @@ export {
   deleteConnectionByConnectionId,
 } from "./resolver.js";
 export type { ConnectionMapping } from "./resolver.js";
+export {
+  configureConnectionManager,
+  onConnectionChange,
+  assignConnection,
+  unassignConnection,
+  unassignConnectionById,
+  listConnectionMappings,
+  getProvider,
+  resolveCredentials,
+  getAddConnectionUrl,
+} from "./manager.js";
 export { initNango, getNango, fetchCredentials } from "./nango-client.js";
 export type { IntegrationProvider } from "./integration-provider.js";
 export { createIntegrationProvider } from "./integration-provider.js";