Relocate MCP connection gating to agentframework extension

Move connection-readiness gating out of the core tooling package and into the
Agent Framework extension. Core now only parses the per-server schema fields
(connectivityStatus, allConnectionsUrl, missingConnectionsUrl) onto each
MCPServerConfig and never gates or raises.

Core:
- Remove the internal McpDiscoveryResult dataclass, the deprecated
  _enforce_connection_readiness method, and the _CONNECTIVITY_READY constant.
- _parse_gateway_response/_load_servers_from_gateway return List[MCPServerConfig]
  again; response-level aggregate fields are ignored.
- Delete exceptions.py and drop McpConnectionsRequiredError from the public API.

Extension (agentframework):
- Own McpConnectionsRequiredError (all_connections_url, connectivity_status,
  server_names) and export it from the package root.
- Gate at registration time in add_tool_servers_to_agent: when any discovered
  server is Pending, raise before building the agent so the turn handler can
  prompt the user with all_connections_url. Replaces the per-server FunctionTool
  placeholder mechanism.

Raising at construction time (not inside a FunctionTool) is required because
Agent Framework's tool-call loop swallows exceptions raised inside a tool and
returns 'Error: Function failed.' to the model, which would drop the setup URL.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: gwharris7

libraries/microsoft-agents-a365-tooling-extensions-agentframework/docs/design.md

@@ -41,7 +41,8 @@ McpToolRegistrationService.add_tool_servers_to_agent()
        │
        ├── Resolve agent identity
        ├── Exchange token for MCP scope
-       ├── Create MCPStreamableHTTPTool for each server
+       ├── Gate: raise McpConnectionsRequiredError if any server is Pending
+       ├── Create MCPStreamableHTTPTool for each (Ready) server
        └── Create ChatAgent with all tools
        │
        ▼
