solace-agent-mesh 1.11.2__py3-none-any.whl → 1.12.0__py3-none-any.whl

solace_agent_mesh/agent/adk/setup.py

@@ -15,6 +15,7 @@ from google.adk.models.llm_request import LlmRequest
 from google.adk.models.llm_response import LlmResponse
 from google.adk.runners import Runner
 from google.adk.tools import BaseTool, ToolContext
+from google.adk.tools.mcp_tool import MCPTool
 from google.adk.tools.mcp_tool.mcp_session_manager import (
     SseServerParams,
     StdioConnectionParams,
@@ -625,14 +626,30 @@ async def _load_mcp_tool(component: "SamAgentComponent", tool_config: Dict) -> T
     else:
         raise ValueError(f"Unsupported MCP connection type: {connection_type}")
 
-    tool_filter_list = (
-        [tool_config_model.tool_name] if tool_config_model.tool_name else None
-    )
-    if tool_filter_list:
+    # Determine tool filter based on configuration
+    # tool_name, allow_list, and deny_list are mutually exclusive (validated by pydantic)
+    tool_filter = None
+    filter_description = "none (all tools)"
+
+    if tool_config_model.tool_name:
+        # Backward compatible: single tool name becomes a list
+        tool_filter = [tool_config_model.tool_name]
+        filter_description = f"tool_name='{tool_config_model.tool_name}'"
+    elif tool_config_model.allow_list:
+        # Allow list: pass directly as list of tool names
+        tool_filter = tool_config_model.allow_list
+        filter_description = f"allow_list={tool_config_model.allow_list}"
+    elif tool_config_model.deny_list:
+        # Deny list: create a ToolPredicate that excludes these tools
+        deny_set = set(tool_config_model.deny_list)
+        tool_filter = lambda tool, ctx=None, _deny=deny_set: tool.name not in _deny
+        filter_description = f"deny_list={tool_config_model.deny_list}"
+
+    if tool_filter:
         log.info(
-            "%s MCP tool config specifies tool_name: '%s'. Applying as tool_filter.",
+            "%s MCP tool config specifies filter: %s",
             component.log_identifier,
-            tool_config_model.tool_name,
+            filter_description,
         )
 
     additional_params = {}
@@ -647,7 +664,7 @@ async def _load_mcp_tool(component: "SamAgentComponent", tool_config: Dict) -> T
                 tool_type="mcp",
                 tool_config=tool_config,
                 connection_params=connection_params,
-                tool_filter=tool_filter_list,
+                tool_filter=tool_filter,
             )
         except Exception as e:
             log.error(
@@ -664,7 +681,8 @@ async def _load_mcp_tool(component: "SamAgentComponent", tool_config: Dict) -> T
     # Create the EmbedResolvingMCPToolset with base parameters
     toolset_params = {
         "connection_params": connection_params,
-        "tool_filter": tool_filter_list,
+        "tool_filter": tool_filter,
+        "tool_name_prefix": tool_config_model.tool_name_prefix,
         "tool_config": tool_config,
     }
 
@@ -677,7 +695,7 @@ async def _load_mcp_tool(component: "SamAgentComponent", tool_config: Dict) -> T
     log.info(
         "%s Initialized MCPToolset (filter: %s) for server: %s",
         component.log_identifier,
-        (tool_filter_list if tool_filter_list else "none (all tools)"),
+        filter_description,
         connection_params,
     )
 
@@ -893,19 +911,7 @@ async def load_adk_tools(
                 for tool in new_tools:
                     if isinstance(tool, EmbedResolvingMCPToolset):
                         # Special handling for MCPToolset which can load multiple tools
-                        try:
-                            mcp_tools = await tool.get_tools()
-                            for mcp_tool in mcp_tools:
-                                _check_and_register_tool_name(
-                                    mcp_tool.name, "mcp", loaded_tool_names
-                                )
-                        except Exception as e:
-                            log.error(
-                                "%s Failed to discover tools from MCP server for name registration: %s",
-                                component.log_identifier,
-                                str(e),
-                            )
-                            raise
+                        await _check_and_register_tool_name_mcp(component, loaded_tool_names, tool)
                     else:
                         tool_name = getattr(
                             tool, "name", getattr(tool, "__name__", None)
@@ -949,6 +955,25 @@ async def load_adk_tools(
     return loaded_tools, enabled_builtin_tools, cleanup_hooks
 
 
+async def _check_and_register_tool_name_mcp(component, loaded_tool_names: set[str], tool: EmbedResolvingMCPToolset):
+    try:
+        mcp_tools: list[MCPTool] = await tool.get_tools()
+        for mcp_tool in mcp_tools:
+            toolname = mcp_tool.name
+            if tool.tool_name_prefix != None:
+                toolname = f"{tool.tool_name_prefix}_{toolname}"
+            _check_and_register_tool_name(
+                toolname, "mcp", loaded_tool_names
+            )
+    except Exception as e:
+        log.error(
+            "%s Failed to discover tools from MCP server for name registration: %s",
+            component.log_identifier,
+            str(e),
+        )
+        raise
+
+
 def initialize_adk_agent(
     component,
     loaded_explicit_tools: List[Union[BaseTool, Callable]],
@@ -1221,7 +1246,17 @@ def initialize_adk_agent(
         # The callbacks are executed in the order they are added to this list.
         callbacks_in_order_for_after_model = []
 
-        # 1. Fenced Artifact Block Processing (must run before auto-continue)
+        # 1. Pre-register long-running tools (must run BEFORE tool execution)
+        preregister_cb = functools.partial(
+            adk_callbacks.preregister_long_running_tools_callback, host_component=component
+        )
+        callbacks_in_order_for_after_model.append(preregister_cb)
+        log.debug(
+            "%s Added preregister_long_running_tools_callback to after_model chain.",
+            component.log_identifier,
+        )
+
+        # 2. Fenced Artifact Block Processing (must run before auto-continue)
         artifact_block_cb = functools.partial(
             adk_callbacks.process_artifact_blocks_callback, host_component=component
         )
@@ -1231,7 +1266,7 @@ def initialize_adk_agent(
             component.log_identifier,
         )
 
-        # 2. Auto-Continuation (may short-circuit the chain)
+        # 3. Auto-Continuation (may short-circuit the chain)
         auto_continue_cb = functools.partial(
             adk_callbacks.auto_continue_on_max_tokens_callback, host_component=component
         )
@@ -1241,13 +1276,13 @@ def initialize_adk_agent(
             component.log_identifier,
         )
 
-        # 3. Solace LLM Response Logging
+        # 4. Solace LLM Response Logging
         solace_llm_response_cb = functools.partial(
             adk_callbacks.solace_llm_response_callback, host_component=component
         )
         callbacks_in_order_for_after_model.append(solace_llm_response_cb)
 
-        # 4. Chunk Logging
+        # 5. Chunk Logging
         log_chunk_cb = functools.partial(
             adk_callbacks.log_streaming_chunk_callback, host_component=component
         )

solace_agent_mesh/agent/protocol/event_handlers.py

@@ -8,6 +8,8 @@ import json
 import logging
 from typing import TYPE_CHECKING, Any, Dict
 
+from litellm.exceptions import BadRequestError
+
 from a2a.types import (
     A2ARequest,
     AgentCapabilities,
@@ -31,6 +33,7 @@ from ...agent.adk.callbacks import _publish_data_part_status_update
 from ...agent.adk.runner import TaskCancelledError, run_adk_async_task_thread_wrapper
 from ...agent.utils.artifact_helpers import generate_artifact_metadata_summary
 from ...common import a2a
+from ...common.error_handlers import get_error_message
 from ...common.utils.embeds.constants import (
     EMBED_DELIMITER_OPEN,
     EMBED_DELIMITER_CLOSE,
@@ -975,6 +978,51 @@ async def handle_a2a_request(component, message: SolaceMessage):
         component.handle_error(e, Event(EventType.MESSAGE, message))
         return None
 
+    except BadRequestError as e:
+        log.error(
+            "%s Bad Request error handling A2A request: %s", component.log_identifier, e
+        )
+        
+        # Use centralized error handler
+        error_message, is_context_limit = get_error_message(e)
+        
+        if is_context_limit:
+            log.error(
+                "%s Context limit exceeded for task %s",
+                component.log_identifier,
+                logical_task_id,
+            )
+        
+        error_response = a2a.create_invalid_request_error_response(
+            message=error_message,
+            request_id=jsonrpc_request_id,
+            data={"taskId": logical_task_id},
+        )
+        target_topic = reply_topic_from_peer or (
+            get_client_response_topic(namespace, client_id) if client_id else None
+        )
+        if target_topic:
+            component.publish_a2a_message(
+                error_response.model_dump(exclude_none=True),
+                target_topic,
+            )
+
+        try:
+            message.call_negative_acknowledgements()
+            log.warning(
+                "%s NACKed original A2A request due to bad request error.",
+                component.log_identifier,
+            )
+        except Exception as nack_e:
+            log.error(
+                "%s Failed to NACK message after bad request error: %s",
+                component.log_identifier,
+                nack_e,
+            )
+
+        component.handle_error(e, Event(EventType.MESSAGE, message))
+        return None
+
     except OperationalError as e:
         log.error(
             "%s Database error while processing A2A request: %s",

solace_agent_mesh/agent/proxies/a2a/component.py

@@ -28,6 +28,7 @@ from a2a.types import (
     Artifact,
     CancelTaskRequest,
     DataPart,
+    InternalError,
     Message,
     SendMessageRequest,
     SendStreamingMessageRequest,
@@ -322,6 +323,8 @@ class A2AProxyComponent(BaseProxyComponent):
 
         # Step 3: Normal request flow for all other auth types
         # (static_bearer, static_apikey, oauth2_client_credentials, or authorized oauth2_authorization_code)
+        received_final_task = False
+
         while auth_retry_count <= max_auth_retries:
             try:
                 # Get or create A2AClient
@@ -382,6 +385,10 @@ class A2AProxyComponent(BaseProxyComponent):
                             await self._process_downstream_response(
                                 raw_event, task_context, client, agent_name
                             )
+                            # Check if this is a final task
+                            if isinstance(raw_event, Task) and raw_event.status:
+                                if raw_event.status.state in [TaskState.completed, TaskState.failed, TaskState.canceled]:
+                                    received_final_task = True
                     else:
                         # Non-streaming: use normal client method (works fine)
                         log.debug(
@@ -394,6 +401,12 @@ class A2AProxyComponent(BaseProxyComponent):
                             await self._process_downstream_response(
                                 event, task_context, client, agent_name
                             )
+                            # Check if this is a final task (event is tuple of (Task, Optional[UpdateEvent]))
+                            if isinstance(event, tuple) and len(event) > 0:
+                                task = event[0]
+                                if isinstance(task, Task) and task.status:
+                                    if task.status.state in [TaskState.completed, TaskState.failed, TaskState.canceled]:
+                                        received_final_task = True
                 elif isinstance(request, CancelTaskRequest):
                     # Forward cancel request to downstream agent using the downstream task ID
                     # The request.params.id contains SAM's task ID, but we need to send
@@ -555,6 +568,20 @@ class A2AProxyComponent(BaseProxyComponent):
                 # and publish an error response.
                 raise
 
+        # After retry loop completes - check if we received a final task
+        # This detects cases where the stream closes without error but also without final response
+        if not received_final_task and isinstance(request, (SendStreamingMessageRequest, SendMessageRequest)):
+            from ....common.a2a import create_error_response
+
+            error_msg = f"Remote agent '{agent_name}' disconnected without completing the task. Agent may have crashed."
+            log.error("%s %s", log_identifier, error_msg)
+
+            error = InternalError(message=error_msg, data={"agent_name": agent_name})
+            reply_topic = task_context.a2a_context.get("reply_to_topic")
+            if reply_topic:
+                response = create_error_response(error=error, request_id=task_context.a2a_context.get("jsonrpc_request_id"))
+                self._publish_a2a_message(response.model_dump(exclude_none=True), reply_topic)
+
     async def _handle_auth_error(
         self, agent_name: str, task_context: ProxyTaskContext
     ) -> bool:

solace_agent_mesh/agent/sac/component.py

@@ -13,6 +13,10 @@ import threading
 import time
 from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Union
 
+from litellm.exceptions import BadRequestError
+
+from ...common.error_handlers import get_error_message
+
 from a2a.types import (
     AgentCard,
     MessageSendParams,
@@ -74,7 +78,8 @@ from ...common.constants import (
     HEALTH_CHECK_INTERVAL_SECONDS,
     HEALTH_CHECK_TTL_SECONDS,
 )
-from ...common.data_parts import AgentProgressUpdateData
+from ...common.a2a.types import ArtifactInfo
+from ...common.data_parts import AgentProgressUpdateData, ArtifactSavedData
 from ...common.middleware.registry import MiddlewareRegistry
 from ...common.sac.sam_component_base import SamComponentBase
 from ...common.utils.rbac_utils import validate_agent_access
@@ -1526,6 +1531,68 @@ class SamAgentComponent(SamComponentBase):
             )
             return False
 
+    async def notify_artifact_saved(
+        self,
+        artifact_info: ArtifactInfo,
+        a2a_context: Dict[str, Any],
+        function_call_id: Optional[str] = None,
+    ) -> None:
+        """
+        Publishes an artifact saved notification signal.
+
+        This is a separate event from ArtifactCreationProgressData and does not
+        follow the start->updates->end protocol. It's a single notification that
+        an artifact has been successfully saved to storage.
+
+        Args:
+            artifact_info: Information about the saved artifact
+            a2a_context: The A2A context dictionary for the current task
+            function_call_id: Optional function call ID if artifact was created by a tool
+        """
+        log_identifier = f"{self.log_identifier}[ArtifactSaved:{artifact_info.filename}]"
+
+        try:
+            # Create artifact saved signal
+            artifact_signal = ArtifactSavedData(
+                type="artifact_saved",
+                filename=artifact_info.filename,
+                version=artifact_info.version,
+                mime_type=artifact_info.mime_type or "application/octet-stream",
+                size_bytes=artifact_info.size,
+                description=artifact_info.description,
+                function_call_id=function_call_id,
+            )
+
+            # Create and publish status update event
+            logical_task_id = a2a_context.get("logical_task_id")
+            context_id = a2a_context.get("contextId")
+
+            status_update_event = a2a.create_data_signal_event(
+                task_id=logical_task_id,
+                context_id=context_id,
+                signal_data=artifact_signal,
+                agent_name=self.agent_name,
+            )
+
+            await self._publish_status_update_with_buffer_flush(
+                status_update_event,
+                a2a_context,
+                skip_buffer_flush=False,
+            )
+
+            log.debug(
+                "%s Published artifact saved notification for '%s' v%s.",
+                log_identifier,
+                artifact_info.filename,
+                artifact_info.version,
+            )
+        except Exception as e:
+            log.error(
+                "%s Failed to publish artifact saved notification: %s",
+                log_identifier,
+                e,
+            )
+
     async def _publish_status_update_with_buffer_flush(
         self,
         status_update_event: TaskStatusUpdateEvent,
@@ -2646,10 +2713,25 @@ class SamAgentComponent(SamComponentBase):
             peer_reply_topic = a2a_context.get("replyToTopic")
             namespace = self.get_config("namespace")
 
+            # Detect context limit errors and provide user-friendly message
+            error_message = "An unexpected error occurred during tool execution. Please try your request again. If the problem persists, contact an administrator."
+            
+            if isinstance(exception, BadRequestError):
+                # Use centralized error handler
+                error_message, is_context_limit = get_error_message(exception)
+                
+                if is_context_limit:
+                    log.error(
+                        "%s Context limit exceeded for task %s. Error: %s",
+                        self.log_identifier,
+                        logical_task_id,
+                        exception,
+                    )
+
             failed_status = a2a.create_task_status(
                 state=TaskState.failed,
                 message=a2a.create_agent_text_message(
-                    text="An unexpected error occurred during tool execution. Please try your request again. If the problem persists, contact an administrator."
+                    text=error_message
                 ),
             )
 

solace_agent_mesh/agent/tools/builtin_artifact_tools.py

@@ -175,6 +175,7 @@ async def _internal_create_artifact(
             timestamp=timestamp_for_artifact,
             schema_max_keys=max_keys_to_use,
             tool_context=tool_context,
+            suppress_visualization_signal=True,  # Fenced blocks handle their own visualization signals
         )
         log.info(
             "%s Result from save_artifact_with_metadata: %s", log_identifier, result
@@ -1740,18 +1741,20 @@ tool_registry.register(extract_content_from_artifact_tool_def)
 async def delete_artifact(
     filename: str,
     version: Optional[int] = None,
+    confirm_delete: bool = False,
     tool_context: ToolContext = None,
 ) -> Dict[str, Any]:
     """
-    Deletes a specific version of an artifact, or all versions if no version is specified.
+    Deletes all versions of an artifact. Version-specific deletion is not currently supported.
 
     Args:
         filename: The name of the artifact to delete.
-        version: The specific version number to delete. If not provided, all versions will be deleted.
+        version: Reserved for future use. Currently not supported - returns error if specified.
+        confirm_delete: Must be set to True to confirm deletion. If False, returns confirmation prompt.
         tool_context: The context provided by the ADK framework.
 
     Returns:
-        A dictionary indicating the result of the deletion.
+        A dictionary indicating the result of the deletion or requesting confirmation.
     """
     if not tool_context:
         return {
@@ -1760,9 +1763,7 @@ async def delete_artifact(
             "message": "ToolContext is missing, cannot delete artifact.",
         }
 
-    log_identifier = (
-        f"[BuiltinArtifactTool:delete_artifact:{filename}:{version or 'all'}]"
-    )
+    log_identifier = f"[BuiltinArtifactTool:delete_artifact:{filename}]"
     log.debug("%s Processing request.", log_identifier)
 
     try:
@@ -1780,14 +1781,32 @@ async def delete_artifact(
                 "ArtifactService does not support deleting artifacts."
             )
 
+        # Error if version-specific deletion requested (not currently supported)
         if version is not None:
-            log.warning(
-                "%s Deleting a specific version (%s) is not supported by the current artifact service interface. "
-                "All versions of the artifact will be deleted.",
-                log_identifier,
-                version,
-            )
+            return {
+                "status": "error",
+                "filename": filename,
+                "version_requested": version,
+                "message": f"Deleting a specific version ({version}) is not currently supported. Only deletion of ALL versions is supported. To delete all versions, omit 'version' and set confirm_delete=True.",
+            }
+
+        # Get version list for confirmation message
+        versions = await artifact_service.list_versions(
+            app_name=app_name, user_id=user_id, session_id=session_id, filename=filename
+        )
 
+        # Require confirmation before deleting
+        if not confirm_delete:
+            count = len(versions) if versions else "unknown number of"
+            return {
+                "status": "confirmation_required",
+                "filename": filename,
+                "version_count": len(versions) if versions else None,
+                "versions": versions,
+                "message": f"WARNING: This operation is irreversible and will permanently delete artifact '{filename}' and ALL {count} version(s). To proceed, call this tool again with confirm_delete=True.",
+            }
+
+        # Proceed with deletion
         await artifact_service.delete_artifact(
             app_name=app_name,
             user_id=user_id,
@@ -1795,17 +1814,12 @@ async def delete_artifact(
             filename=filename,
         )
 
-        log.info(
-            "%s Successfully deleted artifact '%s' version '%s'.",
-            log_identifier,
-            filename,
-            version or "all",
-        )
+        log.info("%s Successfully deleted artifact '%s'.", log_identifier, filename)
         return {
             "status": "success",
             "filename": filename,
-            "version": version or "all",
-            "message": f"Artifact '{filename}' version '{version or 'all'}' deleted successfully.",
+            "versions_deleted": len(versions) if versions else None,
+            "message": f"Artifact '{filename}' deleted successfully.",
         }
 
     except FileNotFoundError as e:
@@ -1829,7 +1843,7 @@ async def delete_artifact(
 delete_artifact_tool_def = BuiltinTool(
     name="delete_artifact",
     implementation=delete_artifact,
-    description="Deletes a specific version of an artifact, or all versions if no version is specified.",
+    description="Deletes all versions of an artifact. IMPORTANT: Requires explicit confirmation via confirm_delete=True parameter. The first call without confirmation will return details about what will be deleted.",
     category="artifact_management",
     category_name=CATEGORY_NAME,
     category_description=CATEGORY_DESCRIPTION,
@@ -1843,7 +1857,12 @@ delete_artifact_tool_def = BuiltinTool(
             ),
             "version": adk_types.Schema(
                 type=adk_types.Type.INTEGER,
-                description="The specific version number to delete. If not provided, all versions will be deleted.",
+                description="Reserved for future use. Version-specific deletion is not currently supported - will return error if specified.",
+                nullable=True,
+            ),
+            "confirm_delete": adk_types.Schema(
+                type=adk_types.Type.BOOLEAN,
+                description="Must be set to True to actually perform the deletion. If False or omitted, returns a confirmation prompt with details about what will be deleted (including version count).",
                 nullable=True,
             ),
         },

solace_agent_mesh/agent/tools/peer_agent_tool.py

@@ -20,6 +20,7 @@ from ...common.exceptions import MessageSizeExceededError
 
 log = logging.getLogger(__name__)
 
+
 class ArtifactIdentifier(BaseModel):
     """Identifies a specific version of an artifact."""
 
@@ -90,7 +91,10 @@ class PeerAgentTool(BaseTool):
             Enhanced description string with markdown formatting
         """
         # Start with base description - ensure it's clean (no extra whitespace)
-        base_desc = agent_card.description or f"Interact with the {self.target_agent_name} agent."
+        base_desc = (
+            agent_card.description
+            or f"Interact with the {self.target_agent_name} agent."
+        )
         base_desc = " ".join(base_desc.split())  # Normalize whitespace
 
         # Extract skills information
@@ -101,7 +105,7 @@ class PeerAgentTool(BaseTool):
             skill_names = []
             for skill in agent_card.skills[:max_skills_to_show]:
                 # Prefer name, fallback to id
-                skill_name = getattr(skill, 'name', None) or getattr(skill, 'id', None)
+                skill_name = getattr(skill, "name", None) or getattr(skill, "id", None)
                 if skill_name:
                     skill_names.append(skill_name)
 
@@ -113,7 +117,9 @@ class PeerAgentTool(BaseTool):
 
             # Include skill count in the header
             if skill_count > 1:
-                enhanced_desc = f"{base_desc}\n\n**Skills ({skill_count}):** {skills_str}"
+                enhanced_desc = (
+                    f"{base_desc}\n\n**Skills ({skill_count}):** {skills_str}"
+                )
             else:
                 enhanced_desc = f"{base_desc}\n\n**Skills:** {skills_str}"
 
@@ -122,7 +128,9 @@ class PeerAgentTool(BaseTool):
                 # Truncate to first 4 skills to keep it concise
                 skill_names = []
                 for skill in agent_card.skills[:4]:
-                    skill_name = getattr(skill, 'name', None) or getattr(skill, 'id', None)
+                    skill_name = getattr(skill, "name", None) or getattr(
+                        skill, "id", None
+                    )
                     if skill_name:
                         skill_names.append(skill_name)
                 skills_str = ", ".join(skill_names)
@@ -131,7 +139,9 @@ class PeerAgentTool(BaseTool):
                     skills_str += f" ({remaining} more...)"
 
                 if skill_count > 1:
-                    enhanced_desc = f"{base_desc}\n\n**Skills ({skill_count}):** {skills_str}"
+                    enhanced_desc = (
+                        f"{base_desc}\n\n**Skills ({skill_count}):** {skills_str}"
+                    )
                 else:
                     enhanced_desc = f"{base_desc}\n\n**Skills:** {skills_str}"
         else:
@@ -264,13 +274,10 @@ class PeerAgentTool(BaseTool):
                     f"TaskExecutionContext not found for task '{main_logical_task_id}'"
                 )
 
-            task_context_obj.register_parallel_call_sent(invocation_id)
-            log.info(
-                "%s Registered parallel call for invocation %s. Current state: %s",
-                log_identifier,
-                invocation_id,
-                task_context_obj.parallel_tool_calls.get(invocation_id),
-            )
+            # NOTE: register_parallel_call_sent is called in
+            # preregister_long_running_tools_callback (after_model_callback)
+            # BEFORE tool execution begins. This prevents race conditions where
+            # one tool completes before another registers.
 
             a2a_message_parts = self._prepare_a2a_parts(args, tool_context)
             a2a_metadata = {}

solace_agent_mesh/agent/tools/tool_config_types.py

@@ -47,11 +47,31 @@ class McpToolConfig(BaseToolConfig):
     """Configuration for an MCP tool or toolset."""
     tool_type: Literal["mcp"]
     connection_params: Dict[str, Any]
-    tool_name: Optional[str] = None # Optional filter
+    tool_name: Optional[str] = None  # Single tool filter (backward compat)
+    tool_name_prefix: Optional[str] = None # Optional prefix for tool names
     environment_variables: Optional[Dict[str, Any]] = None
     auth: dict[str, Any] | None = None
     manifest: list[dict[str, Any]] | None = None
 
+    # Tool filtering options (mutually exclusive with each other AND with tool_name)
+    allow_list: Optional[List[str]] = None  # Include only these tools
+    deny_list: Optional[List[str]] = None   # Exclude these tools
+
+    @model_validator(mode='after')
+    def validate_tool_filtering(self):
+        """Ensure tool_name, allow_list, and deny_list are mutually exclusive."""
+        filters_specified = [
+            self.tool_name is not None,
+            self.allow_list is not None,
+            self.deny_list is not None,
+        ]
+        if sum(filters_specified) > 1:
+            raise ValueError(
+                "MCP tool configuration error: 'tool_name', 'allow_list', and 'deny_list' "
+                "are mutually exclusive. Please use only one."
+            )
+        return self
+
 
 class OpenApiToolConfig(BaseToolConfig):
     """Configuration for OpenAPI-based tools."""