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

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "YAML MCP Configuration"
        YAML[📄 YAML Config] --> Parse[⚙️ Parser]
        Parse --> MCP[🔌 MCP Servers]
        MCP --> Agent[🤖 Agent]
        Agent --> Tools[🧰 Tool Usage]
    end
    
    classDef config fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    
    class YAML config
    class Parse,MCP process
    class Agent,Tools output
```

## Quick Start

<Steps>
  <Step title="Create YAML Workflow">
    Define an agent with MCP servers in YAML:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # 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
    ```
  </Step>

  <Step title="Run the Workflow">
    Execute the YAML workflow with MCP integration:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai workflow run --file agent-with-mcp.yaml
    ```
  </Step>
</Steps>

***

## Configuration Schema

### Basic MCP Server

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<Warning>
  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.
</Warning>

### Current Limitation Example

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# ❌ 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# .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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<AccordionGroup>
  <Accordion title="Use Environment Variables for Secrets">
    Never hardcode API keys in YAML files. Always use environment variable substitution with `${VARIABLE_NAME}` syntax.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Document Your Server Configuration">
    Add comments explaining what each server does and what environment variables it requires. This helps with team collaboration.
  </Accordion>

  <Accordion title="Test Server Configurations">
    Before deploying, test your YAML configuration locally to ensure all servers connect properly and required environment variables are available.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Load MCP Tools" icon="plug" href="/features/load-mcp-tools">
    Wire configured MCP servers into agents with one line
  </Card>

  <Card title="MCP CLI" icon="terminal" href="/cli/mcp">
    Configure and manage MCP servers from the command line
  </Card>
</CardGroup>