MCP Integration

Integration Patterns

MCP (Model Context Protocol) integration patterns provide proven approaches for connecting external tools and services with Compozy agents and workflows. This guide covers common patterns, best practices, and implementation strategies for building robust MCP integrations using Compozy's simple HTTP-based architecture.

Overview

Agent Integration

Connect AI agents directly to MCP servers for intelligent tool usage

Workflow Integration

Use MCP servers within workflow task orchestration

Multi-Server Configuration

Configure multiple MCP servers for different capabilities

External Tool Integration

Connect external tools through MCP protocol adapters

Agent Integration Patterns

Single MCP Server Integration

The simplest integration pattern connects one agent to one MCP server for focused functionality:

workflow-with-mcp.yaml
resource: workflow
id: file-management-workflow
description: Workflow using MCP filesystem server

# MCP server configuration
mcps:
  - id: filesystem
    transport: stdio
    command: "mcp-server-filesystem"
    args: ["--root", "/workspace"]
    env:
      LOG_LEVEL: "info"

agents:
  - id: file_manager
    instructions: |
      You are a file management assistant with access to the file system.
      You can read, write, and organize files in the workspace directory.
      Always confirm destructive operations before executing them.

tasks:
  - id: list_workspace_files
    type: basic
    agent: file_manager
    prompt: "List all files in the workspace directory"

  - id: read_specific_file
    type: basic
    agent: file_manager
    prompt: "Read the contents of: {{ .workflow.input.filename }}"
    condition: "{{ .workflow.input.filename }}"

  - id: create_summary
    type: basic
    agent: file_manager
    prompt: |
      Create a summary of the workspace contents:
      Files found: {{ .tasks.list_workspace_files.output }}
      {{ if .tasks.read_specific_file.output }}
      Content of {{ .workflow.input.filename }}: {{ .tasks.read_specific_file.output }}
      {{ end }}

This pattern demonstrates:

  • Simple MCP registration: Single filesystem server using stdio transport
  • Agent tool access: Agent can use MCP tools transparently
  • Workflow integration: MCP servers available throughout the workflow
  • Error handling: Built-in error handling for MCP server failures

Multiple MCP Servers Integration

For more complex scenarios, you can configure multiple MCP servers within a single workflow. Use the CLI to manage these workflows:

multi-server-workflow.yaml
resource: workflow
id: multi-server-example
description: Workflow using multiple MCP servers

# Multiple MCP server configuration
mcps:
  - id: filesystem
    transport: stdio
    command: "mcp-server-filesystem"
    args: ["--root", "/workspace"]
    env:
      LOG_LEVEL: "info"

  - id: database
    transport: stdio
    command: "mcp-server-database"
    args: ["--connection", "postgresql://localhost/db"]
    env:
      QUERY_TIMEOUT: "30s"

agents:
  - id: data_processor
    instructions: |
      You can access both the filesystem and database.
      Use the filesystem for reading configuration files and the database for storing results.

tasks:
  - id: read_config
    type: basic
    agent: data_processor
    prompt: "Read the configuration file from /workspace/config.json"

  - id: process_data
    type: basic
    agent: data_processor
    prompt: |
      Process the data based on the configuration: {{ .tasks.read_config.output }}
      Store the results in the database.

  - id: verify_storage
    type: basic
    agent: data_processor
    prompt: "Verify that the data was stored correctly in the database"

Dynamic MCP Server Selection

You can configure conditional MCP server loading based on workflow context:

resource: workflow
id: adaptive-mcp-workflow
description: Conditional MCP server selection based on input parameters

mcps:
  - id: local_filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    condition: '{{ eq .workflow.input.environment "local" }}'

  - id: database_server
    transport: stdio
    command: python
    args: ["mcp_server_database.py", "--connection-string", "{{ .env.DATABASE_URL }}"]
    condition: '{{ eq .workflow.input.operation_type "database" }}'

agents:
  - id: adaptive_assistant
    instructions: |
      You are an assistant that uses different MCP servers based on the task context.
      The available MCP servers will vary based on the environment and operation type.

tasks:
  - id: adaptive_operation
    type: basic
    agent: adaptive_assistant
    prompt: |
      Task: {{ .workflow.input.task }}
      Environment: {{ .workflow.input.environment }}
      Operation Type: {{ .workflow.input.operation_type }}

      Use the appropriate MCP tools available for this context to complete the task.

Key benefits of conditional MCP loading:

  • Resource efficiency: Only load MCP servers when needed
  • Environment-specific behavior: Different servers for different environments
  • Operation-specific access: Control which servers are available for specific operations
  • Simple configuration: Use standard template conditions

Workflow Integration Patterns

CLI Development Workflow

The recommended development workflow uses the Compozy CLI for seamless integration:

# 1. Initialize project with MCP support
compozy init data-processing-project
cd data-processing-project

# 2. Start development server with hot reload
compozy dev --watch

# 3. In another terminal, start MCP proxy
compozy mcp-proxy --mcp-port 6001 --debug

# 4. Test your workflow
compozy workflow execute data-processing-workflow

Basic MCP Tool Usage

For simple data processing workflows, refer to the Single MCP Server Integration pattern above with these key principles:

  • Use focused agents with clear instructions for specific data operations
  • Structure tasks in logical sequence (read → process → save)
  • Leverage template variables for dynamic file paths and formats
  • Implement proper error handling for file operations

Checklist

  • Project Setup

    Use compozy init to create a new project with MCP support

  • Development Environment

    Start development server with compozy dev --watch for hot reload

  • MCP Proxy Setup

    Start MCP proxy with compozy mcp-proxy --debug for development

  • Configuration Phase

    Configure MCP servers with proper command arguments and environment variables

  • Implementation Phase

    Create agents with access to MCP tools and build workflows

  • Testing Phase

    Test with compozy workflow execute and verify tool registration

  • Deployment Phase

    Deploy with compozy start and proper logging configuration

  • Maintenance Phase

    Monitor with CLI commands and update configurations as needed

This guide provides practical patterns for integrating MCP servers with Compozy agents and workflows using the simple HTTP-based proxy architecture.

Best Practices

Simple Configuration

Use clear MCP server commands with proper arguments and environment variables

Error Handling

Handle MCP server failures gracefully with clear error messages

Environment Management

Use environment variables for configuration and secrets

Transport Selection

Choose appropriate transport (stdio or SSE) based on MCP server capabilities

Tool Organization

Structure your MCP tools for easy discovery and maintenance

Testing Strategy

Test MCP integrations with realistic data and scenarios

Next Steps