mcp.agents.basic_mcp_agent¶

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

Examples

Creating and using an MCP agent:

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¶

BasicMCPAgent

An agent with MCP (Model Context Protocol) capabilities.

Functions¶

create_filesystem_agent(→ BasicMCPAgent)

Create an agent with filesystem MCP server.

create_github_agent(→ BasicMCPAgent)

Create an agent with GitHub MCP server.

create_multi_mcp_agent(→ BasicMCPAgent)

Create an agent with multiple MCP servers.

Module Contents¶

class mcp.agents.basic_mcp_agent.BasicMCPAgent(/, **data: Any)¶

Bases: haive.mcp.mixins.mcp_mixin.MCPMixin, 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.

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

Examples

Basic MCP agent setup:

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:

# Using convenience factory
agent = MCPAgent.create_with_mcp_servers(
    engine=engine,
    server_configs={
        "filesystem": {
            "transport": "stdio",
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem"]
        }
    }
)
__repr__() → str¶

String representation of the agent.

async call_tool_with_retry(tool_name: str, arguments: dict[str, Any], max_retries: int = 3) → Any¶

Call an MCP tool with retry logic.

Parameters:

  • tool_name – Name of the tool

  • arguments – Tool arguments

  • max_retries – Maximum retry attempts

Returns:

Tool result

classmethod create_with_mcp_servers(engine: Any, server_configs: dict[str, dict[str, Any]], name: str | None = None, **kwargs) → Self¶

Create an MCP agent with server configurations.

Convenience factory method that simplifies agent creation by accepting server configurations as dictionaries instead of MCPServerConfig objects.

Parameters:

  • engine – The LLM engine configuration (AugLLMConfig)

  • server_configs – Dictionary mapping server names to their configurations. Each config should include transport, command/url, and optional settings.

  • name – Optional agent name (defaults to “mcp_agent”)

  • **kwargs – Additional agent configuration parameters

Returns:

Configured agent instance ready for initialization

Return type:

MCPAgent

Raises:

ValueError – If server configurations are invalid

Examples

Creating an agent with multiple servers:

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()
async discover_tools_by_capability(capability: str) → list[Any]¶

Discover tools that provide a specific capability.

Parameters:

capability – The capability to search for

Returns:

List of tools that provide the capability

get_available_capabilities() → list[str]¶

Get all available capabilities from connected MCP servers.

async setup() → None¶

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.

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.

mcp_config: haive.mcp.config.MCPConfig | None = None¶
property tool_count: int¶

Get total number of available tools including MCP tools.

mcp.agents.basic_mcp_agent.create_filesystem_agent(engine: Any) → BasicMCPAgent¶

Create an agent with filesystem MCP server.

mcp.agents.basic_mcp_agent.create_github_agent(engine: Any, github_token: str) → BasicMCPAgent¶

Create an agent with GitHub MCP server.

mcp.agents.basic_mcp_agent.create_multi_mcp_agent(engine: Any, github_token: str | None = None) → BasicMCPAgent¶

Create an agent with multiple MCP servers.