MCP Integration

MCP Integration#

MassGen supports the Model Context Protocol (MCP) for standardized tool integration. MCP enables agents to use external tools through a unified interface.

What is MCP?#

From the official documentation:

MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.

MassGen integrates MCP through YAML configuration, allowing agents to access tools like:

  • Web search (Brave, Google)

  • Weather services

  • File operations

  • Browser automation (Playwright)

  • Discord, Twitter, Notion APIs

  • And many more MCP servers

Quick Start#

Single MCP tool (weather):

massgen \
  --config @examples/tools/mcp/gpt5_nano_mcp_example.yaml \
  "What's the weather forecast for New York this week?"

Multiple MCP tools:

massgen \
  --config @examples/tools/mcp/multimcp_gemini.yaml \
  "Find the best restaurants in Paris and save the recommendations to a file"

Backend Support#

MCP integration is available for most MassGen backends. For the complete backend capabilities matrix including MCP support status, see Backend Configuration.

Backends with MCP Support:

  • ✅ Claude API - Full MCP integration

  • ✅ Claude Code - Native MCP + file tools

  • ✅ Gemini API - Full MCP integration with planning mode

  • ✅ Grok API - Full MCP integration

  • ✅ OpenAI API - Full MCP integration

  • ✅ Z AI - MCP integration available

  • ❌ Azure OpenAI - Not yet supported

See Backend Configuration for detailed backend capabilities and feature comparison.

Configuration#

Basic MCP Setup#

Add MCP servers to your agent’s backend configuration:

agents:
  - id: "agent_with_mcp"
    backend:
      type: "openai"              # Your backend choice
      model: "gpt-5-mini"         # Your model choice

      # Add MCP servers here
      mcp_servers:
        - name: "weather"         # Server name (you choose this)
          type: "stdio"           # Communication type
          command: "npx"          # Command to run
          args: ["-y", "@modelcontextprotocol/server-weather"]

That’s it! The agent can now check weather.

MCP Transport Types#

stdio (Standard Input/Output)

Most MCP servers use stdio transport:

mcp_servers:
  - name: "weather"
    type: "stdio"                # stdio transport
    command: "npx"               # Command to launch server
    args: ["-y", "@modelcontextprotocol/server-weather"]

streamable-http (HTTP/SSE)

Some MCP servers use HTTP with Server-Sent Events:

mcp_servers:
  - name: "custom_api"
    type: "streamable-http"      # HTTP transport
    url: "http://localhost:8080/mcp/sse"

Configuration Parameters#

Parameter

Required

Description

name

Yes

Unique name for the MCP server

type

Yes

Transport: "stdio" or "streamable-http"

command

stdio only

Command to run the MCP server

args

stdio only

Arguments for the command

url

http only

Server endpoint URL

env

No

Environment variables to pass

Variable Substitution#

MassGen supports variable substitution in MCP configurations:

Built-in Variables:

  • ${cwd} - Replaced with the agent’s working directory (from backend.cwd)

  • Works anywhere in the backend config (args, env, etc.)

Environment Variables:

  • Use ${VARIABLE_NAME} syntax (must be UPPERCASE)

  • Resolved from your .env file or system environment

  • Work in both args and env parameters

mcp_servers:
  - name: "playwright"
    type: "stdio"
    command: "npx"
    args:
      - "@playwright/mcp@latest"
      - "--output-dir=${cwd}"                # Built-in: agent's working directory
      - "--user-data-dir=${cwd}/profile"
    env:
      API_KEY: "${API_KEY}"                  # Environment variable from .env file

Important:

  • ${cwd} is lowercase and refers to the agent’s working directory

  • Environment variables must be UPPERCASE (e.g., ${API_KEY}, ${BRAVE_API_KEY})

  • Both systems work together but are resolved separately

Common MCP Servers#

Weather#

mcp_servers:
  - name: "weather"
    type: "stdio"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-weather"]

Web Search (Brave)#

Requires BRAVE_API_KEY in your .env file:

mcp_servers:
  - name: "search"
    type: "stdio"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-brave-search"]
    env:
      BRAVE_API_KEY: "${BRAVE_API_KEY}"

Playwright (Browser Automation)#

Enables browser automation with screenshot and PDF capabilities:

mcp_servers:
  playwright:
    type: "stdio"
    command: "npx"
    args:
      - "@playwright/mcp@latest"
      - "--browser=chrome"              # Browser choice (chrome, firefox, webkit)
      - "--caps=vision,pdf"             # Enable vision and PDF capabilities
      - "--output-dir=${cwd}"           # Save screenshots/PDFs to workspace
      - "--user-data-dir=${cwd}/playwright-profile"  # Persistent browser profile

