> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<Steps>
  <Step title="Load All Enabled Servers">
    Wire all enabled MCP servers from your configuration:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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")
    ```
  </Step>

  <Step title="Load Specific Servers">
    Load only the servers you need by name:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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")
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Loader
    participant Config
    participant MCP
    
    User->>Agent: Request with MCP tools
    Agent->>Loader: load_mcp_tools()
    Loader->>Config: Read ~/.praisonai/mcp/
    Config-->>Loader: Enabled configs
    Loader->>MCP: Create MCP instances
    MCP-->>Loader: Ready tools
    Loader-->>Agent: List of MCP clients
    Agent-->>User: Response with tool results
```

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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Multi-Server Namespacing"
        FS[📁 filesystem server] --> FSP[🏷️ filesystem_search]
        GH[🐙 github server] --> GHP[🏷️ github_search]
        FSP --> Agent[🤖 Agent]
        GHP --> Agent
    end

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

    class FS,GH server
    class FSP,GHP prefixed
    class Agent output
```

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 |

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

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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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"]`.
  </Accordion>

  <Accordion title="Handle Missing Configs Gracefully">
    The loader silently skips disabled or missing configs. Always check that your expected servers are enabled with `praisonai mcp list`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="MCP Tool Filtering" icon="filter" href="/docs/features/mcp-tool-filtering">
    Restrict which MCP tools an agent can see and call
  </Card>

  <Card title="MCP CLI" icon="terminal" href="/docs/cli/mcp">
    Configure and manage MCP servers from the command line
  </Card>
</CardGroup>