Make MCP connection gating non-blocking per server

Switch the agentframework extension from blocking gating (raise
McpConnectionsRequiredError before building the agent when any server is Pending)
to non-blocking per-server gating:

- Ready servers (and legacy sources with no connectivityStatus) are wired as live
  MCPStreamableHTTPTool instances, unchanged.
- A Pending server is registered as a single placeholder FunctionTool named after
  the server (max_invocations=1). When the model invokes it, the placeholder
  RETURNS a static setup message including missing_connections_url (fallback
  all_connections_url) for the model to relay. The agent is always built and Ready
  tools stay usable; the user is only prompted about connections if their request
  actually needs the Pending server.

The placeholder returns the message rather than raising it: Agent Framework
swallows exceptions raised inside a tool and converts UserInputRequiredException
into tool-result content, so neither reaches the turn handler. Returning the text
is the only way to surface the URL through the model.

McpConnectionsRequiredError stays exported for developers who want custom blocking
gating; it now carries missing_connections_url, connectivity_status, server_names,
and shares the new format_mcp_connections_required_message helper with the
placeholder so the message wording has a single source of truth.

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

Author: gwharris7

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

@@ -41,8 +41,7 @@ McpToolRegistrationService.add_tool_servers_to_agent()
        │
        ├── Resolve agent identity
        ├── Exchange token for MCP scope
-       ├── Gate: raise McpConnectionsRequiredError if any server is Pending
-       ├── Create MCPStreamableHTTPTool for each (Ready) server
+       ├── Gate (per server, non-blocking): Ready → MCPStreamableHTTPTool; Pending → placeholder tool
        └── Create ChatAgent with all tools
        │
        ▼
@@ -77,50 +76,65 @@ 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.
+### Connection-readiness gating (non-blocking, per server)
+
+MCP server discovery runs every turn. The gateway reports each server's `connectivityStatus`
+(`"Ready"` or `"Pending"`) along with a `missingConnectionsUrl` the user can visit to set up the
+connection(s) that server needs. Gating is **per server and non-blocking**:
+
+- A **Ready** server (or a legacy source with no `connectivityStatus`) is wired as a live
+  `MCPStreamableHTTPTool`, exactly as before.
+- A **Pending** server is wired as a single **placeholder tool** named after the server. The agent
+  is still built and the Ready servers remain fully usable for the turn. Only if the model invokes
+  the placeholder — because the user's request actually needs that server — does it return a static
+  message (including `missingConnectionsUrl`) for the model to relay to the user. If the turn never
+  needs the Pending server, the user is never bothered. A later turn re-runs discovery and wires the
+  server for real once its connections are in place.
+
+The placeholder **returns** the message rather than raising it. 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), and it converts `UserInputRequiredException` into
+tool-result content rather than propagating it — so returning the text is the only way to surface
+the setup URL through the model. Because surfacing flows through the model, exact verbatim delivery
+is best-effort; the placeholder's description instructs the model to relay the message and URL
+verbatim, and `max_invocations=1` stops the model from looping on it within a turn.
+
+> **Note:** A Pending server is represented by one placeholder named after the server (its real
+> sub-tools are invisible until it connects). The model routes the user's intent to it by server
+> name plus description — best-effort, not guaranteed.
 
 ```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.
+# Non-blocking: Pending servers become placeholders, so no special handling is needed in the
+# turn handler. The agent is always built and Ready tools always run.
+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,
+)
+```
+
+For developers who instead want **blocking** behavior (abort the whole turn until every server is
+connected), the extension still exports `McpConnectionsRequiredError`. Inspect the discovered
+servers yourself and raise it before building the agent:
+
+```python
+from microsoft_agents_a365.tooling.extensions.agentframework import McpConnectionsRequiredError
 ```
 
-`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).
+`McpConnectionsRequiredError` exposes `missing_connections_url`, `connectivity_status`, and
+`server_names`, and its message is built from the same `format_mcp_connections_required_message`
+helper the placeholder uses. 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
 

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

@@ -1,44 +1,77 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
-"""Exceptions raised by the Agent Framework MCP tooling extension."""
+"""Exceptions and message helpers for the Agent Framework MCP tooling extension."""
 
 from typing import List, Optional
 
 
+def format_mcp_connections_required_message(
+    *,
+    server_names: List[str],
+    connectivity_status: Optional[str],
+    missing_connections_url: Optional[str],
+) -> str:
+    """Build the static, user-facing message shown when an MCP server needs connection setup.
+
+    This single helper is the source of truth for the wording so that the message a Pending
+    server's placeholder tool returns to the model is identical to the message carried by
+    ``McpConnectionsRequiredError``.
+
+    Args:
+        server_names: Names of the MCP server(s) whose downstream connections are not set up.
+        connectivity_status: The gateway-reported ``connectivityStatus`` (typically ``"Pending"``).
+        missing_connections_url: URL the user opens to set up the missing connection(s). May be
+            ``None`` when the gateway did not supply one.
+
+    Returns:
+        A human-readable message suitable for relaying verbatim to the end user.
+    """
+    servers_text = ", ".join(server_names) if server_names else "(unknown)"
+    message = (
+        f"The tool(s) from MCP server(s) [{servers_text}] can't be used yet because the "
+        f"required data connection(s) aren't set up (connectivityStatus={connectivity_status})."
+    )
+    if missing_connections_url:
+        message += f" Set up the missing connection(s) here: {missing_connections_url}"
+    else:
+        message += " Ask your administrator to set up the required connection(s)."
+    return message
+
+
 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.
+    """Raised when an MCP server the user invoked is 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. Discovery runs every turn.
+
+    The agentframework extension gates **per server, non-blocking**: Ready servers are wired as
+    real tools and a Pending server is registered as a placeholder tool. Only when the model
+    actually invokes that placeholder (because the user's request needs the server) is the static
+    setup message — including ``missing_connections_url`` — surfaced; the rest of the turn runs
+    normally with the Ready tools.
+
+    This exception is **not** raised by the non-blocking gate (Agent Framework swallows exceptions
+    raised inside a tool, and converts ``UserInputRequiredException`` into tool-result content, so
+    neither reaches the developer's turn handler). It is exported for developers who want to
+    implement their own *blocking* gating — e.g. inspect the discovered servers and raise this
+    before building the agent to abort the whole turn — and as the structured carrier of the same
+    message the placeholder returns.
     """
 
     def __init__(
         self,
-        all_connections_url: Optional[str],
+        missing_connections_url: Optional[str],
         connectivity_status: Optional[str],
         server_names: List[str],
     ) -> None:
-        self.all_connections_url = all_connections_url
+        self.missing_connections_url = missing_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}"
+            format_mcp_connections_required_message(
+                server_names=server_names,
+                connectivity_status=connectivity_status,
+                missing_connections_url=missing_connections_url,
+            )
         )