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.

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.

How It Works

Quick Start

1. Create YAML Workflow

   Define an agent with MCP servers in 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:
         command: npx
         args:
           - "-y" 
           - "@modelcontextprotocol/server-time"
         env: {}
         enabled: true
   
2. Run the Workflow

   Execute the YAML workflow with MCP integration:

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

---

Configuration Schema

Basic MCP Server

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

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

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:

# 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  
    time:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/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:

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

Per-server tool filtering (tools.include/exclude keys) is not yet supported by the YAML/TOML MCP server schema. Apply filtering in Python via MCP(allowed_tools=...) after calling mcp.get_tools() in your application code.

Current Limitation Example

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

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

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

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