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
Workflow Integration
Multi-Server Configuration
External Tool Integration
Agent Integration Patterns
Single MCP Server Integration
The simplest integration pattern connects one agent to one MCP server for focused functionality:
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:
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
Error Handling
Environment Management
Transport Selection
Tool Organization
Testing Strategy
Next Steps
Security & Authentication
The MCP Proxy provides comprehensive security features including token-based authentication, IP filtering, rate limiting, and security headers. This guide covers configuring and managing security for your MCP deployments with multi-layered protection strategies.
Overview
Master Compozy's event-driven communication system for building reactive, scalable workflows with signal-based coordination patterns