Skip to main content
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

ParameterTypeDefaultDescription
namesList[str]NoneSpecific config names to load (None = all enabled)
configsList[MCPConfig]NoneOptional injected configs from wrapper TOML loader
prefix_toolsboolTrueNamespace 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:
ScenarioBeforeAfter
Load filesystem + github, both expose searchSilent collision — one shadows the otherfilesystem_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

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.
Use specific server names rather than loading everything. A file processing agent only needs ["filesystem"], while a development agent might need ["filesystem", "github", "postgres"].
The loader silently skips disabled or missing configs. Always check that your expected servers are enabled with praisonai mcp list.
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.

MCP Tool Filtering

Restrict which MCP tools an agent can see and call

MCP CLI

Configure and manage MCP servers from the command line