Advanced Options:

  • --browser - Browser to use: chrome, firefox, or webkit

  • --caps - Capabilities: vision (screenshots), pdf (PDF generation)

  • --output-dir - Directory for saving screenshots and PDFs

  • --user-data-dir - Persistent browser profile directory

  • --save-trace - Save Playwright traces for debugging (uncomment to enable)

Discord#

Requires Discord bot token. See Discord MCP Setup Guide:

mcp_servers:
  - name: "discord"
    type: "stdio"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-discord"]
    env:
      DISCORD_BOT_TOKEN: "${DISCORD_BOT_TOKEN}"

Twitter#

Requires Twitter API credentials. See Twitter MCP Setup Guide:

mcp_servers:
  - name: "twitter"
    type: "stdio"
    command: "npx"
    args: ["-y", "mcp-server-twitter-unofficial"]
    env:
      TWITTER_USERNAME: "${TWITTER_USERNAME}"
      TWITTER_PASSWORD: "${TWITTER_PASSWORD}"

Multiple MCP Servers#

Agents can use multiple MCP servers simultaneously:

agents:
  - id: "multi_tool_agent"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"
      mcp_servers:
        # Web search
        - name: "search"
          type: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-brave-search"]
          env:
            BRAVE_API_KEY: "${BRAVE_API_KEY}"

        # Weather data
        - name: "weather"
          type: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-weather"]

The agent can use all tools together. For example: “Search for weather apps and check the weather in Paris”

Note

File operations are handled automatically via the cwd parameter in your backend configuration. You don’t need to add a filesystem MCP server manually.

Tool Filtering#

Control which MCP tools are available to agents.

Backend-Level Filtering#

Exclude specific tools at the backend level:

backend:
  type: "openai"
  model: "gpt-4o-mini"
  exclude_tools:
    - mcp__discord__discord_send_webhook_message  # Exclude dangerous tools
  mcp_servers:
    - name: "discord"
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-discord"]

MCP-Server-Specific Filtering#

Override with allowed tools per MCP server:

backend:
  type: "openai"
  model: "gpt-4o-mini"
  mcp_servers:
    - name: "discord"
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-discord"]
      allowed_tools:  # Whitelist specific tools
        - mcp__discord__discord_read_messages
        - mcp__discord__discord_send_message

Merged Exclusions#

exclude_tools from both backend and MCP server configs are combined:

backend:
  exclude_tools:
    - mcp__discord__send_webhook  # Backend-level exclusion
  mcp_servers:
    - name: "discord"
      exclude_tools:
        - mcp__discord__delete_channel  # MCP-level exclusion
      # Both tools are excluded

MCP Planning Mode#

NEW in v0.1.2: Intelligent LLM-based tool filtering automatically detects and blocks irreversible operations during coordination.

Planning mode prevents irreversible actions during multi-agent coordination by intelligently analyzing your question and blocking tools with side effects.

How It Works#

Without planning mode:

  1. All agents execute MCP tools during coordination

  2. Risk of duplicate or premature actions

  3. Example: Multiple agents posting to Discord

With planning mode (v0.1.2):

  1. LLM Analysis: Question is analyzed to detect irreversible operations

  2. Automatic Blocking: Tools with side effects are automatically blocked during coordination

  3. Coordination: Agents plan and discuss with read-only tools available

  4. Execution: Winning agent executes the plan with full tool access

Example Analysis Output:

╭─ Coordination Mode ────────────────────────────────────────╮
│ 🧠 Planning Mode: ENABLED                                  │
│                                                            │
│ Agents will plan and coordinate without executing         │
│ irreversible actions. The winning agent will implement    │
│ the plan during final presentation.                       │
│                                                            │
│ 🚫 Blocked Tools:                                          │
│   1. mcp__discord__discord_send_message                    │
│                                                            │
│ 📊 Analysis:                                               │
│   Post a summary of recent AI discussions to Discord      │
╰────────────────────────────────────────────────────────────╯

The LLM identifies which tools have irreversible side effects (like sending messages) and blocks them during coordination, while keeping read-only tools (like reading messages) available.

Configuration#

Enable planning mode in orchestrator config - the LLM analysis happens automatically:

