Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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

Never hardcode API keys in YAML files. Always use environment variable substitution with ${VARIABLE_NAME} syntax.
Use the enabled field to control which servers are active. This allows you to have optional integrations that only activate when configured.
Add comments explaining what each server does and what environment variables it requires. This helps with team collaboration.
Before deploying, test your YAML configuration locally to ensure all servers connect properly and required environment variables are available.

Load MCP Tools

Wire configured MCP servers into agents with one line

MCP CLI

Configure and manage MCP servers from the command line