MCP (Model Context Protocol)

Integrate Model Context Protocol servers as tools for agents

The --mcp flag enables integration with Model Context Protocol (MCP) servers, allowing agents to use external tools and services.

All praisonai mcp <cmd> host commands (serve, list-tools, doctor, serve-recipe) also run as praisonai-mcp <cmd> when only the standalone praisonai-mcp package is installed. Config commands (list, add, remove, test, sync, tools, describe, status, run, auth, logout) require praisonai-code; running one without it prints:

MCP configuration commands require praisonai-code.
Install it with: pip install praisonai-code
(or install the full stack: pip install "praisonai[mcp]")

Quick Start

praisonai mcp list

praisonai "Search files" --mcp "npx -y @modelcontextprotocol/server-filesystem ."

Usage

Basic MCP Server

praisonai "List files in current directory" --mcp "npx -y @modelcontextprotocol/server-filesystem ."

Expected Output:

🔌 MCP Server connected: @modelcontextprotocol/server-filesystem

╭─ Agent Info ─────────────────────────────────────────────────────────────────╮
│  👤 Agent: DirectAgent                                                       │
│  Role: Assistant                                                             │
│  🔧 Tools: list_directory, read_file, write_file                            │
╰──────────────────────────────────────────────────────────────────────────────╯

╭────────────────────────────────── Response ──────────────────────────────────╮
│ Here are the files in the current directory:                                 │
│                                                                              │
│ 📁 src/                                                                      │
│ 📁 tests/                                                                    │
│ 📄 README.md                                                                 │
│ 📄 package.json                                                              │
│ 📄 requirements.txt                                                          │
╰──────────────────────────────────────────────────────────────────────────────╯

MCP with Environment Variables

# Brave Search with API key
praisonai "Search for AI news" \
  --mcp "npx -y @modelcontextprotocol/server-brave-search" \
  --mcp-env "BRAVE_API_KEY=your_api_key"

Expected Output:

🔌 MCP Server connected: @modelcontextprotocol/server-brave-search
🔑 Environment variables loaded

╭────────────────────────────────── Response ──────────────────────────────────╮
│ Here are the latest AI news articles:                                        │
│                                                                              │
│ 1. "OpenAI Announces GPT-5" - TechCrunch                                    │
│    https://techcrunch.com/2024/12/...                                       │
│                                                                              │
│ 2. "Google DeepMind's Latest Breakthrough" - The Verge                      │
│    https://theverge.com/2024/12/...                                         │
╰──────────────────────────────────────────────────────────────────────────────╯

Multiple Environment Variables

praisonai "Complex task" \
  --mcp "npx server-name" \
  --mcp-env "API_KEY=key1,SECRET=secret2,REGION=us-east-1"

Popular MCP Servers

Filesystem

--mcp "npx -y @modelcontextprotocol/server-filesystem ."

Read, write, and list files

Brave Search

--mcp "npx -y @modelcontextprotocol/server-brave-search"
--mcp-env "BRAVE_API_KEY=xxx"

Web search capabilities

GitHub

--mcp "npx -y @modelcontextprotocol/server-github"
--mcp-env "GITHUB_TOKEN=xxx"

GitHub repository operations

PostgreSQL

--mcp "npx -y @modelcontextprotocol/server-postgres"
--mcp-env "DATABASE_URL=xxx"

Database queries

Slack

--mcp "npx -y @modelcontextprotocol/server-slack"
--mcp-env "SLACK_TOKEN=xxx"

Slack messaging

Google Drive

--mcp "npx -y @anthropic/server-gdrive"

Google Drive access

Use Cases

File Operations

praisonai "Read the README.md file and summarize it" \
  --mcp "npx -y @modelcontextprotocol/server-filesystem ."

Web Research

praisonai "Research the latest developments in quantum computing" \
  --mcp "npx -y @modelcontextprotocol/server-brave-search" \
  --mcp-env "BRAVE_API_KEY=your_key"

Database Queries

praisonai "Show me the top 10 customers by revenue" \
  --mcp "npx -y @modelcontextprotocol/server-postgres" \
  --mcp-env "DATABASE_URL=postgresql://user:pass@localhost/db"

Expected Output:

