McpToolRegistrationService Class

Service for managing MCP tools and servers for an agent

Constructor

McpToolRegistrationService()

Parameters

Name	Description
logger	Default value: None

Methods

__init__	Initialize the MCP Tool Registration Service for OpenAI.
__new__
add_tool_servers_to_agent	Add new MCP servers to the agent by creating a new Agent instance. Note: Due to OpenAI Agents SDK limitations, MCP servers must be set during Agent creation. If new servers are found, this method creates a new Agent instance with all MCP servers (existing + new) properly initialized.
cleanup_all_servers	Clean up all connected MCP servers
send_chat_history	Extract chat history from an OpenAI Session and send it to the MCP platform. This method extracts messages from an OpenAI Session object using get_items() and sends them to the MCP platform for real-time threat protection.
send_chat_history_messages	Send OpenAI chat history messages to the MCP platform for threat protection. This method accepts a list of OpenAI TResponseInputItem messages, converts them to ChatHistoryMessage format, and sends them to the MCP platform. Note Even if messages is empty or all messages are filtered during conversion, 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 Registration Service for OpenAI.

__init__(logger: Logger | None = None)

Parameters

Name	Description
logger	Logger \| None Logger instance for logging operations. Default value: None

new

__new__(**kwargs)

add_tool_servers_to_agent

Add new MCP servers to the agent by creating a new Agent instance.

Note: Due to OpenAI Agents SDK limitations, MCP servers must be set during Agent creation. If new servers are found, this method creates a new Agent instance with all MCP servers (existing + new) properly initialized.

async add_tool_servers_to_agent(agent: Agent, auth: Authorization, auth_handler_name: str, context: TurnContext, auth_token: str | None = None) -> Agent

Parameters

Name	Description
agent Required	<xref:agents.agent.Agent> The existing agent to add servers to
auth Required	Authorization Authorization handler for token exchange.
auth_handler_name Required	str Name of the authorization handler.
context Required	TurnContext Turn context for the current operation.
auth_token	str \| None Authentication token to access the MCP servers. Default value: None

Returns

Type	Description
<xref:agents.agent.Agent>	New Agent instance with all MCP servers, or original agent if no new servers

cleanup_all_servers

Clean up all connected MCP servers

async cleanup_all_servers() -> None

Returns

Type	Description
None

send_chat_history

Extract chat history from an OpenAI Session and send it to the MCP platform.

This method extracts messages from an OpenAI Session object using get_items() and sends them to the MCP platform for real-time threat protection.

async send_chat_history(turn_context: TurnContext, session: Session, limit: int | None = None, options: ToolOptions | None = None) -> OperationResult

Parameters

Name	Description
turn_context Required	TurnContext TurnContext from the Agents SDK containing conversation info. Must have a valid activity with conversation.id, activity.id, and activity.text.
session Required	<xref:agents.memory.session.Session> OpenAI Session instance to extract messages from. Must support the get_items() method which returns a list of TResponseInputItem.
limit	int \| None Optional maximum number of items to retrieve from session. If None, retrieves all items. Default value: None
options	ToolOptions \| None Optional ToolOptions for customization. If not provided, uses default options with orchestrator_name="OpenAI". Default value: None

Returns

Type	Description
OperationResult	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 or session is None.

Examples


>>> from agents import Agent, Runner
>>> from microsoft_agents_a365.tooling.extensions.openai import (
...     McpToolRegistrationService
... )
>>>
>>> service = McpToolRegistrationService()
>>> agent = Agent(name="my-agent", model="gpt-4")
>>>
>>> # In your agent handler:
>>> async with Runner.run(agent, messages) as result:
...     session = result.session
...     op_result = await service.send_chat_history(
...         turn_context, session
...     )
...     if op_result.succeeded:
...         print("Chat history sent successfully")

send_chat_history_messages

Send OpenAI chat history messages to the MCP platform for threat protection.

This method accepts a list of OpenAI TResponseInputItem messages, converts them to ChatHistoryMessage format, and sends them to the MCP platform.

Note

