MCP Schema

Args supplies additional arguments passed to the command when spawning local MCP processes.

Only used when command is provided (stdio transport). Ignored when url is configured. Runtime validation enforces that command and url are mutually exclusive. Use this to provide flags or subcommands while keeping Command focused on the executable. Example: command: "uvx" args: ["mcp-server-fetch", "--port", "9000"]

Command is the executable command to spawn a local MCP server process.

Used for stdio transport to run MCP servers as child processes. Supports both direct executables and complex commands with arguments.

• Examples:

# Simple executable
command: "mcp-server-filesystem"

# Command with arguments
command: "python /app/mcp_server.py --mode production"

# Docker container
command: "docker run --rm -i mcp/postgres:latest"

Security Note: Commands are parsed using shell lexing for safety. Avoid user-provided input in commands.

Env contains environment variables to pass to the MCP server process.

Only used when command is specified for spawning local processes. Useful for passing configuration, secrets, or runtime parameters.

• Examples:

env:
  DATABASE_URL: "postgres://user:pass@localhost/db"
  API_KEY: "{{ .env.GITHUB_TOKEN }}"
  LOG_LEVEL: "debug"
  WORKSPACE_DIR: "/data/workspace"

Template Support: Values can use Go template syntax to reference environment variables from the host system.

Headers contains HTTP headers to include when connecting to remote MCP servers (SSE/HTTP). Useful for passing Authorization tokens, custom auth headers, or version negotiation. Example: headers: Authorization: "Bearer {{ .env.GITHUB_MCP_OAUTH_TOKEN }}"

ID is the unique identifier for this MCP server configuration.

This identifier is used throughout the system to reference this specific MCP server. Choose descriptive IDs that reflect the server's purpose.

• Examples:
• filesystem - for file system operations
• postgres-db - for PostgreSQL database access
• github-api - for GitHub integration
• python-runtime - for Python code execution

MaxSessions defines the maximum number of concurrent sessions allowed.

Helps manage resource usage and prevent server overload. Each agent connection typically creates one session.

Values:

• 0 or negative: Unlimited sessions (default)

• Positive number: Maximum concurrent sessions

• Examples:

max_sessions: 10  # Allow up to 10 concurrent connections
max_sessions: 1   # Single session only (useful for stateful servers)
max_sessions: 0   # Unlimited sessions

Proto specifies the MCP protocol version to use.

Different protocol versions may support different features, message formats, or capabilities. Always use the version compatible with your MCP server.

Format: YYYY-MM-DD (e.g., "2025-03-26")

Default: DefaultProtocolVersion ("2025-03-26")

Version History:

• 2025-03-26 - Latest version with streaming support
• 2024-12-01 - Initial protocol release

Resource reference for the MCP server (optional)

If not specified, defaults to the value of ID. Used for resource identification and referencing in Compozy's resource system.

StartTimeout is the maximum time to wait for the MCP server to start.

Only applicable when using command to spawn local processes. Helps detect and handle startup failures gracefully.

Format: Go duration string (e.g., "30s", "1m", "500ms")

Default: No timeout (waits indefinitely)

• Examples:

start_timeout: 30s   # Wait up to 30 seconds
start_timeout: 2m    # Wait up to 2 minutes
start_timeout: 500ms # Wait up to 500 milliseconds

Recommendation: Set to at least 10-30s for Docker-based servers.

Transport defines the communication transport mechanism.

Choose the transport based on your MCP server's capabilities and deployment model.

Supported Values:

Default: sse

• Examples:

# Remote server with SSE
transport: sse

# Local process with stdio
transport: stdio

# HTTP server with large file support
transport: streamable-http

URL is the endpoint for remote MCP servers.

Required for HTTP-based transports (SSE, streamable-http). Must be a valid HTTP or HTTPS URL pointing to an MCP-compatible endpoint.

Format: http[s]://host[:port]/path

• Examples:

url: "http://localhost:3000/mcp"
url: "https://api.example.com/v1/mcp"
url: "http://mcp-proxy:6001/filesystem"

Note: Mutually exclusive with command - use either URL or Command, not both.