╭────────────────────────────────── Response ──────────────────────────────────╮
│ Top 10 Customers by Revenue:                                                 │
│                                                                              │
│ | Rank | Customer        | Revenue      |                                   │
│ |------|-----------------|--------------|                                   │
│ | 1    | Acme Corp       | $1,250,000   |                                   │
│ | 2    | TechStart Inc   | $980,000     |                                   │
│ | 3    | Global Systems  | $875,000     |                                   │
│ | ...  | ...             | ...          |                                   │
╰──────────────────────────────────────────────────────────────────────────────╯

GitHub Operations

praisonai "List open issues in the repository" \
  --mcp "npx -y @modelcontextprotocol/server-github" \
  --mcp-env "GITHUB_TOKEN=ghp_xxx"

Combine with Other Features

# MCP with metrics
praisonai "Search and analyze" --mcp "npx server" --metrics

# MCP with planning
praisonai "Complex research task" --mcp "npx server" --planning

# MCP with guardrail
praisonai "Query database" --mcp "npx postgres-server" --guardrail "Read-only queries"

MCP Server Configuration

Command Format

--mcp "command [args...]"

Examples:

• --mcp "npx -y @modelcontextprotocol/server-filesystem ."
• --mcp "python -m mcp_server"
• --mcp "node ./my-server.js"

Environment Variables Format

--mcp-env "KEY1=value1,KEY2=value2"

Never commit API keys or secrets to version control. Use environment variables or secure secret management.

Best Practices

Test MCP servers independently before using them with agents to ensure they’re working correctly.

Security

Use environment variables for sensitive credentials

Testing

Test MCP servers with simple commands first

Permissions

Grant minimum necessary permissions to MCP servers

Monitoring

Use --metrics to track MCP tool usage

Troubleshooting

Issue	Solution
Server not found	Ensure npx/node is installed and in PATH
Connection timeout	Check network connectivity and server status
Permission denied	Verify API keys and access permissions
Tool not available	Check server documentation for available tools

MCP Configuration Management

In addition to the --mcp flag, you can manage MCP server configurations using the praisonai mcp command.

List Configurations

praisonai mcp list

Expected Output:

                         MCP Server Configurations                         
┏━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name       ┃ Command ┃ Enabled ┃ Scope     ┃ Description                ┃
┡━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ filesystem │ npx     │ ✅      │ workspace │ Filesystem access          │
│ brave      │ npx     │ ✅      │ global    │ Brave search               │
└────────────┴─────────┴─────────┴───────────┴────────────────────────────┘

Create Configuration

praisonai mcp create <name> <command> [args...]

Example:

praisonai mcp create filesystem npx -y @modelcontextprotocol/server-filesystem .

Show Configuration

praisonai mcp show <name>

Expected Output:

MCP Config: filesystem
Command: npx
Args: -y @modelcontextprotocol/server-filesystem .
Enabled: Yes
Description: Filesystem access

Enable/Disable Configuration

praisonai mcp enable <name>
praisonai mcp disable <name>

Delete Configuration

praisonai mcp delete <name>

Verify MCP Setup

Check server health and inspect available tools before wiring them into agents.

# Health check — config, dependencies, protocol version
praisonai mcp doctor

# List tools exposed by the PraisonAI MCP server
praisonai mcp list-tools
praisonai mcp list-tools --json

# Search or inspect a specific tool
praisonai mcp tools search "filesystem"
praisonai mcp tools schema <tool-name>

For ad-hoc server runs, use praisonai mcp serve --transport stdio (local) or --transport http-stream (remote). Saved configs live under ~/.praisonai/mcp/.

Configuration File Format

MCP configs are stored as JSON files in ~/.praisonai/mcp/:

{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
  "env": {
    "SOME_VAR": "value"
  },
  "enabled": true,
  "description": "Filesystem access for the agent"
}

Storage Locations

Location	Scope	Description
~/.praisonai/mcp/	Workspace	Project-specific configs
~/.praisonai/mcp/config.json	Global	Shared across all projects

Legacy .praison/mcp.json paths are still recognised for backward compatibility but ~/.praisonai/mcp/ is the canonical location.

Python API

from praisonaiagents import MCPConfigManager

# Initialize
mcp = MCPConfigManager(workspace_path=".")

# List all configs
configs = mcp.list_configs()

# Get a specific config
config = mcp.get_config("filesystem")

# Create a config
mcp.create_config(
    name="brave-search",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-brave-search"],
    env={"BRAVE_API_KEY": "$BRAVE_API_KEY"},
    description="Brave web search"
)

# Get MCP tools for agents
tools = mcp.get_mcp_tools()

Related

• MCP Overview
• MCP Servers
• Custom MCP