Load MCP Tools

Wire configured MCP servers into agents with one line

Load MCP tools from your configured servers with a single function call, following the agent-centric design principles.

from praisonaiagents import Agent
from praisonaiagents.mcp import load_mcp_tools

agent = Agent(name="assistant", tools=load_mcp_tools())
agent.start("List files in /tmp")

The user asks a question; the agent calls MCP tools loaded from your JSON/TOML server config.

Quick Start

1. Load All Enabled Servers

   Wire all enabled MCP servers from your configuration:

   from praisonaiagents import Agent
   from praisonaiagents.mcp import load_mcp_tools
   
   agent = Agent(name="assistant", tools=load_mcp_tools())
   agent.start("List files in /tmp")
   
2. Load Specific Servers

   Load only the servers you need by name:

   from praisonaiagents import Agent
   from praisonaiagents.mcp import load_mcp_tools
   
   tools = load_mcp_tools(["filesystem", "github"])
   agent = Agent(name="coder", tools=tools)
   agent.start("Read the README file and create a GitHub issue")
   

---

How It Works

The loader bridges configuration and agent setup by:

1. Reading configs from ~/.praisonai/mcp/ directory
2. Filtering by enabled status and optional name selection
3. Converting each config to an MCP client instance
4. Returning ready-to-use tool instances

---

Configuration Options

Parameter	Type	Default	Description
names	List[str]	None	Specific config names to load (None = all enabled)
configs	List[MCPConfig]	None	Optional injected configs from wrapper TOML loader
prefix_tools	bool	True	Namespace each server’s tools as <server_name>_<tool_name> when more than one server loads. Single-server loads keep bare names for backward compatibility. Set False to keep bare names always (collisions possible).

---

Multi-Server Namespacing

Loading several servers together auto-prefixes each server’s tools so overlapping names never collide.

from praisonaiagents import Agent
from praisonaiagents.mcp import load_mcp_tools

agent = Agent(
    name="engineer",
    instructions="You have filesystem and GitHub tools.",
    tools=load_mcp_tools(names=["filesystem", "github"]),
)

# The model sees `filesystem_search` and `github_search` — no collision.
agent.start("Find the auth module in the repo and list recent GitHub issues about it.")

Dispatch still routes to each server’s original tool name — only the name the model sees changes.

Both servers expose a search tool, yet the agent sees two distinct, callable names:

Scenario	Before	After
Load filesystem + github, both expose search	Silent collision — one shadows the other	filesystem_search, github_search — both callable

Single-server loads keep bare names. load_mcp_tools(["filesystem"]) still emits read_file, not filesystem_read_file.

Server names are sanitized to [0-9A-Za-z_] before prefixing. If two servers sanitize to the same prefix (e.g. "file-system" and "file system" both become file_system), the loader raises ValueError at load time instead of silently shadowing.

---

Prefixing a Single Server

MCP.with_tool_prefix() namespaces one server’s tools yourself when you build MCP instances directly.

from praisonaiagents import Agent
from praisonaiagents.mcp import MCP

fs = MCP("npx -y @modelcontextprotocol/server-filesystem /tmp").with_tool_prefix("fs")
gh = MCP("npx -y @modelcontextprotocol/server-github").with_tool_prefix("gh")

agent = Agent(
    name="engineer",
    instructions="Work across filesystem and GitHub.",
    tools=[fs, gh],
)
# Model sees `fs_read_file`, `gh_search_issues`, etc.

• The prefix is sanitized to [0-9A-Za-z_]; an empty result raises ValueError.
• Returns self, so calls chain fluently.
• Dispatch still routes to the original server-side tool names.

---

Filtering a Single Server

MCP.apply_tool_filters() restricts which tools an instance exposes.

from praisonaiagents import Agent
from praisonaiagents.mcp import MCP

fs = MCP("npx -y @modelcontextprotocol/server-filesystem /tmp") \
    .apply_tool_filters(disabled_tools=["delete_file"])

agent = Agent(name="safe-editor", tools=[fs])

allowed_tools wins over disabled_tools when both are supplied. Returns self for chaining, so it composes with with_tool_prefix().

---

Common Patterns

Load All Enabled Servers

The simplest approach - load everything that’s enabled:

from praisonaiagents import Agent
from praisonaiagents.mcp import load_mcp_tools

agent = Agent(
    name="multi-tool-assistant",
    instructions="Help with various tasks using available tools",
    tools=load_mcp_tools()
)

Load Specific Servers

Target specific capabilities for focused agents:

from praisonaiagents import Agent
from praisonaiagents.mcp import load_mcp_tools

# File operations only
file_agent = Agent(
    name="file-assistant", 
    tools=load_mcp_tools(["filesystem"])
)

# Development tools
dev_agent = Agent(
    name="dev-assistant",
    tools=load_mcp_tools(["filesystem", "github", "postgres"])
)

Inject Configs from TOML

Advanced usage with wrapper TOML loading:

from praisonaiagents import Agent
from praisonaiagents.mcp import load_mcp_tools
from praisonai.cli.configuration import get_config_loader

# Load from wrapper TOML config
loader = get_config_loader()
config = loader.load()
toml_configs = [MCPConfig(...) for server in config.mcp.servers]

# Use injected configs
tools = load_mcp_tools(configs=toml_configs)
agent = Agent(name="toml-configured", tools=tools)

---

Best Practices

Configure Once, Use Everywhere

Set up your MCP servers once using praisonai mcp create, then any agent can pick them up automatically via load_mcp_tools(). This follows the “configure once, use everywhere” principle.

Filter by Purpose

Use specific server names rather than loading everything. A file processing agent only needs ["filesystem"], while a development agent might need ["filesystem", "github", "postgres"].

Handle Missing Configs Gracefully

The loader silently skips disabled or missing configs. Always check that your expected servers are enabled with praisonai mcp list.

Rely on Auto-Prefixing for Collisions

Multi-server loads auto-namespace tools as <server_name>_<tool_name>, so overlapping names (like two search tools) both stay callable. If two server names sanitize to the same prefix, the loader raises a clear ValueError at load time — never a silent shadow. Set prefix_tools=False only when you need bare names and accept possible collisions.

---

Related

MCP Tool Filtering

Restrict which MCP tools an agent can see and call

MCP CLI

Configure and manage MCP servers from the command line