API Reference

JSON Schema

https://compozy.dev/schemas/mcp.json

{
  "type": "object",
  "required": ["mcp_servers"],
  "properties": {
    "mcp_servers": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "use", "command"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the MCP server"
          },
          "use": {
            "oneOf": [
              { "type": "string" },
              {
                "type": "object",
                "required": ["repo", "package"],
                "properties": {
                  "repo": { "type": "string" },
                  "package": { "type": "string" },
                  "version": { "type": "string" }
                }
              }
            ],
            "description": "Server implementation reference"
          },
          "command": {
            "type": "string",
            "description": "Command to execute the MCP server"
          },
          "config": {
            "type": "object",
            "description": "Server-specific configuration options"
          },
          "env": {
            "type": "object",
            "description": "Environment variables for this server instance"
          }
        }
      }
    }
  }
}

Parameters

array

required

List of MCP servers available in the workflow.

string

required

Unique identifier for the MCP server. Must be unique across all servers in your workflow.

string | object

required

Server implementation reference. Can be specified in three formats:

"repo/package" (e.g., "compozy/mcp-servers:telegram")
"repo:package@version" (e.g., "compozy/mcp-servers:telegram@1.0.0")
Object with repo and package fields

mcp_servers:
  - id: telegram_bot
    use: compozy/mcp-servers:telegram

mcp_servers:
  - id: slack_app
    use: compozy/mcp-servers:slack@2.1.0

mcp_servers:
  - id: github_integration
    use:
      repo: compozy/mcp-servers
      package: github
      version: 1.2.0

string

required

Command to execute the MCP server. Can be an NPM package or Docker command. Examples:

"npx -y @compozy/mcp-telegram"
"docker run -i --rm mcp/blockchain-scanner"

object

Server-specific configuration options. Structure varies by server type.

object

Environment variables specific to this server instance.

Output References

any

Server’s output data, accessible via {{ mcp_servers.server_id.output }}. Example:

{
  "message_id": "123456789",
  "chat_id": "-100123456789",
  "status": "sent",
  "timestamp": "2024-03-20T10:30:00Z"
}

object

Error information if server execution fails. Example:

{
  "code": "CONNECTION_ERROR",
  "message": "Failed to connect to service",
  "details": {
    "status": 503,
    "reason": "Service unavailable"
  }
}

Getting Started

Core Concepts

JSON Schema

Parameters

Output References

​JSON Schema

​Parameters

​Output References

JSON Schema

Parameters

Output References