Even if messages is empty or all messages are filtered during conversion,

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_messages(turn_context: TurnContext, messages: List[EasyInputMessageParam | Message | ResponseOutputMessageParam | ResponseFileSearchToolCallParam | ResponseComputerToolCallParam | ComputerCallOutput | ResponseFunctionWebSearchParam | ResponseFunctionToolCallParam | FunctionCallOutput | ToolSearchCall | ResponseToolSearchOutputItemParamParam | ResponseReasoningItemParam | ResponseCompactionItemParamParam | ImageGenerationCall | ResponseCodeInterpreterToolCallParam | LocalShellCall | LocalShellCallOutput | ShellCall | ShellCallOutput | ApplyPatchCall | ApplyPatchCallOutput | McpListTools | McpApprovalRequest | McpApprovalResponse | McpCall | ResponseCustomToolCallOutputParam | ResponseCustomToolCallParam | ItemReference], options: ToolOptions | None = None) -> OperationResult

Parameters

Name	Description
turn_context Required	TurnContext TurnContext from the Agents SDK containing conversation info. Must have a valid activity with conversation.id, activity.id, and activity.text.
messages Required	List[<xref:openai.types.responses.easy_input_message_param.EasyInputMessageParam> \| <xref:openai.types.responses.response_input_item_param.Message> \| <xref:openai.types.responses.response_output_message_param.ResponseOutputMessageParam> \| <xref:openai.types.responses.response_file_search_tool_call_param.ResponseFileSearchToolCallParam> \| <xref:openai.types.responses.response_computer_tool_call_param.ResponseComputerToolCallParam> \| <xref:openai.types.responses.response_input_item_param.ComputerCallOutput> \| <xref:openai.types.responses.response_function_web_search_param.ResponseFunctionWebSearchParam> \| <xref:openai.types.responses.response_function_tool_call_param.ResponseFunctionToolCallParam> \| <xref:openai.types.responses.response_input_item_param.FunctionCallOutput> \| <xref:openai.types.responses.response_input_item_param.ToolSearchCall> \| <xref:openai.types.responses.response_tool_search_output_item_param_param.ResponseToolSearchOutputItemParamParam> \| <xref:openai.types.responses.response_reasoning_item_param.ResponseReasoningItemParam> \| <xref:openai.types.responses.response_compaction_item_param_param.ResponseCompactionItemParamParam> \| <xref:openai.types.responses.response_input_item_param.ImageGenerationCall> \| <xref:openai.types.responses.response_code_interpreter_tool_call_param.ResponseCodeInterpreterToolCallParam> \| <xref:openai.types.responses.response_input_item_param.LocalShellCall> \| <xref:openai.types.responses.response_input_item_param.LocalShellCallOutput> \| <xref:openai.types.responses.response_input_item_param.ShellCall> \| <xref:openai.types.responses.response_input_item_param.ShellCallOutput> \| <xref:openai.types.responses.response_input_item_param.ApplyPatchCall> \| <xref:openai.types.responses.response_input_item_param.ApplyPatchCallOutput> \| <xref:openai.types.responses.response_input_item_param.McpListTools> \| <xref:openai.types.responses.response_input_item_param.McpApprovalRequest> \| <xref:openai.types.responses.response_input_item_param.McpApprovalResponse> \| <xref:openai.types.responses.response_input_item_param.McpCall> \| <xref:openai.types.responses.response_custom_tool_call_output_param.ResponseCustomToolCallOutputParam> \| <xref:openai.types.responses.response_custom_tool_call_param.ResponseCustomToolCallParam> \| <xref:openai.types.responses.response_input_item_param.ItemReference>] List of OpenAI TResponseInputItem messages to send. Supports UserMessage, AssistantMessage, SystemMessage, and other OpenAI message types. Can be empty - the request will still be sent to register the user message from turn_context.activity.text.
options	ToolOptions \| None Optional ToolOptions for customization. If not provided, uses default options with orchestrator_name="OpenAI". Default value: None

Returns

Type	Description
OperationResult	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 or messages is None.

Examples


>>> from microsoft_agents_a365.tooling.extensions.openai import (
...     McpToolRegistrationService
... )
>>>
>>> service = McpToolRegistrationService()
>>> messages = [
...     {"role": "user", "content": "Hello"},
...     {"role": "assistant", "content": "Hi there!"},
... ]
>>>
>>> result = await service.send_chat_history_messages(
...     turn_context, messages
... )
>>> if result.succeeded:
...     print("Chat history sent successfully")