feat: built-in MCP server for AI tool integration (#825)

* feat: add MCPSettings model and AppSettings integration

* feat: add MCP message types and JSON-RPC protocol types

* refactor: extract QueryClassifier from MainContentCoordinator for MCP reuse

* feat: add HTTP/1.1 request parser for MCP server

* feat: add MCPSession for per-client MCP state tracking

* feat: add MCPToolHandler and MCPResourceHandler

* feat: add MCP settings UI and AppDelegate integration

* feat: add MCPServer, MCPRouter, MCPConnectionBridge, and MCPAuthGuard

* docs: add MCP server to CHANGELOG

* fix: wire MCP tool handlers, add localization and documentation

* fix: number formatting without grouping separators and friendlier port-in-use error

* fix: crash in MCP settings didSet from UInt16 trap and @observable data race

* fix: validate port range on load and use UInt16(clamping:) in AppDelegate

* fix: address all code review findings for MCP server

* feat: add MCP connected clients list and menu status item

* fix: port change race condition — only restart on enabled/port change, await listener release

* fix: final review — stop() race, cancellation tracking, xlsx removal, stale callback guard

* feat: redesign MCP client configuration with per-tool setup instructions

* fix: handle OAuth discovery probes from Claude Code and use --transport http

* refactor: MCP server spec compliance — Origin validation, session HTTP codes, init gate, SSE IDs

* docs: update MCP docs transport type, add MCP and Terminal to landing page features

Author: datlechin

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- MCP server: built-in Model Context Protocol server lets AI tools (Claude Desktop, Claude Code, Cursor) browse schemas, run queries, and export data through TablePro's connections
+- MCP server: connected clients list in Settings and status menu item showing server state
 - Import connections from TablePlus, Sequel Ace, and DBeaver with one-click migration
 - Embedded database CLI terminal (View > Open Terminal or Ctrl+Cmd+`) auto-launches mysql, psql, redis-cli, etc. for the active connection
 - Structure tab: modify existing tables (add, modify, drop columns, indexes, foreign keys, primary keys)

TablePro/AppDelegate.swift

@@ -108,6 +108,12 @@ class AppDelegate: NSObject, NSApplicationDelegate {
         SyncCoordinator.shared.start()
         LinkedFolderWatcher.shared.start()
 
+        if AppSettingsManager.shared.mcp.enabled {
+            Task {
+                await MCPServerManager.shared.start(port: UInt16(clamping: AppSettingsManager.shared.mcp.port))
+            }
+        }
+
         Task.detached(priority: .background) {
             _ = QueryHistoryStorage.shared
         }
@@ -205,6 +211,9 @@ class AppDelegate: NSObject, NSApplicationDelegate {
     }
 
     func applicationWillTerminate(_ notification: Notification) {
+        Task {
+            await MCPServerManager.shared.stop()
+        }
         LinkedFolderWatcher.shared.stop()
         SSHTunnelManager.shared.terminateAllProcessesSync()
     }

TablePro/Core/MCP/MCPAuthGuard.swift

@@ -0,0 +1,167 @@
+//
+//  MCPAuthGuard.swift
+//  TablePro
+//
+//  Enforces AIConnectionPolicy and SafeModeLevel for MCP requests.
+//
+
+import AppKit
+import Foundation
+import os
+
+actor MCPAuthGuard {
+    private static let logger = Logger(subsystem: "com.TablePro", category: "MCPAuthGuard")
+
+    /// Per-session approved connections (for askEachTime policy)
+    private var sessionApprovals: [String: Set<UUID>] = [:]
+
+    // MARK: - Connection Access Check
+
+    func checkConnectionAccess(connectionId: UUID, sessionId: String) async throws {
+        let (policy, connectionName, databaseType) = await MainActor.run {
+            let conns = ConnectionStorage.shared.loadConnections()
+            guard let conn = conns.first(where: { $0.id == connectionId }) else {
+                return (AIConnectionPolicy.never, "", "")
+            }
+            let effective = conn.aiPolicy ?? AppSettingsManager.shared.ai.defaultConnectionPolicy
+            return (effective, conn.name, conn.type.rawValue)
+        }
+
+        switch policy {
+        case .alwaysAllow:
+            return
+
+        case .never:
+            throw MCPError.forbidden(
+                String(localized: "AI access is disabled for this connection")
+            )
+
+        case .askEachTime:
+            if let approved = sessionApprovals[sessionId], approved.contains(connectionId) {
+                return
+            }
+
+            let userApproved = try await promptUserApproval(
+                connectionName: connectionName,
+                databaseType: databaseType
+            )
+
+            if userApproved {
+                sessionApprovals[sessionId, default: []].insert(connectionId)
+            } else {
+                throw MCPError.forbidden(
+                    String(localized: "User denied MCP access to this connection")
+                )
+            }
+        }
+    }
+
+    // MARK: - Query Permission Check
+
+    func checkQueryPermission(
+        sql: String,
+        connectionId: UUID,
+        databaseType: DatabaseType,
+        safeModeLevel: SafeModeLevel
+    ) async throws {
+        let isWrite = QueryClassifier.isWriteQuery(sql, databaseType: databaseType)
+
+        // SafeModeGuard.checkPermission is @MainActor async; Swift hops automatically
+        let permission = await SafeModeGuard.checkPermission(
+            level: safeModeLevel,
+            isWriteOperation: isWrite,
+            sql: sql,
+            operationDescription: String(localized: "MCP query execution"),
+            window: nil,
+            databaseType: databaseType
+        )
+
+        if case .blocked(let reason) = permission {
+            throw MCPError.forbidden(reason)
+        }
+    }
+
+    // MARK: - Query Logging
+
+    func logQuery(
+        sql: String,
+        connectionId: UUID,
+        databaseName: String,
+        executionTime: TimeInterval,
+        rowCount: Int,
+        wasSuccessful: Bool,
+        errorMessage: String?
+    ) async {
+        let shouldLog = await MainActor.run {
+            AppSettingsManager.shared.mcp.logQueriesInHistory
+        }
+        guard shouldLog else { return }
+
+        let entry = QueryHistoryEntry(
+            query: sql,
+            connectionId: connectionId,
+            databaseName: databaseName,
+            executionTime: executionTime,
+            rowCount: rowCount,
+            wasSuccessful: wasSuccessful,
+            errorMessage: errorMessage
+        )
+
+        _ = await QueryHistoryStorage.shared.addHistory(entry)
+    }
+
+    // MARK: - User Approval (askEachTime)
+
+    private func promptUserApproval(connectionName: String, databaseType: String) async throws -> Bool {
+        // Use a task group so the actor suspends (freeing it for other requests)
+        // while the approval dialog is shown on the main thread.
+        // Race the dialog against a 30-second timeout.
+        let approvalTask = Task { @MainActor in
+            NSApp.requestUserAttention(.criticalRequest)
+            NSApp.activate(ignoringOtherApps: true)
+            return await AlertHelper.confirmDestructive(
+                title: String(localized: "MCP Access Request"),
+                message: String(
+                    format: String(localized: "An MCP client wants to access '%@' (%@). Allow?"),
+                    connectionName,
+                    databaseType
+                ),
+                confirmButton: String(localized: "Allow"),
+                cancelButton: String(localized: "Deny"),
+                window: nil
+            )
+        }
+
+        let approved = try await withThrowingTaskGroup(of: Bool.self) { group in
+            group.addTask {
+                await approvalTask.value
+            }
+            group.addTask {
+                try await Task.sleep(for: .seconds(30))
+                approvalTask.cancel()
+                throw MCPError.timeout(
+                    String(localized: "User approval timed out after 30 seconds")
+                )
+            }
+            guard let result = try await group.next() else {
+                throw MCPError.internalError("No result from approval prompt")
+            }
+            approvalTask.cancel()
+            group.cancelAll()
+            return result
+        }
+
+        if approved {
+            return true
+        }
+        throw MCPError.forbidden(
+            String(localized: "User denied MCP access to this connection")
+        )
+    }
+
+    // MARK: - Session Cleanup
+
+    func clearSession(_ sessionId: String) {
+        sessionApprovals.removeValue(forKey: sessionId)
+    }
+}