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.

MCP(...) accepts three equivalent construction forms — see Three equivalent forms.

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.

graph LR
    subgraph "MCP Tool Loading"
        Config[📋 JSON/TOML Config] --> Load[🔄 load_mcp_tools()]
        Load --> Tools[🧰 MCP Tools]
        Tools --> Agent[🤖 Agent]
    end

    classDef config fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff  
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Config config
    class Load process
    class Tools,Agent output

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

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:

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

Related