> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compozy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Learn about the parameters and definitions of MCP servers in Compozy.

## JSON Schema

```json https://compozy.dev/schemas/mcp.json [expandable] theme={"dark"}
{
  "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

<ParamField path="mcp_servers" type="array" required>
  List of MCP servers available in the workflow.
</ParamField>

<ParamField path="mcp_servers[].id" type="string" required>
  Unique identifier for the MCP server. Must be unique across all servers in your
  workflow.
</ParamField>

<ParamField path="mcp_servers[].use" type="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

  <CodeGroup>
    ```yaml Shorthand theme={"dark"}
    mcp_servers:
      - id: telegram_bot
        use: compozy/mcp-servers:telegram
    ```

    ```yaml Version theme={"dark"}
    mcp_servers:
      - id: slack_app
        use: compozy/mcp-servers:slack@2.1.0
    ```

    ```yaml Detailed theme={"dark"}
    mcp_servers:
      - id: github_integration
        use:
          repo: compozy/mcp-servers
          package: github
          version: 1.2.0
    ```
  </CodeGroup>
</ParamField>

<ParamField path="mcp_servers[].command" type="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"`
</ParamField>

<ParamField path="mcp_servers[].config" type="object">
  Server-specific configuration options. Structure varies by server type.
</ParamField>

<ParamField path="mcp_servers[].env" type="object">
  Environment variables specific to this server instance.
</ParamField>

## Output References

<ResponseField name="mcp_servers.server_id.output" type="any">
  Server's output data, accessible via `{{ mcp_servers.server_id.output }}`. Example:

  ```json theme={"dark"}
  {
    "message_id": "123456789",
    "chat_id": "-100123456789",
    "status": "sent",
    "timestamp": "2024-03-20T10:30:00Z"
  }
  ```
</ResponseField>

<ResponseField name="mcp_servers.server_id.error" type="object">
  Error information if server execution fails. Example:

  ```json theme={"dark"}
  {
    "code": "CONNECTION_ERROR",
    "message": "Failed to connect to service",
    "details": {
      "status": 503,
      "reason": "Service unavailable"
    }
  }
  ```
</ResponseField>