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

Attributes¶

logger

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`(→ IntelligentMCPAgent)	Create an agent with custom approval callback.
`create_auto_discovering_agent`(→ IntelligentMCPAgent)	Create an agent that automatically discovers and installs MCP servers.
`create_manual_discovery_agent`(→ IntelligentMCPAgent)	Create an agent with manual discovery tools but no auto-discovery.

Module Contents¶

class mcp.agents.intelligent_mcp_agent.ApprovalStatus¶

Bases: str, enum.Enum

Status of HITL approval request.

APPROVED = 'approved'¶

PENDING = 'pending'¶

REJECTED = 'rejected'¶

TIMEOUT = 'timeout'¶

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

Bases: pydantic.BaseModel

Request for human-in-the-loop approval.

approval_callback: str | None = None¶

context: dict[str, Any] = None¶

recommendation: ServerRecommendation = None¶

request_id: str = None¶

request_type: str = None¶

response_deadline: datetime.datetime | None = None¶

status: ApprovalStatus = None¶

timestamp: datetime.datetime = None¶

class 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

async approve_request(request_id: str) → bool¶

Approve a pending request.

Parameters:: request_id – ID of the request to approve
Returns:: True if request was found and approved

async arun(inputs: dict[str, Any]) → Any¶

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 – Agent inputs with messages
Returns:: Agent response after processing with dynamic MCP

get_pending_approvals() → list[HITLApprovalRequest]¶: Get list of pending approval requests.

get_recommendation_history() → list[ServerRecommendation]¶: Get history of server recommendations.

async reject_request(request_id: str) → bool¶

Reject a pending request.

Parameters:: request_id – ID of the request to reject
Returns:: True if request was found and rejected

async setup() → None¶: Setup the intelligent agent including documentation agent.

approval_callback: collections.abc.Callable | None = None¶

approval_timeout: float = None¶

auto_discover: bool = None¶

capability_cache: dict[str, list[str]] = None¶

doc_agent: Any | None = None¶

mcp_manager: haive.mcp.manager.MCPManager = None¶

pending_approvals: dict[str, HITLApprovalRequest] = None¶

recommendation_history: list[ServerRecommendation] = None¶

require_approval: bool = None¶

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

Bases: pydantic.BaseModel

Recommendation for MCP server installation.

alternative_servers: list[str] = None¶

capabilities: list[str] = None¶

confidence: float = None¶

config: haive.mcp.config.MCPServerConfig = None¶

reason: str = None¶

server_name: str = None¶

async mcp.agents.intelligent_mcp_agent.create_agent_with_callback(engine: haive.core.engine.aug_llm.AugLLMConfig, approval_callback: collections.abc.Callable[[HITLApprovalRequest], bool]) → IntelligentMCPAgent¶

Create an agent with custom approval callback.

Parameters:

engine – LLM engine configuration
approval_callback – Custom function to handle approvals

Returns:

Configured IntelligentMCPAgent

mcp.agents.intelligent_mcp_agent.create_auto_discovering_agent(engine: haive.core.engine.aug_llm.AugLLMConfig, require_approval: bool = True) → IntelligentMCPAgent¶

Create an agent that automatically discovers and installs MCP servers.

Parameters:

engine – LLM engine configuration
require_approval – Whether to require HITL approval

Returns:

Configured IntelligentMCPAgent

mcp.agents.intelligent_mcp_agent.create_manual_discovery_agent(engine: haive.core.engine.aug_llm.AugLLMConfig) → IntelligentMCPAgent¶

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

Parameters:: engine – LLM engine configuration
Returns:: Configured IntelligentMCPAgent

mcp.agents.intelligent_mcp_agent.logger¶