Skip to content

Building AI agents, atomically

feat: add async MCP tools fetcher without event loop dependency (#133)

jon fox963a14786f6c
diff --git a/atomic-agents/atomic_agents/lib/factories/mcp_tool_factory.py b/atomic-agents/atomic_agents/lib/factories/mcp_tool_factory.py
index 7dcf2ee..87f23a9 100644
--- a/atomic-agents/atomic_agents/lib/factories/mcp_tool_factory.py
+++ b/atomic-agents/atomic_agents/lib/factories/mcp_tool_factory.py
@@ -303,6 +303,34 @@ def fetch_mcp_tools(
return factory.create_tools()
+async def fetch_mcp_tools_async(
+ mcp_endpoint: Optional[str] = None,
+ transport_type: MCPTransportType = MCPTransportType.STDIO,
+ *,
+ client_session: Optional[ClientSession] = None,
+ working_directory: Optional[str] = None,
+) -> List[Type[BaseTool]]:
+ """
+ Asynchronously connects to an MCP server and dynamically generates BaseTool subclasses for each tool.
+ Must be called within an existing asyncio event loop context.
+
+ Args:
+ mcp_endpoint: URL of the MCP server (for HTTP/SSE) or command for STDIO.
+ transport_type: Type of transport to use (SSE, HTTP_STREAM, or STDIO).
+ client_session: Optional pre-initialized ClientSession for reuse.
+ working_directory: Optional working directory for STDIO transport.
+ """
+ if client_session is not None:
+ tool_defs = await ToolDefinitionService.fetch_definitions_from_session(client_session)
+ factory = MCPToolFactory(mcp_endpoint, transport_type, client_session, asyncio.get_running_loop(), working_directory)
+ else:
+ service = ToolDefinitionService(mcp_endpoint, transport_type, working_directory)
+ tool_defs = await service.fetch_definitions()
+ factory = MCPToolFactory(mcp_endpoint, transport_type, None, None, working_directory)
+
+ return factory._create_tool_classes(tool_defs)
+
+
def create_mcp_orchestrator_schema(tools: List[Type[BaseTool]]) -> Optional[Type[BaseIOSchema]]:
"""
Creates a schema for the MCP Orchestrator's output using the Union of all tool input schemas.
diff --git a/atomic-agents/tests/lib/factories/test_mcp_tool_factory.py b/atomic-agents/tests/lib/factories/test_mcp_tool_factory.py
index 47359d0..a3320be 100644
--- a/atomic-agents/tests/lib/factories/test_mcp_tool_factory.py
+++ b/atomic-agents/tests/lib/factories/test_mcp_tool_factory.py
@@ -5,6 +5,7 @@ from atomic_agents.lib.factories.mcp_tool_factory import (
fetch_mcp_tools,
create_mcp_orchestrator_schema,
fetch_mcp_tools_with_schema,
+ fetch_mcp_tools_async,
MCPToolFactory,
)
from atomic_agents.lib.factories.tool_definition_service import MCPToolDefinition, ToolDefinitionService, MCPTransportType
@@ -437,3 +438,245 @@ def test_http_stream_endpoint_formatting():
# Verify the factory was created with correct transport type
assert factory.transport_type == MCPTransportType.HTTP_STREAM
+
+
+# Tests for fetch_mcp_tools_async function
+
+
+async def test_fetch_mcp_tools_async_with_client_session(monkeypatch):
+ """Test fetch_mcp_tools_async with pre-initialized client session."""
+ import atomic_agents.lib.factories.mcp_tool_factory as mtf
+
+ # Setup persistent client
+ class DummySessionPersistent:
+ async def call_tool(self, name, arguments):
+ return {"content": "async-session-ok"}
+
+ client = DummySessionPersistent()
+ definitions = [
+ MCPToolDefinition(
+ name="AsyncTool", description="Test async tool", input_schema={"type": "object", "properties": {}, "required": []}
+ )
+ ]
+
+ async def fake_fetch_defs(session):
+ return definitions
+
+ monkeypatch.setattr(mtf.ToolDefinitionService, "fetch_definitions_from_session", staticmethod(fake_fetch_defs))
+
+ # Call fetch_mcp_tools_async with client session
+ tools = await fetch_mcp_tools_async(None, MCPTransportType.HTTP_STREAM, client_session=client)
+
+ assert len(tools) == 1
+ tool_cls = tools[0]
+ # Verify the tool was created correctly
+ assert hasattr(tool_cls, "mcp_tool_name")
+
+
+async def test_fetch_mcp_tools_async_without_client_session(monkeypatch):
+ """Test fetch_mcp_tools_async without pre-initialized client session."""
+
+ definitions = [
+ MCPToolDefinition(
+ name="AsyncTool2",
+ description="Test async tool 2",
+ input_schema={"type": "object", "properties": {}, "required": []},
+ )
+ ]
+
+ async def fake_fetch_defs(self):
+ return definitions
+
+ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)
+
+ # Call fetch_mcp_tools_async without client session
+ tools = await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)
+
+ assert len(tools) == 1
+ tool_cls = tools[0]
+ # Verify the tool was created correctly
+ assert hasattr(tool_cls, "mcp_tool_name")
+
+
+async def test_fetch_mcp_tools_async_stdio_transport(monkeypatch):
+ """Test fetch_mcp_tools_async with STDIO transport."""
+ definitions = [
+ MCPToolDefinition(
+ name="StdioAsyncTool",
+ description="Test stdio async tool",
+ input_schema={"type": "object", "properties": {}, "required": []},
+ )
+ ]
+
+ async def fake_fetch_defs(self):
+ return definitions
+
+ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)
+
+ # Call fetch_mcp_tools_async with STDIO transport
+ tools = await fetch_mcp_tools_async("test-command", MCPTransportType.STDIO, working_directory="/tmp")
+
+ assert len(tools) == 1
+ tool_cls = tools[0]
+ # Verify the tool was created correctly
+ assert hasattr(tool_cls, "mcp_tool_name")
+
+
+async def test_fetch_mcp_tools_async_empty_definitions(monkeypatch):
+ """Test fetch_mcp_tools_async returns empty list when no definitions found."""
+
+ async def fake_fetch_defs(self):
+ return []
+
+ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)
+
+ # Call fetch_mcp_tools_async
+ tools = await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)
+
+ assert tools == []
+
+
+async def test_fetch_mcp_tools_async_connection_error(monkeypatch):
+ """Test fetch_mcp_tools_async propagates connection errors."""
+
+ async def fake_fetch_defs_error(self):
+ raise ConnectionError("Failed to connect to MCP server")
+
+ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs_error)
+
+ # Call fetch_mcp_tools_async and expect ConnectionError
+ with pytest.raises(ConnectionError, match="Failed to connect to MCP server"):
+ await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)
+
+
+async def test_fetch_mcp_tools_async_runtime_error(monkeypatch):
+ """Test fetch_mcp_tools_async propagates runtime errors."""
+
+ async def fake_fetch_defs_error(self):
+ raise RuntimeError("Unexpected error during fetching")
+
+ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs_error)
+
+ # Call fetch_mcp_tools_async and expect RuntimeError
+ with pytest.raises(RuntimeError, match="Unexpected error during fetching"):
+ await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)
+
+
+async def test_fetch_mcp_tools_async_with_working_directory(monkeypatch):
+ """Test fetch_mcp_tools_async with working directory parameter."""
+ definitions = [
+ MCPToolDefinition(
+ name="WorkingDirTool",
+ description="Test tool with working dir",
+ input_schema={"type": "object", "properties": {}, "required": []},
+ )
+ ]
+
+ async def fake_fetch_defs(self):
+ return definitions
+
+ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)
+
+ # Call fetch_mcp_tools_async with working directory
+ tools = await fetch_mcp_tools_async("test-command", MCPTransportType.STDIO, working_directory="/custom/working/dir")
+
+ assert len(tools) == 1
+ tool_cls = tools[0]
+ # Verify the tool was created correctly
+ assert hasattr(tool_cls, "mcp_tool_name")
+
+
+async def test_fetch_mcp_tools_async_session_error_propagation(monkeypatch):
+ """Test fetch_mcp_tools_async with client session error propagation."""
+ import atomic_agents.lib.factories.mcp_tool_factory as mtf
+
+ class DummySessionPersistent:
+ async def call_tool(self, name, arguments):
+ return {"content": "session-ok"}
+
+ client = DummySessionPersistent()
+
+ async def fake_fetch_defs_error(session):
+ raise ValueError("Session fetch error")
+
+ monkeypatch.setattr(mtf.ToolDefinitionService, "fetch_definitions_from_session", staticmethod(fake_fetch_defs_error))
+
+ # Call fetch_mcp_tools_async with client session and expect error
+ with pytest.raises(ValueError, match="Session fetch error"):
+ await fetch_mcp_tools_async(None, MCPTransportType.HTTP_STREAM, client_session=client)
+
+
[email protected]("transport_type", [MCPTransportType.HTTP_STREAM, MCPTransportType.STDIO, MCPTransportType.SSE])
+async def test_fetch_mcp_tools_async_all_transport_types(monkeypatch, transport_type):
+ """Test fetch_mcp_tools_async with all supported transport types."""
+ definitions = [
+ MCPToolDefinition(
+ name=f"Tool_{transport_type.value}",
+ description=f"Test tool for {transport_type.value}",
+ input_schema={"type": "object", "properties": {}, "required": []},
+ )
+ ]
+
+ async def fake_fetch_defs(self):
+ return definitions
+
+ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)
+
+ # Determine endpoint based on transport type
+ endpoint = "test-command" if transport_type == MCPTransportType.STDIO else "http://test-endpoint"
+ working_dir = "/tmp" if transport_type == MCPTransportType.STDIO else None
+
+ # Call fetch_mcp_tools_async with different transport types
+ tools = await fetch_mcp_tools_async(endpoint, transport_type, working_directory=working_dir)
+
+ assert len(tools) == 1
+ tool_cls = tools[0]
+ # Verify the tool was created correctly
+ assert hasattr(tool_cls, "mcp_tool_name")
+
+
+async def test_fetch_mcp_tools_async_multiple_tools(monkeypatch):
+ """Test fetch_mcp_tools_async with multiple tool definitions."""
+ definitions = [
+ MCPToolDefinition(
+ name="Tool1", description="First tool", input_schema={"type": "object", "properties": {}, "required": []}
+ ),
+ MCPToolDefinition(
+ name="Tool2",
+ description="Second tool",
+ input_schema={"type": "object", "properties": {"param": {"type": "string"}}, "required": ["param"]},
+ ),
+ MCPToolDefinition(
+ name="Tool3",
+ description="Third tool",
+ input_schema={
+ "type": "object",
+ "properties": {"x": {"type": "number"}, "y": {"type": "number"}},
+ "required": ["x", "y"],
+ },
+ ),
+ ]
+
+ async def fake_fetch_defs(self):
+ return definitions
+
+ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)
+
+ # Call fetch_mcp_tools_async
+ tools = await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)
+
+ assert len(tools) == 3
+ tool_names = [getattr(tool_cls, "mcp_tool_name", None) for tool_cls in tools]
+ assert "Tool1" in tool_names
+ assert "Tool2" in tool_names
+ assert "Tool3" in tool_names
diff --git a/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.py b/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.py
new file mode 100644
index 0000000..ab18c24
--- /dev/null
+++ b/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.py
@@ -0,0 +1,222 @@
+# pyright: reportInvalidTypeForm=false
+from atomic_agents.lib.factories.mcp_tool_factory import fetch_mcp_tools_async, MCPToolOutputSchema
+from atomic_agents.lib.factories.tool_definition_service import MCPTransportType
+from rich.console import Console
+from rich.table import Table
+import openai
+import os
+import instructor
+import asyncio
+import shlex
+from contextlib import AsyncExitStack
+from pydantic import Field
+from atomic_agents.agents.base_agent import BaseIOSchema, BaseAgent, BaseAgentConfig
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+from atomic_agents.lib.components.chat_history import ChatHistory
+from typing import Union, Type, Dict
+from dataclasses import dataclass
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+
+# 1. Configuration and environment setup
+@dataclass
+class MCPConfig:
+ """Configuration for the MCP Agent system using STDIO transport."""
+
+ # NOTE: In contrast to other examples, we use gpt-4o and not gpt-4o-mini here.
+ # In my tests, gpt-4o-mini was not smart enough to deal with multiple tools like that
+ # and at the moment MCP does not yet allow for adding sufficient metadata to
+ # clarify tools even more and introduce more constraints.
+ openai_model: str = "gpt-4o"
+ openai_api_key: str = os.getenv("OPENAI_API_KEY")
+
+ # Command to run the STDIO server.
+ # In practice, this could be something like "pipx some-other-persons-server or npx some-other-persons-server
+ # if working with a server you did not write yourself.
+ mcp_stdio_server_command: str = "poetry run example-mcp-server --mode stdio"
+
+ def __post_init__(self):
+ if not self.openai_api_key:
+ raise ValueError("OPENAI_API_KEY environment variable is not set")
+
+
+config = MCPConfig()
+console = Console()
+client = instructor.from_openai(openai.OpenAI(api_key=config.openai_api_key))
+
+
+class FinalResponseSchema(BaseIOSchema):
+ """Schema for providing a final text response to the user."""
+
+ response_text: str = Field(..., description="The final text response to the user's query")
+
+
+async def main():
+ async with AsyncExitStack() as stack:
+ # Start MCP server
+ cmd, *args = shlex.split(config.mcp_stdio_server_command)
+ read_stream, write_stream = await stack.enter_async_context(
+ stdio_client(StdioServerParameters(command=cmd, args=args))
+ )
+ session = await stack.enter_async_context(ClientSession(read_stream, write_stream))
+ await session.initialize()
+
+ # Fetch tools - factory sees running loop
+ tools = await fetch_mcp_tools_async(
+ transport_type=MCPTransportType.STDIO,
+ client_session=session, # factory sees running loop
+ )
+
+ if not tools:
+ raise RuntimeError("No MCP tools found. Please ensure the MCP server is running and accessible.")
+
+ # Build mapping from input_schema to ToolClass
+ tool_schema_to_class_map: Dict[Type[BaseIOSchema], Type[BaseAgent]] = {
+ ToolClass.input_schema: ToolClass for ToolClass in tools if hasattr(ToolClass, "input_schema")
+ }
+ # Collect all tool input schemas
+ tool_input_schemas = tuple(tool_schema_to_class_map.keys())
+
+ # Available schemas include all tool input schemas and the final response schema
+ available_schemas = tool_input_schemas + (FinalResponseSchema,)
+
+ # Define the Union of all action schemas
+ ActionUnion = Union[available_schemas]
+
+ # 2. Schema and class definitions
+ class MCPOrchestratorInputSchema(BaseIOSchema):
+ """Input schema for the MCP Orchestrator Agent."""
+
+ query: str = Field(..., description="The user's query to analyze.")
+
+ class OrchestratorOutputSchema(BaseIOSchema):
+ """Output schema for the orchestrator. Contains reasoning and the chosen action."""
+
+ reasoning: str = Field(
+ ..., description="Detailed explanation of why this action was chosen and how it will address the user's query."
+ )
+ action: ActionUnion = Field( # type: ignore
+ ...,
+ description="The chosen action: either a tool's input schema instance or a final response schema instance.",
+ )
+
+ model_config = {"arbitrary_types_allowed": True}
+
+ # 3. Main logic
+ console.print("[bold green]Initializing MCP Agent System (STDIO mode - Async)...[/bold green]")
+
+ # Display available tools
+ table = Table(title="Available MCP Tools", box=None)
+ table.add_column("Tool Name", style="cyan")
+ table.add_column("Input Schema", style="yellow")
+ table.add_column("Description", style="magenta")
+ for ToolClass in tools:
+ schema_name = ToolClass.input_schema.__name__ if hasattr(ToolClass, "input_schema") else "N/A"
+ table.add_row(ToolClass.mcp_tool_name, schema_name, ToolClass.__doc__ or "")
+ console.print(table)
+
+ # Create and initialize orchestrator agent
+ console.print("[dim]• Creating orchestrator agent...[/dim]")
+ history = ChatHistory()
+ orchestrator_agent = BaseAgent[MCPOrchestratorInputSchema, OrchestratorOutputSchema](
+ BaseAgentConfig(
+ client=client,
+ model=config.openai_model,
+ history=history,
+ system_prompt_generator=SystemPromptGenerator(
+ background=[
+ "You are an MCP Orchestrator Agent, designed to chat with users and",
+ "determine the best way to handle their queries using the available tools.",
+ ],
+ steps=[
+ "1. Use the reasoning field to determine if one or more successive tool calls could be used to handle the user's query.",
+ "2. If so, choose the appropriate tool(s) one at a time and extract all necessary parameters from the query.",
+ "3. If a single tool can not be used to handle the user's query, think about how to break down the query into "
+ "smaller tasks and route them to the appropriate tool(s).",
+ "4. If no sequence of tools could be used, or if you are finished processing the user's query, provide a final "
+ "response to the user.",
+ ],
+ output_instructions=[
+ "1. Always provide a detailed explanation of your decision-making process in the 'reasoning' field.",
+ "2. Choose exactly one action schema (either a tool input or FinalResponseSchema).",
+ "3. Ensure all required parameters for the chosen tool are properly extracted and validated.",
+ "4. Maintain a professional and helpful tone in all responses.",
+ "5. Break down complex queries into sequential tool calls before giving the final answer via `FinalResponseSchema`.",
+ ],
+ ),
+ )
+ )
+ console.print("[green]Successfully created orchestrator agent.[/green]")
+
+ # Interactive chat loop
+ console.print(
+ "[bold green]MCP Agent Interactive Chat (STDIO mode - Async). Type 'exit' or 'quit' to leave.[/bold green]"
+ )
+ while True:
+ query = console.input("[bold yellow]You:[/bold yellow] ").strip()
+ if query.lower() in {"/exit", "/quit"}:
+ console.print("[bold red]Exiting chat. Goodbye![/bold red]")
+ break
+ if not query:
+ continue # Ignore empty input
+
+ try:
+ # Initial run with user query
+ orchestrator_output = orchestrator_agent.run(MCPOrchestratorInputSchema(query=query))
+ action_instance = orchestrator_output.action
+ reasoning = orchestrator_output.reasoning
+ console.print(f"[cyan]Orchestrator reasoning:[/cyan] {reasoning}")
+
+ # Keep executing until we get a final response
+ while not isinstance(action_instance, FinalResponseSchema):
+ schema_type = type(action_instance)
+ ToolClass = tool_schema_to_class_map.get(schema_type)
+ if not ToolClass:
+ raise ValueError(f"Unknown schema type '" f"{schema_type.__name__}" f"' returned by orchestrator")
+
+ tool_name = ToolClass.mcp_tool_name
+ console.print(f"[blue]Executing tool:[/blue] {tool_name}")
+ console.print(f"[dim]Parameters:[/dim] " f"{action_instance.model_dump()}")
+
+ # Execute the MCP tool using the session directly to avoid event loop conflicts
+ arguments = action_instance.model_dump(exclude={"tool_name"}, exclude_none=True)
+ tool_result = await session.call_tool(name=tool_name, arguments=arguments)
+
+ # Process the result similar to how the factory does it
+ if hasattr(tool_result, "content"):
+ actual_result_content = tool_result.content
+ elif isinstance(tool_result, dict) and "content" in tool_result:
+ actual_result_content = tool_result["content"]
+ else:
+ actual_result_content = tool_result
+
+ # Create output schema instance
+ OutputSchema = type(
+ f"{tool_name}OutputSchema", (MCPToolOutputSchema,), {"__doc__": f"Output schema for {tool_name}"}
+ )
+ tool_output = OutputSchema(result=actual_result_content)
+ console.print(f"[bold green]Result:[/bold green] {tool_output.result}")
+
+ # Add tool result to agent history
+ result_message = MCPOrchestratorInputSchema(
+ query=(f"Tool {tool_name} executed with result: " f"{tool_output.result}")
+ )
+ orchestrator_agent.history.add_message("system", result_message)
+
+ # Run the agent again without parameters to continue the flow
+ orchestrator_output = orchestrator_agent.run()
+ action_instance = orchestrator_output.action
+ reasoning = orchestrator_output.reasoning
+ console.print(f"[cyan]Orchestrator reasoning:[/cyan] {reasoning}")
+
+ # Final response from the agent
+ console.print(f"[bold blue]Agent:[/bold blue] {action_instance.response_text}")
+
+ except Exception as e:
+ console.print(f"[red]Error processing query:[/red] {str(e)}")
+ console.print_exception()
+
+
+if __name__ == "__main__":
+ asyncio.run(main())