Praison AI

MCP YAML Configuration

Configure MCP servers in YAML workflows for declarative agent setup

Define MCP servers directly in YAML workflows to create agents with external tool capabilities in a declarative way.

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

python
from praisonaiagents import Agent

agent = Agent(name="mcp-agent", instructions="Configure MCP tools via YAML.")
agent.start("Load MCP tools defined in mcp-config.yaml.")

The user declares MCP servers in YAML; PraisonAI wires those tools into the agent at startup.

Diagram

YAML MCP Configuration

📄 YAML Config

⚙️ Parser

🔌 MCP Servers

🤖 Agent

🧰 Tool Usage

How It Works

Diagram
MCP YAML ConfigurationAgentUserMCP YAML ConfigurationAgentUserRequestProcess requestResult Agent–>>User: Response

Quick Start

  1. Create YAML Workflow

    Define an agent with MCP servers in YAML:

    yaml
    # agent-with-mcp.yaml
agent:
  name: mcp_assistant
  instructions: |
    You are a helpful assistant with access to filesystem and time tools.
    Use the MCP tools when needed to help users with file operations or time queries.
  llm: gpt-4o-mini

mcp:
  servers:
    filesystem:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "."
      env: {}
      enabled: true

    time:
      # Time and date utilities (published Python MCP server via uvx)
      command: uvx
      args:
        - "mcp-server-time"
      env: {}
      enabled: true
  2. Run the Workflow

    Execute the YAML workflow with MCP integration:

    bash
    praisonai workflow run --file agent-with-mcp.yaml

Configuration Schema

Basic MCP Server

yaml
mcp:
  servers:
    server_name:
      command: npx                           # Command to run
      args:                                  # Command arguments
        - "-y"
        - "@modelcontextprotocol/server-filesystem" 
        - "/tmp"
      env: {}                               # Environment variables
      enabled: true                         # Enable/disable server

With Environment Variables

yaml
mcp:
  servers:
    github:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-github"
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"     # Use environment variable
        REPO_PATH: "./my-repo"              # Static value
      enabled: true

Multiple Servers

yaml
mcp:
  servers:
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
      enabled: true

    brave_search:
      command: npx  
      args: ["-y", "@modelcontextprotocol/server-brave-search"]
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"
      enabled: true

    postgres:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-postgres"]
      env:
        DATABASE_URL: "${DATABASE_URL}"
      enabled: false  # Disabled by default

Complete Example

Here’s a production-ready YAML configuration:

yaml
# multi-tool-agent.yaml
agent:
  name: developer_assistant
  instructions: |
    You are a developer assistant with access to:
    - Filesystem operations (read, write, list files)
    - Time and date utilities
    - Web search capabilities

    Help users with development tasks, file management, and research.
    Always be helpful and accurate in your responses.
  llm: gpt-4o-mini

mcp:
  servers:
    # Local filesystem access
    filesystem:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "."
      env: {}
      enabled: true

    # Time and date utilities (published Python MCP server via uvx)
    time:
      command: uvx
      args:
        - "mcp-server-time"
      env: {}
      enabled: true

    # Web search (requires API key)
    brave_search:
      command: npx
      args:
        - "-y" 
        - "@modelcontextprotocol/server-brave-search"
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"
      enabled: true

    # GitHub integration (optional)
    github:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-github"  
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"
      enabled: false  # Enable when token is available

Run with:

bash
export BRAVE_API_KEY="your-brave-api-key"
export GITHUB_TOKEN="your-github-token"  # Optional
praisonai workflow run --file multi-tool-agent.yaml

Important Limitations

Current Limitation Example

yaml
# ❌ This does NOT work yet
mcp:
  servers:
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
      tools:
        include: ["read_file", "list_directory"]  # Not supported
        exclude: ["write_file", "delete_file"]    # Not supported

Workaround in Python

python
from praisonaiagents import Agent
from praisonaiagents.mcp import load_mcp_tools

# Load tools from YAML config
tools = load_mcp_tools()

# Apply filtering manually
for tool in tools:
    if tool.name == "filesystem":
        # Apply filtering after loading
        tool.allowed_tools = ["read_file", "list_directory"]

agent = Agent(name="filtered", tools=tools)

Environment Variable Patterns

Using .env Files

yaml
# .env
BRAVE_API_KEY=your_brave_api_key
GITHUB_TOKEN=ghp_your_github_token
DATABASE_URL=postgresql://user:pass@localhost/db

# agent.yaml
mcp:
  servers:
    search:
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"

Conditional Enabling

yaml
mcp:
  servers:
    # Always enabled (no API key needed)
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
      enabled: true

    # Only enable if API key is available
    brave_search:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-brave-search"]  
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"
      enabled: "${BRAVE_API_KEY:+true}"  # Enable only if BRAVE_API_KEY is set

Best Practices

Use Environment Variables for Secrets

Never hardcode API keys in YAML files. Always use environment variable substitution with ${VARIABLE_NAME} syntax.

Enable Servers Conditionally

Use the enabled field to control which servers are active. This allows you to have optional integrations that only activate when configured.

Document Your Server Configuration

Add comments explaining what each server does and what environment variables it requires. This helps with team collaboration.

Test Server Configurations

Before deploying, test your YAML configuration locally to ensure all servers connect properly and required environment variables are available.

Related

Load MCP Tools

Wire configured MCP servers into agents with one line

 MCP CLI

Configure and manage MCP servers from the command line