Skip to main content
MCPAgent is the enterprise-focused Logicore agent for large tool ecosystems. It extends the base Agent class with MCP server integration, named session lifecycle management, optional deferred tool loading, and session lifecycle callbacks. 
from logicore.agents.agent_mcp import MCPAgent

​
Constructor

MCPAgent(
    provider: str | LLMProvider = "ollama",
    model: str = None,
    api_key: str = None,
    endpoint: str = None,
    system_message: str = "You are a helpful AI assistant with access to various tools.",
    debug: bool = False,
    telemetry: bool = False,
    memory: bool = False,
    max_iterations: int = 40,
    session_timeout: int = 3600,
    mcp_config_path: str = None,
    mcp_config: dict = None,
    deferred_tools: bool = False,
    tool_threshold: int = 15,
    skills: list = None,
    workspace_root: str = None,
)

​
Parameters

​
provider
str or LLMProvider
default:"ollama"
LLM backend. Pass a string shorthand ("ollama", "openai", "groq", "gemini", "azure") or a pre-constructed LLMProvider instance.
​
model
str
default:"None"
Model name to use with the selected provider (e.g. "qwen2:7b", "gpt-4o-mini"). Falls back to the provider default when None.
​
api_key
str
default:"None"
API key for cloud providers. Required when provider is "openai", "groq", "gemini", or "azure". Missing credentials will cause requests to fail.
​
endpoint
str
default:"None"
Custom base URL. Required for Azure deployments; optional for self-hosted OpenAI-compatible endpoints.
​
system_message
str
System prompt applied to every new session.
​
debug
bool
default:"false"
Print verbose internal logs covering MCP connection status, tool registration, deferred mode decisions, and session events.
​
telemetry
bool
default:"false"
Enable telemetry tracking via TelemetryTracker.
​
memory
bool
default:"false"
Enable memory / context middleware via AgentrySimpleMem.
​
max_iterations
int
default:"40"
Maximum number of tool-call iterations per chat() call before the loop exits. Prevents runaway execution.
​
session_timeout
int
default:"3600"
Seconds of inactivity after which a session is considered stale. Used by cleanup_stale_sessions(). Defaults to one hour.
​
mcp_config_path
str
default:"None"
Path to an mcp.json file on disk. Passed directly to MCPClientManager. Provide either this or mcp_config, not both.
​
mcp_config
dict
default:"None"
In-memory MCP server config dict (same schema as mcp.json). Takes precedence over mcp_config_path when both are given.
​
deferred_tools
bool
default:"false"
Explicitly enable deferred tool loading regardless of tool count. When True, the model starts with only tool_search_regex and tools are loaded on demand.
​
tool_threshold
int
default:"15"
Auto-enable deferred mode when total tools (default + MCP) reaches this number. Prevents context bloat in large tool catalogs.
​
skills
list
default:"None"
List of skill names or Skill objects to load into the agent at startup.
​
workspace_root
str
default:"None"
Root directory for workspace-based skill discovery.

​
chat()

await agent.chat(
    user_input: str,
    session_id: str = "default",
    create_if_missing: bool = True,
    stream: bool = False,
    streaming_funct: callable = None,
    generate_walkthrough: bool = False,
    **kwargs,
) -> str | None
Process a message within a named session context. MCP servers are lazily initialized on the first call if init_mcp_servers() has not been called explicitly.
​
user_input
str
required
The user’s message to process.
​
session_id
str
default:"default"
Identifies the session context. Each session has isolated conversation history.
​
create_if_missing
bool
default:"true"
Automatically create the session if it does not exist. Set to False to require explicit create_session() calls.
​
stream
bool
default:"false"
Stream response tokens as they are generated rather than returning the complete response at the end.
​
streaming_funct
callable
default:"None"
Callback receiving each token string during streaming. Only used when stream=True.
​
generate_walkthrough
bool
default:"false"
Append a concise run summary to the response. Useful for audits and debugging.
Returns str | None — the final assistant message, or None if the iteration limit was reached without a final response.
A None return does not raise an exception. Handle it explicitly in production callers with retry or fallback logic.

​
Session management methods

​
create_session()

agent.create_session(
    session_id: str,
    system_message: str = None,
    metadata: dict = None,
) -> AgentSession
Create a named session with isolated conversation history. Fires the on_session_created callback if set.

​
destroy_session()

agent.destroy_session(session_id: str) -> bool
Delete a session and free its resources. Returns True on success, False if the session was not found. Fires on_session_destroyed if set.

​
list_sessions()

agent.list_sessions() -> list[dict]
Return a summary list for all active sessions. Each entry includes session_id, message_count, created_at, last_activity, and metadata.

​
cleanup_stale_sessions()

agent.cleanup_stale_sessions() -> int
Destroy every session whose last_activity exceeds session_timeout. Returns the number of sessions removed.

​
set_session_callbacks()

agent.set_session_callbacks(
    on_session_created: callable = None,
    on_session_destroyed: callable = None,
)
Register callbacks for session lifecycle events. Both callbacks receive the session_id string.

​
Tool management methods

​
init_mcp_servers()

await agent.init_mcp_servers()
Connect to all servers declared in mcp_config_path / mcp_config, discover their tools, and decide whether deferred mode should activate. Idempotent — safe to call multiple times.

​
register_tool_deferred()

agent.register_tool_deferred(schema: dict, preload: bool = False)
Add a tool schema directly to the deferred registry. When preload=True the tool is also added to _loaded_tools so it is available immediately without a search step.

​
preload_tools()

agent.preload_tools(tool_names: list[str])
Mark specific tools in the registry as loaded so they appear in the model’s tool list without requiring a tool_search_regex call. Useful for high-frequency tools.

​
get_registry_stats()

agent.get_registry_stats() -> dict
Return a snapshot of the tool registry: 
{
    "total_registered": 42,
    "loaded": 7,
    "deferred": 35,
    "deferred_mode": True,
    "auto_deferred": True,
    "threshold": 15,
    "tool_names": ["read_file", "write_file", ...]
}

​
Examples

from logicore.agents.agent_mcp import MCPAgent

agent = MCPAgent(provider="ollama", model="qwen2:7b")
response = await agent.chat("Summarize Python async in simple terms")
print(response)

​
Inheritance from Agent

MCPAgent inherits the following capabilities from the base Agent class without modification:
  • Internal tool execution (local Python functions)
  • register_tool_from_function() — overridden to also populate the deferred registry when deferred mode is active
  • Memory and telemetry middleware
  • Provider abstraction (LLMProvider)
  • get_session() / AgentSession base session model

Build docs developers (and LLMs) love

Get started for freeTalk to us