docs(mcp): restore TSDoc that documented intent on exported types/methods

Earlier comment-trim pass went too far on a few exports — restored
the TSDoc that explained non-obvious "why" decisions:

- SimMcpOauthProviderInit.preregistered: when set, the SDK skips DCR.
- McpServerConfig.userId: required for OAuth; selects which user's
  stored tokens to use.
- McpOauthAuthorizationRequiredError: benign pending state vs failure.
- McpToolsChangedCallback / McpClientOptions: notification semantics,
  DNS-rebinding pinning rationale, OAuth provider contract.
- StoredMcpToolReference / StoredMcpTool: minimal vs extended use.
- McpClient.connect: documents listChanged handler registration.
- McpService.executeTool: documents session-error retry behavior.

Pure-restatement comments ("Disconnect from MCP server") stay trimmed.

Author: waleedlatif1

apps/sim/lib/mcp/client.ts

@@ -80,6 +80,11 @@ export class McpClient {
     )
   }
 
+  /**
+   * Initialize connection to MCP server.
+   * If an `onToolsChanged` callback was provided, registers a notification handler
+   * for `notifications/tools/list_changed` after connecting.
+   */
   async connect(): Promise<void> {
     logger.info(`Connecting to MCP server: ${this.config.name} (${this.config.transport})`)
 

apps/sim/lib/mcp/oauth/provider.ts

@@ -41,7 +41,10 @@ export interface PreregisteredClient {
 interface SimMcpOauthProviderInit {
   row: McpOauthRow
   scope?: string
-  /** When set, the SDK skips Dynamic Client Registration and uses these credentials directly. */
+  /**
+   * Optional user-supplied client credentials. When provided, the SDK skips
+   * Dynamic Client Registration and uses these for the auth/token exchange.
+   */
   preregistered?: PreregisteredClient
 }
 

apps/sim/lib/mcp/service.ts

@@ -242,6 +242,10 @@ class McpService {
     })
   }
 
+  /**
+   * Execute a tool on a specific server with retry logic for session errors.
+   * Retries once on session-related errors (400, 404, session ID issues).
+   */
   async executeTool(
     userId: string,
     serverId: string,

apps/sim/lib/mcp/types.ts

@@ -17,7 +17,10 @@ export interface McpServerConfig {
   transport: McpTransport
   url?: string
   authType?: McpAuthType
-  /** Required for `authType === 'oauth'` — selects whose stored tokens to use. */
+  /**
+   * Required when `authType === 'oauth'` — identifies whose stored tokens
+   * to use when establishing the connection. Omit for header / none auth.
+   */
   userId?: string
   workspaceId?: string
   headers?: Record<string, string>
@@ -129,7 +132,12 @@ export class McpConnectionError extends McpError {
   }
 }
 
-/** Benign "needs re-auth" state — distinct from a connection failure. */
+/**
+ * Thrown when an OAuth-protected MCP server is reachable but the current
+ * user has not yet authorized Sim. This is a benign "pending" state, not a
+ * connection failure — callers should surface a re-auth prompt rather than
+ * marking the server as errored.
+ */
 export class McpOauthAuthorizationRequiredError extends McpError {
   constructor(
     public readonly serverId: string,
@@ -153,15 +161,32 @@ export interface McpServerSummary {
   error?: string
 }
 
+/**
+ * Callback invoked when an MCP server sends a `notifications/tools/list_changed` notification.
+ */
 export type McpToolsChangedCallback = (serverId: string) => void
 
+/**
+ * Options for creating an McpClient with notification support.
+ */
 export interface McpClientOptions {
   config: McpServerConfig
   securityPolicy?: McpSecurityPolicy
   onToolsChanged?: McpToolsChangedCallback
-  /** Pre-resolved IP pinned via undici to prevent DNS-rebinding between URL validation and connection. */
+  /**
+   * Pre-resolved IP address to pin all transport HTTP connections to. When
+   * set, the SDK transport uses a custom fetch backed by an undici Agent with
+   * a fixed DNS lookup, preventing DNS-rebinding (TOCTOU) attacks between
+   * URL validation and connection. Should be supplied by callers that have
+   * just validated the URL via `validateMcpServerSsrf`.
+   */
   resolvedIP?: string
-  /** SDK provider for OAuth token discovery, refresh, and 401 recovery. Required for `authType === 'oauth'`. */
+  /**
+   * SDK-compatible OAuth client provider. When provided, the underlying
+   * StreamableHTTPClientTransport delegates token discovery, refresh, and
+   * 401 recovery to it. Should be supplied for `authType === 'oauth'`
+   * server configs.
+   */
   authProvider?: import('@modelcontextprotocol/sdk/client/auth.js').OAuthClientProvider
 }
 
@@ -200,14 +225,21 @@ export interface McpToolDiscoveryResponse {
   byServer: Record<string, number>
 }
 
-/** Minimal MCP tool reference stored in workflow blocks for schema validation. */
+/**
+ * MCP tool reference stored in workflow blocks (for validation).
+ * Minimal version used for comparing against discovered tools.
+ */
 export interface StoredMcpToolReference {
   serverId: string
   serverUrl?: string
   toolName: string
   schema?: McpToolSchema
 }
 
+/**
+ * Full stored MCP tool with workflow context (for API responses).
+ * Extended version that includes which workflow the tool is used in.
+ */
 export interface StoredMcpTool extends StoredMcpToolReference {
   workflowId: string
   workflowName: string