orchestrator:
  coordination:
    enable_planning_mode: true
    planning_mode_instruction: |
      PLANNING MODE ACTIVE: You are currently in the coordination phase.
      During this phase:
      1. Describe your intended actions and reasoning
      2. Analyze other agents' proposals
      3. Use only 'vote' or 'new_answer' tools for coordination
      4. Read-only tools are available, but write operations are blocked
      5. Save execution for final presentation phase

When enable_planning_mode: true is set:

  1. Automatic Analysis: An LLM analyzes your question before coordination starts

  2. Smart Blocking: Only tools with irreversible side effects are blocked

  3. Read-Only Access: Agents can still use read tools (e.g., discord_get_messages)

  4. Visual Feedback: A UI box shows what’s blocked and why

No manual tool filtering needed - the system intelligently determines what to block based on your specific question.

Example Configuration#

agents:
  - id: "gemini_discord_agent"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"
      mcp_servers:
        - name: "discord"
          type: "stdio"
          command: "npx"
          args: ["-y", "mcp-discord"]
          env:
            DISCORD_TOKEN: "${DISCORD_TOKEN}"
          security:
            level: "high"

  - id: "openai_discord_agent"
    backend:
      type: "openai"
      model: "gpt-4o-mini"
      mcp_servers:
        - name: "discord"
          type: "stdio"
          command: "npx"
          args: ["-y", "mcp-discord"]
          env:
            DISCORD_TOKEN: "${DISCORD_TOKEN}"

orchestrator:
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"
  coordination:
    enable_planning_mode: true
    planning_mode_instruction: |
      PLANNING MODE ACTIVE: Coordination phase - plan only.
      Read-only operations are allowed (reading messages, files).
      DO NOT execute write operations - those are blocked.

Usage#

# Five agents with planning mode (no execution during coordination)
massgen \
  --config @examples/tools/planning/five_agents_filesystem_mcp_planning_mode.yaml \
  "Create a comprehensive project structure with documentation"

What happens:

  1. Coordination phase → Agents discuss and plan file structure

  2. Voting → Agents vote for best plan

  3. Final presentation → Winning agent executes the plan

Multi-Backend Support#

Planning mode works across:

  • Response API (Claude)

  • Chat Completions (OpenAI, Grok, etc.)

  • Gemini with session-based tool execution

Complete Example#

Full configuration with multiple MCP servers and planning mode:

agents:
  - id: "research_agent"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"
      mcp_servers:
        # Web search
        - name: "search"
          type: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-brave-search"]
          env:
            BRAVE_API_KEY: "${BRAVE_API_KEY}"
          allowed_tools:
            - mcp__search__brave_web_search

        # Weather
        - name: "weather"
          type: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-weather"]

  - id: "analyst_agent"
    backend:
      type: "openai"
      model: "gpt-5-nano"
      # File operations handled via cwd parameter

orchestrator:
  coordination:
    enable_planning_mode: true
    planning_mode_instruction: |
      PLANNING MODE: Describe your intended tool usage.
      Do not execute tools during coordination.

ui:
  display_type: "rich_terminal"
  logging_enabled: true

Security Considerations#

  1. Tool Filtering - Use allowed_tools and exclude_tools to limit capabilities

  2. Planning Mode - Enable for tasks with irreversible actions

  3. Environment Variables - Store API keys in .env, never in config files

  4. Path Restrictions - Limit filesystem server to specific directories

  5. Review Permissions - Check what each MCP server can do before enabling

Troubleshooting#

MCP server not found:

Ensure the MCP server package is installed:

npx -y @modelcontextprotocol/server-weather

Tools not appearing:

  • Check backend MCP support (see table above)

  • Verify mcp_servers configuration

  • Check for tool filtering (allowed_tools, exclude_tools)

Environment variables not working:

# Set in .env file
BRAVE_API_KEY=your_key_here

# Reference in config
env:
  BRAVE_API_KEY: "${BRAVE_API_KEY}"

Planning mode not working:

  • Check enable_planning_mode: true in orchestrator config

  • Look for the UI box showing analysis results at the start of coordination

  • If the box says “Planning Mode: DISABLED”, the LLM didn’t detect irreversible operations

  • Review logs to see what tools the LLM identified as blocked

Planning mode blocking too many/few tools:

  • The LLM automatically analyzes your question to determine what to block

  • If too restrictive: Rephrase your question to emphasize read-only operations

  • If not restrictive enough: Make your question more explicit about write operations

  • The analysis UI box shows exactly what was blocked and why

Want to see the analysis:

The UI box appears automatically before coordination starts when planning mode is enabled.

Next Steps#