McpToolServerConfigurationService Class

Provides services for MCP tool server configuration management.

This service handles discovery and configuration of MCP (Model Context Protocol) tool servers from multiple sources:

Development: Local ToolingManifest.json files
Production: Remote tooling gateway endpoints

Constructor

McpToolServerConfigurationService()

Parameters

Name	Description
logger	Default value: None

Methods

__init__	Initialize the MCP Tool Server Configuration Service.
__new__
list_tool_servers	Gets the list of MCP Servers that are configured for the agent. When `authorization`, `auth_handler_name`, and `turn_context` are all provided, per-audience OAuth tokens are acquired for each server after discovery: V1 servers (no `audience` field) share the shared ATG token (one exchange). V2 servers each receive a token scoped to their own audience GUID.
send_chat_history	Sends chat history to the MCP platform for real-time threat protection. Note Even if chat_history_messages is empty, the request will still be sent to the MCP platform. This ensures the user message from turn_context.activity.text is registered correctly for real-time threat protection.

init

Initialize the MCP Tool Server Configuration Service.

__init__(logger: Logger | None = None)

Parameters

Name	Description
logger	Logger \| None Logger instance for logging operations. If None, creates a new logger. Default value: None

new

__new__(**kwargs)

list_tool_servers

Gets the list of MCP Servers that are configured for the agent.

When authorization, auth_handler_name, and turn_context are all provided, per-audience OAuth tokens are acquired for each server after discovery:

V1 servers (no audience field) share the shared ATG token (one exchange).
V2 servers each receive a token scoped to their own audience GUID.

async list_tool_servers(agentic_app_id: str, auth_token: str | None = None, options: ToolOptions | None = None, authorization: Authorization | None = None, auth_handler_name: str | None = None, turn_context: TurnContext | None = None) -> List[MCPServerConfig]

Parameters

Name	Description
agentic_app_id Required	str Agentic App ID for the agent.
auth_token	str \| None Authentication token used for gateway discovery. Default value: None
options	ToolOptions \| None Optional ToolOptions instance containing optional parameters. Default value: None
authorization	Authorization \| None Optional Authorization context for per-audience token exchange. Default value: None
auth_handler_name	str \| None Optional auth handler name used with `authorization`. Default value: None
turn_context	TurnContext \| None Optional TurnContext used with `authorization`. Default value: None

Returns

Type	Description
List[MCPServerConfig]	Returns the list of MCP Servers that are configured, each with an `Authorization` header attached when auth context is provided.

Exceptions

Type	Description
ValueError	If required parameters are invalid or empty.
Exception	If there's an error communicating with the tooling gateway or a per-audience token exchange fails.

send_chat_history

Sends chat history to the MCP platform for real-time threat protection.

Note

Even if chat_history_messages is empty, the request will still be sent to

the MCP platform. This ensures the user message from turn_context.activity.text

is registered correctly for real-time threat protection.

async send_chat_history(turn_context: TurnContext, chat_history_messages: List[ChatHistoryMessage], options: ToolOptions | None = None) -> OperationResult

Parameters

Name	Description
turn_context Required	TurnContext TurnContext from the Agents SDK containing conversation information. Must have a valid activity with conversation.id, activity.id, and activity.text.
chat_history_messages Required	List[ChatHistoryMessage] List of ChatHistoryMessage objects representing the chat history. May be empty - an empty list will still send a request to the MCP platform with empty chat history.
options	ToolOptions \| None Optional ToolOptions instance containing optional parameters. Default value: None

Returns

Type	Description
<xref:OperationResult>	An OperationResult indicating success or failure. On success, returns OperationResult.success(). On failure, returns OperationResult.failed() with error details.

Exceptions

Type	Description
ValueError	If turn_context is None, chat_history_messages is None, turn_context.activity is None, or any of the required fields (conversation.id, activity.id, activity.text) are missing or empty.

Examples


>>> from datetime import datetime, timezone
>>> from microsoft_agents_a365.tooling.models import ChatHistoryMessage
>>>
>>> history = [
...     ChatHistoryMessage("msg-1", "user", "Hello", datetime.now(timezone.utc)),
...     ChatHistoryMessage("msg-2", "assistant", "Hi!", datetime.now(timezone.utc))
... ]
>>>
>>> service = McpToolServerConfigurationService()
>>> result = await service.send_chat_history(turn_context, history)
>>> if result.succeeded:
...     print("Chat history sent successfully")