Add startup warnings for missing secrets (#712)

Add startup warnings for missing tool secrets to provide faster feedback
on configuration issues.

---
Linear Issue:
[TOO-198](https://linear.app/arcadedev/issue/TOO-198/add-startup-warnings-for-missing-tool-secrets)

<a
href="https://cursor.com/background-agent?bcId=bc-203d1b6a-80a7-4933-b3ff-b3a9220b5809"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-cursor-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-cursor-light.svg"><img alt="Open in
Cursor"
src="https://cursor.com/open-in-cursor.svg"></picture></a>&nbsp;<a
href="https://cursor.com/agents?id=bc-203d1b6a-80a7-4933-b3ff-b3a9220b5809"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-web-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-web-light.svg"><img alt="Open in Web"
src="https://cursor.com/open-in-web.svg"></picture></a>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Eric Gustin <eric@arcade.dev>

Author: 4 people

libs/arcade-mcp-server/arcade_mcp_server/__main__.py

@@ -20,7 +20,6 @@
 """
 
 import asyncio
-import logging
 import os
 import sys
 from pathlib import Path
@@ -32,23 +31,11 @@
 from dotenv import load_dotenv
 from loguru import logger
 
+from arcade_mcp_server.logging_utils import intercept_standard_logging
 from arcade_mcp_server.server import MCPServer
 from arcade_mcp_server.settings import MCPSettings
 
 
-# Logging setup with Loguru
-class LoguruInterceptHandler(logging.Handler):
-    """Intercept standard logging and route to Loguru."""
-
-    def emit(self, record: logging.LogRecord) -> None:
-        try:
-            level = logger.level(record.levelname).name
-        except ValueError:
-            level = str(record.levelno)
-
-        logger.opt(exception=record.exc_info).log(level, record.getMessage())
-
-
 def setup_logging(level: str = "INFO", stdio_mode: bool = False) -> None:
     """Configure logging with Loguru."""
     # Remove existing handlers
@@ -74,7 +61,7 @@ def setup_logging(level: str = "INFO", stdio_mode: bool = False) -> None:
     )
 
     # Intercept standard logging
-    logging.basicConfig(handlers=[LoguruInterceptHandler()], level=0, force=True)
+    intercept_standard_logging()
 
 
 def initialize_tool_catalog(

libs/arcade-mcp-server/arcade_mcp_server/logging_utils.py

@@ -0,0 +1,30 @@
+"""Shared logging utilities for MCP server."""
+
+import logging
+
+from loguru import logger
+
+
+class LoguruInterceptHandler(logging.Handler):
+    """Intercept standard logging and route to Loguru.
+
+    This handler bridges the standard Python logging module with Loguru,
+    ensuring all logs (from both systems) use the same formatting.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = str(record.levelno)
+
+        logger.opt(exception=record.exc_info).log(level, record.getMessage())
+
+
+def intercept_standard_logging() -> None:
+    """Configure standard logging to route through Loguru.
+
+    This should be called after Loguru is configured to ensure all
+    standard logging calls are intercepted and formatted consistently.
+    """
+    logging.basicConfig(handlers=[LoguruInterceptHandler()], level=0, force=True)

libs/arcade-mcp-server/arcade_mcp_server/mcp_app.py

@@ -24,6 +24,7 @@
 from watchfiles import watch
 
 from arcade_mcp_server.exceptions import ServerError
+from arcade_mcp_server.logging_utils import intercept_standard_logging
 from arcade_mcp_server.server import MCPServer
 from arcade_mcp_server.settings import MCPSettings, ServerSettings
 from arcade_mcp_server.types import Prompt, PromptMessage, Resource
@@ -217,6 +218,9 @@ def _setup_logging(self, stdio_mode: bool = False) -> None:
             diagnose=(self.log_level == "DEBUG"),
         )
 
+        # Intercept standard logging and route through Loguru
+        intercept_standard_logging()
+
     def add_tool(
         self,
         func: Callable[P, T],

libs/arcade-mcp-server/arcade_mcp_server/server.py

@@ -307,6 +307,10 @@ async def _start(self) -> None:
             await self._tool_manager.load_from_catalog(self._initial_catalog)
         except Exception:
             logger.exception("Failed to load tools from initial catalog")
+
+        # Check for missing secrets and log warnings (only when worker routes are disabled)
+        await self._check_and_warn_missing_secrets()
+
         await self._resource_manager.start()
         await self._prompt_manager.start()
         await self.lifespan_manager.startup()
@@ -654,6 +658,40 @@ async def _create_tool_context(
 
         return tool_context
 
+    async def _check_and_warn_missing_secrets(self) -> None:
+        """
+        Check for missing tool secrets and log warnings.
+
+        This method is called during server startup to provide early feedback
+        about missing configuration. It only runs when worker routes are disabled
+        (when ARCADE_WORKER_SECRET is not set), as worker routes receive secrets
+        with tool execution information.
+        """
+        # Skip validation if worker routes are enabled
+        if self.settings.arcade.server_secret:
+            logger.debug("Skipping secret validation check - worker routes are enabled")
+            return
+
+        # Get all available secrets from settings and environment
+        available_secrets = set(self.settings.tool_secrets().keys()) | set(os.environ.keys())
+
+        # Check each tool for missing secrets
+        managed_tools = await self._tool_manager.registry.list()
+        for managed_tool in managed_tools:
+            tool = managed_tool["materialized"]
+            if tool.definition.requirements and tool.definition.requirements.secrets:
+                missing_secrets = []
+                for secret_requirement in tool.definition.requirements.secrets:
+                    if secret_requirement.key not in available_secrets:
+                        missing_secrets.append(secret_requirement.key)
+
+                if missing_secrets:
+                    secret_list = "', '".join(missing_secrets)
+                    tool_name = tool.definition.name
+                    logger.warning(
+                        f"Tool '{tool_name}' declares secret(s) '{secret_list}' which is/are not set. It will return an error if called."
+                    )
+
     async def _handle_call_tool(
         self,
         message: CallToolRequest,

libs/arcade-mcp-server/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arcade-mcp-server"
-version = "1.10.3"
+version = "1.11.0"
 description = "Model Context Protocol (MCP) server framework for Arcade.dev"
 readme = "README.md"
 authors = [{ name = "Arcade.dev" }]