haive.mcp.agents.intelligent_mcp_agent¶

Intelligent MCP Agent for dynamic server discovery and management.

This module provides an advanced agent that can dynamically discover, recommend, install, and manage MCP servers based on user needs. It includes HITL (Human-In-The-Loop) approval workflows and intelligent capability matching.

The agent supports:

Dynamic server discovery from 992+ server database
Intelligent capability matching
HITL approval workflows
Hot-reload and dynamic tool refresh
Server health monitoring
Automatic retry and recovery

Classes:

IntelligentMCPAgent: Advanced agent for dynamic MCP management HITLApprovalRequest: Request structure for human approval ServerRecommendation: Recommendation for MCP server installation

Example

Dynamic server discovery and installation:

from haive.mcp.agents import IntelligentMCPAgent

from haive import core from haive import agents

# Create intelligent agent agent = IntelligentMCPAgent(

engine=engine, auto_discover=True, require_approval=True

)

# Agent discovers need for database capabilities result = await agent.arun({

“messages”: [{
“role”: “user”, “content”: “I need to analyze data from PostgreSQL”

}]

})

# Agent recommends postgres MCP server and asks for approval # After approval, installs and configures automatically

Classes¶

`ApprovalStatus`	Status of HITL approval request.
`HITLApprovalRequest`	Request for human-in-the-loop approval.
`IntelligentMCPAgent`	Intelligent agent for dynamic MCP server discovery and management.
`ServerRecommendation`	Recommendation for MCP server installation.

Functions¶

`create_agent_with_callback`(engine, approval_callback)	Create an agent with custom approval callback.
`create_auto_discovering_agent`(engine[, require_approval])	Create an agent that automatically discovers and installs MCP servers.
`create_manual_discovery_agent`(engine)	Create an agent with manual discovery tools but no auto-discovery.

Module Contents¶

class haive.mcp.agents.intelligent_mcp_agent.ApprovalStatus¶

Bases: str, enum.Enum

Status of HITL approval request.

Initialize self. See help(type(self)) for accurate signature.

class haive.mcp.agents.intelligent_mcp_agent.HITLApprovalRequest(/, **data)¶

Bases: pydantic.BaseModel

Request for human-in-the-loop approval.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

class haive.mcp.agents.intelligent_mcp_agent.IntelligentMCPAgent(**kwargs)¶

Bases: haive.agents.react.ReactAgent

Intelligent agent for dynamic MCP server discovery and management.

This agent extends ReactAgent with intelligent MCP management capabilities, including dynamic server discovery, HITL approval workflows, and automatic configuration based on user needs.

mcp_manager¶: Dynamic MCP manager for server operations

doc_agent¶: Documentation agent for server discovery

auto_discover¶: Whether to automatically discover servers

require_approval¶: Whether to require HITL approval

approval_timeout¶: Timeout for approval requests in seconds

approval_callback¶: Custom approval callback function

capability_cache¶: Cache of discovered capabilities

recommendation_history¶: History of recommendations

Example

Basic intelligent agent setup:

agent = IntelligentMCPAgent(
    engine=engine,
    auto_discover=True,
    require_approval=True,
    approval_timeout=30.0
)

# Agent automatically discovers and recommends servers
result = await agent.arun({
    "messages": [{
        "role": "user",
        "content": "Help me search the web for Python tutorials"
    }]
})

# Agent detects need for web search, recommends brave-search server
# Waits for approval, then installs and uses it

Initialize intelligent MCP agent.

Sets up the agent with discovery tools and documentation access.

async approve_request(request_id)¶

Approve a pending request.

Parameters:: request_id (str) – ID of the request to approve
Returns:: True if request was found and approved
Return type:: bool

async arun(inputs)¶

Run the agent with intelligent MCP discovery.

Extends the base arun to add capability analysis and dynamic server installation based on user needs.

Parameters:: inputs (dict[str, Any]) – Agent inputs with messages
Returns:: Agent response after processing with dynamic MCP
Return type:: Any

get_pending_approvals()¶

Get list of pending approval requests.

Return type:: list[HITLApprovalRequest]

get_recommendation_history()¶

Get history of server recommendations.

Return type:: list[ServerRecommendation]

async reject_request(request_id)¶

Reject a pending request.

Parameters:: request_id (str) – ID of the request to reject
Returns:: True if request was found and rejected
Return type:: bool

async setup()¶

Setup the intelligent agent including documentation agent.

Return type:: None

class haive.mcp.agents.intelligent_mcp_agent.ServerRecommendation(/, **data)¶

Bases: pydantic.BaseModel

Recommendation for MCP server installation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

async haive.mcp.agents.intelligent_mcp_agent.create_agent_with_callback(engine, approval_callback)¶

Create an agent with custom approval callback.

Parameters:

engine (haive.core.engine.aug_llm.AugLLMConfig) – LLM engine configuration
approval_callback (collections.abc.Callable[[HITLApprovalRequest], bool]) – Custom function to handle approvals

Returns:

Configured IntelligentMCPAgent

Return type:

IntelligentMCPAgent

haive.mcp.agents.intelligent_mcp_agent.create_auto_discovering_agent(engine, require_approval=True)¶

Create an agent that automatically discovers and installs MCP servers.

Parameters:

engine (haive.core.engine.aug_llm.AugLLMConfig) – LLM engine configuration
require_approval (bool) – Whether to require HITL approval

Returns:

Configured IntelligentMCPAgent

Return type:

IntelligentMCPAgent

haive.mcp.agents.intelligent_mcp_agent.create_manual_discovery_agent(engine)¶

Create an agent with manual discovery tools but no auto-discovery.

Parameters:: engine (haive.core.engine.aug_llm.AugLLMConfig) – LLM engine configuration
Returns:: Configured IntelligentMCPAgent
Return type:: IntelligentMCPAgent