MCP Integration

MCP (Model Context Protocol) lets agents connect to external tool servers, instantly adding file system access, database queries, API integrations, and more.

from praisonaiagents import Agent, MCP

agent = Agent(
    name="FileAgent",
    instructions="You help users manage their files.",
    tools=MCP("npx -y @modelcontextprotocol/server-filesystem /tmp"),
)

agent.start("List all files in the /tmp directory.")

The user asks to inspect the filesystem; the agent calls MCP tools on the connected server.

MCP tool turns are treated specially: a mid-response network failure surfaces provider_outcome_unknown instead of silently re-running the tool. See Replay-Safe Retries.

Which MCP package do I need?

Three packages cover three MCP roles — connecting, light serving, and full hosting. This page covers the client layer. To serve your own agents, see the praisonai-mcp Package and The Three MCP Layers.

Quick Start

Connect to an MCP server

from praisonaiagents import Agent, MCP

agent = Agent(
    instructions="You can read and write files.",
    tools=MCP("npx -y @modelcontextprotocol/server-filesystem /tmp"),
)
agent.start("Create a file called notes.txt with the text 'Hello World'.")

SSE-based MCP server

from praisonaiagents import Agent, MCP

agent = Agent(
    instructions="You can search and retrieve web content.",
    tools=MCP("https://mcp.example.com/sse"),
)
agent.start("Search for the latest news about AI.")

Streamable HTTP MCP server

from praisonaiagents import Agent, MCP

# Streamable HTTP endpoint — auto-detected from the URL
agent = Agent(
    name="RemoteToolAgent",
    instructions="Use the remote MCP tools to answer the user.",
    tools=MCP(
        "https://api.example.com/mcp",
        headers={"Authorization": "Bearer YOUR_TOKEN"},
        timeout=60,
    ),
)

agent.start("List the tools you have and use them to check the current weather in London.")

Requires an up-to-date mcp package (pip install -U 'mcp'). The transport is powered by the official SDK’s streamablehttp_client.Pass the full endpoint URL your server exposes. Bare-host URLs are no longer rewritten to /mcp (see PraisonAI #3032).

Multiple MCP servers

from praisonaiagents import Agent, MCP

filesystem_tools = MCP("npx -y @modelcontextprotocol/server-filesystem /home/user")
database_tools = MCP("npx -y @modelcontextprotocol/server-sqlite /db/app.sqlite")

agent = Agent(
    instructions="You manage files and database records.",
    tools=[*filesystem_tools, *database_tools],
)
agent.start("Read the config file and update the database with its settings.")

Three equivalent forms

MCP(...) accepts the command in three equivalent forms — pick whichever reads best for your stdio server. Pick the form that matches how the command reaches your code.

Form 1 — single string
Form 2 — string + args
Form 3 — fully separated

from praisonaiagents import Agent, MCP

agent = Agent(
    name="FS",
    instructions="You manage files.",
    tools=MCP("npx -y @modelcontextprotocol/server-filesystem /tmp"),
)
agent.start("List files under /tmp")

from praisonaiagents import Agent, MCP

allowed_dirs = ["/tmp", "/var/logs"]

agent = Agent(
    name="FS",
    instructions="You manage files.",
    tools=MCP("npx -y @modelcontextprotocol/server-filesystem", args=allowed_dirs),
)
agent.start("List files in the allowed directories")

from praisonaiagents import Agent, MCP
import os

agent = Agent(
    name="GitHub",
    instructions="You manage GitHub issues.",
    tools=MCP(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-github"],
        env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ["GITHUB_TOKEN"]},
    ),
)
agent.start("List my open issues")

Merge rules

A multi-token string is split with shlex: the first token becomes the command, and the remaining tokens are prepended to any explicit args.

