MCPAgent and MCPClientManager. Together they handle server connections, tool discovery, schema conversion, and call routing, so your application code stays focused on the chat interface.
When to use MCP
For small projects with a handful of Python functions,Agent or SmartAgent is sufficient. Reach for MCP when you need:
- Shared tool servers consumed by multiple teams or services
- Enterprise governance — centralized control over which tools are exposed and to whom
- Large tool ecosystems that would exceed prompt or context budgets if loaded all at once
- Standard protocol interoperability with non-Python tooling or third-party MCP servers
Core components
MCPAgent
The agent layer. Extends
Agent with MCP server integration, session lifecycle utilities, and optional deferred tool loading.MCPClientManager
Manages stdio connections to every server in
mcp.json, discovers their tools, and routes calls to the right server.Dynamic tool loading
When the total tool count exceeds a configurable threshold,
MCPAgent switches to deferred mode and exposes tools on demand.Examples
Complete working examples covering small and large toolsets, session management, and lazy initialization.
Lifecycle summary
Create MCPAgent
Instantiate
MCPAgent with your provider, model, and an optional mcp_config_path or mcp_config dict.Initialize MCP servers
Call
await agent.init_mcp_servers(), or skip it — the first chat() call triggers lazy initialization automatically.Tools are merged
Internal default tools and all discovered MCP tools are merged into a unified tool list. If the total exceeds
tool_threshold (default 15), deferred mode activates automatically.Run the chat loop
Call
await agent.chat(user_input). The agent executes tool calls, routing local tools to the built-in executor and MCP tools to the correct server session.What MCP adds beyond normal tools
| Capability | Agent / SmartAgent | MCPAgent |
|---|---|---|
| Local Python tool execution | Yes | Yes (inherited) |
| External tool server connections | No | Yes |
Tool discovery via mcp.json | No | Yes |
| Session lifecycle management | Basic | Full (create, destroy, cleanup) |
| Deferred / dynamic tool loading | No | Yes |
| Session metadata and callbacks | No | Yes |