@@ -76,6 +77,51 @@ mcp_tool = MCPStreamableHTTPTool(
 )
 ```
 
+### Connection-readiness gating
+
+MCP server discovery runs every turn. The gateway reports each server's
+`connectivityStatus` (`"Ready"` or `"Pending"`) along with an `allConnectionsUrl` the user
+can visit to view and manage the connectors required by that server. When **any** discovered
+server is `Pending`, `add_tool_servers_to_agent` raises `McpConnectionsRequiredError`
+**before** building the agent, so the developer's turn handler can prompt the user to set up
+connections and return. A later turn re-runs discovery and proceeds automatically once the
+connections are in place.
+
+The gate raises at agent-construction time — not from inside a tool call — on purpose. Agent
+Framework's tool-call loop catches exceptions raised inside a `FunctionTool` and reflects them
+to the model as an opaque error string (`"Error: Function failed."` by default), which would
+drop the setup URL before it reached the user. Raising during construction lets the typed
+exception propagate intact to the turn handler.
+
+```python
+from microsoft_agents_a365.tooling.extensions.agentframework import (
+    McpToolRegistrationService,
+    McpConnectionsRequiredError,
+)
+
+service = McpToolRegistrationService()
+
+try:
+    agent = await service.add_tool_servers_to_agent(
+        chat_client=chat_client,
+        agent_instructions="You are a helpful assistant.",
+        initial_tools=[],
+        auth=auth_context,
+        auth_handler_name="graph",
+        turn_context=turn_context,
+    )
+except McpConnectionsRequiredError as err:
+    await turn_context.send_activity(
+        f"Before I can help, please set up the required connections for "
+        f"{', '.join(err.server_names)}: {err.all_connections_url}"
+    )
+    return  # Skip running the model/tools this turn.
+```
+
+`McpConnectionsRequiredError` exposes `all_connections_url`, `connectivity_status`, and
+`server_names`. It is owned and exported by this extension (`microsoft_agents_a365.tooling`
+core only parses the per-server connection metadata; it never gates or raises).
+
 ### Chat History API
 
 The service provides methods to send chat history to the MCP platform for real-time threat protection analysis. This enables security scanning of conversation content.

libraries/microsoft-agents-a365-tooling-extensions-agentframework/microsoft_agents_a365/tooling/extensions/agentframework/__init__.py

@@ -21,8 +21,10 @@
 __version__ = "1.0.0"
 
 # Import services from the services module
+from .exceptions import McpConnectionsRequiredError
 from .services import McpToolRegistrationService
 
 __all__ = [
     "McpToolRegistrationService",
+    "McpConnectionsRequiredError",
 ]

libraries/microsoft-agents-a365-tooling-extensions-agentframework/microsoft_agents_a365/tooling/extensions/agentframework/exceptions.py

@@ -0,0 +1,44 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Exceptions raised by the Agent Framework MCP tooling extension."""
+
+from typing import List, Optional
+
+
+class McpConnectionsRequiredError(Exception):
+    """Raised when one or more configured MCP servers are not yet connection-ready.
+
+    The tooling gateway reports a per-server ``connectivityStatus`` of ``"Pending"``
+    when an MCP server has downstream connections the user has not yet established.
+    ``McpToolRegistrationService.add_tool_servers_to_agent`` discovers the servers
+    every turn and raises this error *before* building the agent when any server is
+    Pending, so the agent's turn handler can catch it, reply to the user with
+    ``all_connections_url``, and return without running the model/tools. A later turn
+    re-runs discovery and proceeds once the connections are in place.
+
+    The error is raised at agent-construction time (not from inside a tool call) so it
+    propagates to the developer's turn handler intact — Agent Framework's tool-call loop
+    swallows exceptions raised inside a ``FunctionTool`` and reflects them to the model
+    as an opaque error string, which would drop the setup URL.
+
+    ``all_connections_url`` lets the user view and manage the full set of connectors
+    required by the affected servers — including ones already set up — rather than being
+    scoped strictly to the ones that happen to be missing right now.
+    """
+
+    def __init__(
+        self,
+        all_connections_url: Optional[str],
+        connectivity_status: Optional[str],
+        server_names: List[str],
+    ) -> None:
+        self.all_connections_url = all_connections_url
+        self.connectivity_status = connectivity_status
+        self.server_names = server_names
+        servers_text = ", ".join(server_names) if server_names else "(unknown)"
+        super().__init__(
+            f"MCP servers [{servers_text}] require connection setup "
+            f"(connectivityStatus={connectivity_status}). "
+            f"Set up connections at: {all_connections_url}"
+        )

libraries/microsoft-agents-a365-tooling-extensions-agentframework/microsoft_agents_a365/tooling/extensions/agentframework/services/mcp_tool_registration_service.py

@@ -28,10 +28,18 @@
     is_development_environment,
 )
 
+from ..exceptions import McpConnectionsRequiredError
+
 
 # Default timeout for MCP server HTTP requests (in seconds)
 MCP_HTTP_CLIENT_TIMEOUT_SECONDS = 90.0
 
+# Sentinel per-server status that means a server's downstream connections are
+# already in place. Anything else (typically "Pending") triggers the
+# connection-readiness gate, which raises McpConnectionsRequiredError before the
+# agent is built so the turn handler can prompt the user to set up connections.
+_CONNECTIVITY_READY = "Ready"
+
 
 class McpToolRegistrationService:
     """
@@ -114,11 +122,59 @@ async def add_tool_servers_to_agent(
             )
 
             self._logger.info(f"Loaded {len(server_configs)} MCP server configurations")
+            for c in server_configs:
+                _name = c.mcp_server_name or c.mcp_server_unique_name
+                self._logger.info(
+                    "  per-server gateway state: name=%s connectivity_status=%r missing_url=%s",
+                    _name,
+                    c.connectivity_status,
+                    c.missing_connections_url,
+                )
+
+            # Connection-readiness gate.  Discovery runs every turn; when the
+            # gateway flags any MCP server's downstream connection(s) as not yet
+            # set up (``connectivityStatus == "Pending"``), raise before building
+            # the agent so the developer's turn handler can catch the error,
+            # prompt the user with ``all_connections_url``, and return without
+            # running the model/tools.  A later turn re-runs discovery and
+            # proceeds automatically once the connections are in place.
+            #
+            # The gate raises here — at agent-construction time — rather than
+            # from inside a tool call on purpose: Agent Framework's tool-call
+            # loop swallows exceptions raised inside a ``FunctionTool`` and
+            # reflects them to the model as an opaque error string, which would
+            # drop the setup URL before it ever reaches the user.
+            pending = [
+                c
+                for c in server_configs
+                if c.connectivity_status is not None
+                and c.connectivity_status != _CONNECTIVITY_READY
+            ]
+            if pending:
+                pending_names = [c.mcp_server_name or c.mcp_server_unique_name for c in pending]
+                # Surface all_connections_url so the user can view and manage the
+                # full set of connectors required by the affected servers. Use the
+                # first pending server that provides one (they are environment-scoped
+                # and typically identical across servers).
+                all_connections_url = next(
+                    (c.all_connections_url for c in pending if c.all_connections_url),
+                    None,
+                )
+                self._logger.info(
+                    "MCP connection gate blocking turn: pending servers=%s, setup URL=%s",
+                    pending_names,
+                    all_connections_url,
+                )
+                raise McpConnectionsRequiredError(
+                    all_connections_url=all_connections_url,
+                    connectivity_status=pending[0].connectivity_status,
+                    server_names=pending_names,
+                )
 
             # Create the agent with all tools (initial + MCP tools)
             all_tools = list(initial_tools)
 
-            # Add servers as MCPStreamableHTTPTool instances
+            # Add each Ready server as an MCPStreamableHTTPTool instance.
             for config in server_configs:
                 # Use mcp_server_name if available (not None or empty), otherwise fall back to mcp_server_unique_name
                 server_name = config.mcp_server_name or config.mcp_server_unique_name
@@ -183,6 +239,9 @@ async def add_tool_servers_to_agent(
             self._logger.info(f"Agent created with {len(all_tools)} total tools")
             return agent
 
+        except McpConnectionsRequiredError:
+            # Connection-readiness gate — propagate intact to the turn handler.
+            raise
         except Exception as ex:
             self._logger.error(f"Failed to add tool servers to agent: {ex}")
             raise

libraries/microsoft-agents-a365-tooling/CHANGELOG.md

@@ -35,7 +35,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `ChatHistoryMessage` Pydantic model for representing individual messages in chat history
 - Added `ChatMessageRequest` Pydantic model for the chat history API request payload
 - Added `py.typed` marker for PEP 561 compliance, enabling type checker support
-- Added connection-readiness gating to `McpToolServerConfigurationService.list_tool_servers()`. When the tooling gateway reports an aggregate `connectivityStatus` of `"Pending"`, a `McpConnectionsRequiredError` is raised carrying the response-level `missingConnectionsUrl` and the names of the not-`Ready` servers, so the agent's turn handler can prompt the user to set up connections instead of running tools that would fail. Dev-mode manifests and legacy raw-array gateway responses omit the field and are never gated
-- Added `McpConnectionsRequiredError` exception (exported from `microsoft_agents_a365.tooling`) with `missing_connections_url`, `connectivity_status`, and `server_names` attributes
-- Added `id`, `all_connections_url`, `missing_connections_url`, and `connectivity_status` fields to `MCPServerConfig`, parsed from the per-server gateway payload
-- Added internal `McpDiscoveryResult` dataclass; `_parse_gateway_response()` and `_load_servers_from_gateway()` now return it to carry response-level connection metadata alongside the server list (the public return type of `list_tool_servers()` remains `List[MCPServerConfig]`)
+- Added `id`, `all_connections_url`, `missing_connections_url`, and `connectivity_status` fields to `MCPServerConfig`, parsed from the per-server gateway payload (`allConnectionsUrl`, `missingConnectionsUrl`, `connectivityStatus`). The core service parses this connection metadata onto each server but does not gate on it — connection-readiness gating is owned by the framework-specific tooling extensions
+- `_parse_gateway_response()` and `_load_servers_from_gateway()` return `List[MCPServerConfig]`; the wrapped `{"mcpServers": [...]}` and legacy raw-array gateway response shapes are both supported, and response-level (aggregate) connection fields are ignored

libraries/microsoft-agents-a365-tooling/docs/design.md

@@ -108,35 +108,15 @@ User-Agent: Agent365SDK/0.1.0 (...)
 
 The gateway returns the same JSON structure, but `mcpServerUniqueName` contains the full endpoint URL.
 
-### Connection gating
-
-When the tooling gateway reports that an agent's MCP servers have unsatisfied downstream
-connections, `list_tool_servers()` raises `McpConnectionsRequiredError`. Discovery runs
-every turn, so the agent's turn handler should catch the error, reply with the
-connection-setup link, and return — a later turn proceeds automatically once the user has
-connected.
-
-```python
-from microsoft_agents_a365.tooling import McpConnectionsRequiredError
-
-try:
-    servers = await config_service.list_tool_servers(
-        agentic_app_id=agentic_app_id,
-        auth_token=auth_token,
-        authorization=auth,
-        auth_handler_name=auth_handler_name,
-        turn_context=context,
-    )
-except McpConnectionsRequiredError as err:
-    await context.send_activity(
-        f"Before I can help, please set up the required connections for "
-        f"{', '.join(err.server_names)}: {err.missing_connections_url}"
-    )
-    return  # Skip running the model/tools this turn.
-```
-
-The gate fires only for gateway responses with aggregate `connectivityStatus == "Pending"`.
-Dev-mode manifests and legacy raw-array responses omit the field and are never gated.
+### Connection metadata (per-server)
+
+The core service parses each server's connection metadata — `connectivityStatus`,
+`allConnectionsUrl`, and `missingConnectionsUrl` — onto the returned `MCPServerConfig`
+objects, but it does **not** gate on them. Connection-readiness gating is the
+responsibility of the framework-specific tooling extensions (e.g.
+`microsoft-agents-a365-tooling-extensions-agentframework`), which decide how to surface a
+`Pending` server and raise/handle the appropriate error. See the relevant extension's
+design document for details.
 
 ### MCPServerConfig ([models/mcp_server_config.py](../microsoft_agents_a365/tooling/models/mcp_server_config.py))
 

libraries/microsoft-agents-a365-tooling/microsoft_agents_a365/tooling/__init__.py

@@ -8,7 +8,6 @@
 Provides base utilities and common helper functions.
 """
 
-from .exceptions import McpConnectionsRequiredError
 from .models import MCPServerConfig
 from .services import McpToolServerConfigurationService
 from .utils import Constants
@@ -23,7 +22,6 @@
 __all__ = [
     "MCPServerConfig",
     "McpToolServerConfigurationService",
-    "McpConnectionsRequiredError",
     "Constants",
     "get_tooling_gateway_for_digital_worker",
     "get_mcp_base_url",