Input	Resulting `cmd`	Resulting `args`
`MCP("npx -y @pkg /tmp")`	`"npx"`	`["-y", "@pkg", "/tmp"]`
`MCP("npx -y @pkg", args=["/tmp"])`	`"npx"`	`["-y", "@pkg", "/tmp"]`
`MCP(command="npx", args=["-y", "@pkg", "/tmp"])`	`"npx"`	`["-y", "@pkg", "/tmp"]`
`MCP("/usr/bin/python", args=["app.py"])`	`"/usr/bin/python"`	`["app.py"]`
`MCP('"/opt/my app"', args=["run"])`	`"/opt/my app"`	`["run"]`

MCP("cmd multi word", args=[...]) requires PraisonAI containing #3943 (merged 2026-08-15). On older versions this form silently discovered 0 tools — upgrade with pip install -U praisonaiagents or switch to Form 1 or Form 3.

On Windows, shlex.split(..., posix=False) is used and surrounding double-quotes are stripped from each token. Quote paths that contain spaces: MCP('"C:\\Program Files\\node\\npx.cmd" -y @pkg').

How It Works

Phase	What happens
1. Connect	MCP client connects to the server on first use
2. Discover	Server reports its available tools
3. Execute	Agent calls tools via the MCP protocol
4. Return	Results flow back through the MCP client to the agent

For string forms, the command is parsed with shlex before the server spawns.

MCP Server Types

Remote Streamable HTTP servers connect through the official MCP SDK client.

Common Patterns

Pattern 1 — File management agent

from praisonaiagents import Agent, MCP

agent = Agent(
    name="FileManager",
    instructions="You help users organize and manage their files efficiently.",
    tools=MCP("npx -y @modelcontextprotocol/server-filesystem /home/user/documents"),
)
response = agent.start("Find all PDF files and create a summary list.")
print(response)

Pattern 2 — Database agent

from praisonaiagents import Agent, MCP

agent = Agent(
    name="DBAgent",
    instructions="You query and analyze database records.",
    tools=MCP("npx -y @modelcontextprotocol/server-sqlite /path/to/database.sqlite"),
)
agent.start("Show me all users who signed up in the last 30 days.")

Pattern 3 — GitHub integration

from praisonaiagents import Agent, MCP
import os

agent = Agent(
    name="GitHubAgent",
    instructions="You help manage GitHub repositories and issues.",
    tools=MCP(
        "npx -y @modelcontextprotocol/server-github",
        env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ["GITHUB_TOKEN"]},
    ),
)
agent.start("List the 5 most recent open issues in my repository.")

Best Practices

Use official MCP servers

Start with the official @modelcontextprotocol npm packages for common integrations (filesystem, SQLite, GitHub, etc.). They’re well-tested and actively maintained.

Scope filesystem access

When using the filesystem MCP server, pass the narrowest directory path you need. Giving access to / or /home when you only need /app/data creates unnecessary risk.

Environment variables for credentials

Never hardcode API keys or tokens in your code. Pass them as environment variables to the MCP server via the env parameter, and source them from your environment or secrets manager.

Combine multiple servers

Agents can use tools from multiple MCP servers simultaneously. Unpack each server’s tools with *MCP(...) and combine them into a single tools list for maximum capability. Loading via load_mcp_tools auto-namespaces each server’s tools (e.g. filesystem_search, github_search) so overlapping names never collide.

Tools — built-in tools and custom tool functions

MCP Tool Filtering — filter which tools to expose per agent

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Which MCP package do I need?

Quick Start

Three equivalent forms

Merge rules

How It Works

MCP Server Types

Common Patterns

Pattern 1 — File management agent

Pattern 2 — Database agent

Pattern 3 — GitHub integration

Best Practices

​Which MCP package do I need?

​Quick Start

​Three equivalent forms

​Merge rules

​How It Works

​MCP Server Types

​Common Patterns

​Pattern 1 — File management agent

​Pattern 2 — Database agent

​Pattern 3 — GitHub integration

​Best Practices

​Related

Which MCP package do I need?

Quick Start

Three equivalent forms

Merge rules

How It Works

MCP Server Types

Common Patterns

Pattern 1 — File management agent

Pattern 2 — Database agent

Pattern 3 — GitHub integration

Best Practices

Related