mcp.agents.basic_mcp_agent ========================== .. py:module:: mcp.agents.basic_mcp_agent .. autoapi-nested-parse:: Basic MCP-enabled agent implementation that demonstrates integration with haive-agents. This module provides a ready-to-use agent class that combines SimpleAgent capabilities with MCP (Model Context Protocol) support. The BasicMCPAgent class offers seamless integration with MCP servers, automatic tool discovery, and convenient factory methods. The agent supports: - Multiple MCP server connections - Automatic tool registration - Capability-based tool discovery - Retry logic for failed operations - Convenient factory methods for common patterns Classes: BasicMCPAgent: Main agent class with MCP capabilities Functions: create_filesystem_agent: Factory for filesystem MCP agent create_github_agent: Factory for GitHub MCP agent create_multi_mcp_agent: Factory for multi-server MCP agent .. rubric:: Examples Creating and using an MCP agent: .. code-block:: python from haive.mcp.agents import BasicMCPAgent from haive.mcp.config import MCPConfig, MCPServerConfig from haive import agents # Method 1: Direct instantiation agent = BasicMCPAgent( engine=engine, mcp_config=MCPConfig( enabled=True, servers={ "fs": MCPServerConfig( name="fs", transport="stdio", command="npx", args=["-y", "@modelcontextprotocol/server-filesystem"] ) } ) ) # Method 2: Using convenience factory agent = BasicMCPAgent.create_with_mcp_servers( engine=engine, server_configs={ "filesystem": { "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] } } ) # Initialize and use await agent.setup() result = await agent.arun({"messages": [...]}) Classes ------- .. autoapisummary:: mcp.agents.basic_mcp_agent.BasicMCPAgent Functions --------- .. autoapisummary:: mcp.agents.basic_mcp_agent.create_filesystem_agent mcp.agents.basic_mcp_agent.create_github_agent mcp.agents.basic_mcp_agent.create_multi_mcp_agent Module Contents --------------- .. py:class:: BasicMCPAgent(/, **data: Any) Bases: :py:obj:`haive.mcp.mixins.mcp_mixin.MCPMixin`, :py:obj:`haive.agents.simple.SimpleAgent` An agent with MCP (Model Context Protocol) capabilities. This agent extends SimpleAgent with the ability to connect to and use MCP servers for additional tools and resources. It provides seamless integration with MCP servers while maintaining all SimpleAgent functionality. .. attribute:: mcp_config Optional MCP configuration for connecting to MCP servers The agent automatically: - Connects to configured MCP servers - Discovers available tools and resources - Registers MCP tools with the agent's tool system - Handles server health monitoring and reconnection - Provides unified tool access across all servers .. rubric:: Examples Basic MCP agent setup: .. code-block:: python from haive.mcp.agents import MCPAgent from haive.mcp.config import MCPConfig, MCPServerConfig # Configure MCP servers mcp_config = MCPConfig( enabled=True, servers={ "filesystem": MCPServerConfig( name="filesystem", transport="stdio", command="npx", args=["-y", "@modelcontextprotocol/server-filesystem"], capabilities=["file_read", "file_write", "directory_list"] ), "github": MCPServerConfig( name="github", transport="stdio", command="npx", args=["-y", "@modelcontextprotocol/server-github"], env={"GITHUB_TOKEN": "your_token"}, capabilities=["repo_access", "issue_management"] ) } ) # Create agent with MCP agent = MCPAgent( engine=my_engine, mcp_config=mcp_config, name="mcp_assistant" ) # Initialize agent and MCP connections await agent.setup() # Tools from MCP servers are automatically available result = await agent.arun({ "messages": [{"role": "user", "content": "List files in current directory"}] }) Factory method usage: .. code-block:: python # Using convenience factory agent = MCPAgent.create_with_mcp_servers( engine=engine, server_configs={ "filesystem": { "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] } } ) .. py:method:: __repr__() -> str String representation of the agent. .. py:method:: call_tool_with_retry(tool_name: str, arguments: dict[str, Any], max_retries: int = 3) -> Any :async: Call an MCP tool with retry logic. :param tool_name: Name of the tool :param arguments: Tool arguments :param max_retries: Maximum retry attempts :returns: Tool result .. py:method:: create_with_mcp_servers(engine: Any, server_configs: dict[str, dict[str, Any]], name: str | None = None, **kwargs) -> Self :classmethod: Create an MCP agent with server configurations. Convenience factory method that simplifies agent creation by accepting server configurations as dictionaries instead of MCPServerConfig objects. :param engine: The LLM engine configuration (AugLLMConfig) :param server_configs: Dictionary mapping server names to their configurations. Each config should include transport, command/url, and optional settings. :param name: Optional agent name (defaults to "mcp_agent") :param \*\*kwargs: Additional agent configuration parameters :returns: Configured agent instance ready for initialization :rtype: MCPAgent :raises ValueError: If server configurations are invalid .. rubric:: Examples Creating an agent with multiple servers: .. code-block:: python agent = MCPAgent.create_with_mcp_servers( engine=engine, server_configs={ "filesystem": { "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"], "capabilities": ["file_read", "file_write"] }, "github": { "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": {"GITHUB_TOKEN": token} } }, name="multi_mcp_agent" ) await agent.setup() .. py:method:: discover_tools_by_capability(capability: str) -> list[Any] :async: Discover tools that provide a specific capability. :param capability: The capability to search for :returns: List of tools that provide the capability .. py:method:: get_available_capabilities() -> list[str] Get all available capabilities from connected MCP servers. .. py:method:: setup() -> None :async: Setup agent including MCP initialization. This async setup method should be called after agent creation to initialize MCP connections and discover available tools. The method handles: - MCP server connections (if not lazy_init) - Tool discovery and registration - Resource loading - Health monitoring setup .. note:: This method is required for MCP functionality. Call it after creating the agent but before using it. .. py:method:: setup_agent() -> None Override setup_agent to configure MCP after base setup. This method extends the base SimpleAgent setup to include MCP configuration. It ensures that MCP is initialized after the base agent setup is complete. .. py:attribute:: mcp_config :type: haive.mcp.config.MCPConfig | None :value: None .. py:property:: tool_count :type: int Get total number of available tools including MCP tools. .. py:function:: create_filesystem_agent(engine: Any) -> BasicMCPAgent Create an agent with filesystem MCP server. .. py:function:: create_github_agent(engine: Any, github_token: str) -> BasicMCPAgent Create an agent with GitHub MCP server. .. py:function:: create_multi_mcp_agent(engine: Any, github_token: str | None = None) -> BasicMCPAgent Create an agent with multiple MCP servers.