Skip to main content
Glama
dhofheinz

MCP ComfyUI Flux

by dhofheinz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

MCP ComfyUI Flux - Optimized Docker Solution

License: MIT Docker PyTorch CUDA

A fully containerized MCP (Model Context Protocol) server for generating images with FLUX models via ComfyUI. Features optimized Docker builds, PyTorch 2.5.1, automatic GPU acceleration, and Claude Desktop integration.

🌟 Features

  • πŸš€ Optimized Performance: PyTorch 2.5.1 with native RMSNorm support

  • πŸ“¦ Efficient Images: 25% smaller Docker images (10.9GB vs 14.6GB)

  • ⚑ Fast Rebuilds: BuildKit cache mounts for rapid iterations

  • 🎨 FLUX Models: Supports schnell (4-step) and dev models with fp8 quantization

  • πŸ€– MCP Integration: Works seamlessly with Claude Desktop

  • πŸ’ͺ GPU Acceleration: Automatic NVIDIA GPU detection and CUDA 12.1

  • πŸ”„ Background Removal: Built-in RMBG-2.0 for transparent backgrounds

  • πŸ“ˆ Image Upscaling: 4x upscaling with UltraSharp/AnimeSharp models

  • πŸ›‘οΈ Production Ready: Health checks, auto-recovery, extensive logging

Related MCP server: ComfyUI MCP Server

πŸ“‹ Table of Contents

πŸš€ Quick Start

# Clone the repository
git clone <repository-url> mcp-comfyui-flux
cd mcp-comfyui-flux

# Run the automated installer
./install.sh

# Or build manually with the optimized build script
./build.sh --start

# That's it! The installer will:
# - Check prerequisites
# - Configure environment
# - Download FLUX models
# - Build optimized Docker containers
# - Start all services

πŸ’» System Requirements

Minimum Requirements

  • OS: Linux, macOS, Windows 10+ (WSL2)

  • CPU: 4 cores

  • RAM: 16GB (20GB for WSL2)

  • Storage: 50GB free space

  • Docker: 20.10+

  • Docker Compose: 2.0+ or 1.29+ (legacy)

Recommended Requirements

  • CPU: 8+ cores

  • RAM: 32GB

  • GPU: NVIDIA RTX 3090/4090 (12GB+ VRAM)

  • Storage: 100GB free space

  • CUDA: 12.1+ with NVIDIA Container Toolkit

WSL2 Specific (Windows)

# .wslconfig in Windows user directory
[wsl2]
memory=20GB
processors=8
localhostForwarding=true

πŸ“¦ Installation

Prerequisites

  1. Install Docker:

    # Ubuntu/Debian
curl -fsSL https://get.docker.com | bash

# macOS
brew install docker docker-compose

# Windows - Install Docker Desktop

  2. Install NVIDIA Container Toolkit (for GPU):

    # Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

Automated Installation

# Standard installation
./install.sh

# Non-interactive installation
./install.sh --yes

# CPU-only mode
./install.sh --cpu-only

# With specific models
./install.sh --models minimal  # or all/none/auto

# Debug mode
./install.sh --debug

Build Script Options

# Build only
./build.sh

# Build and start
./build.sh --start

# Build with cleanup
./build.sh --start --cleanup

# Rebuild without cache
./build.sh --no-cache

🎨 MCP Tools

Available Tools in Claude Desktop

1. generate_image

Generate images using FLUX schnell fp8 model (optimized defaults).

// Parameters
{
  "prompt": "a majestic mountain landscape, golden hour",  // Required
  "negative_prompt": "blurry, low quality",               // Optional
  "width": 1024,                                          // Default: 1024
  "height": 1024,                                         // Default: 1024
  "steps": 4,                                            // Default: 4 (schnell optimized)
  "cfg_scale": 1.0,                                      // Default: 1.0 (schnell optimized)
  "seed": -1,                                            // Default: -1 (random)
  "batch_size": 1                                        // Default: 1 (max: 8)
}

// Example usage
generate_image({
  prompt: "cyberpunk city at night, neon lights, detailed",
  steps: 4,
  seed: 42
})

2. upscale_image

Upscale images to 4x resolution using AI models.

// Parameters
{
  "image_path": "flux_output_00001_.png",  // Required
  "model": "ultrasharp",                   // Options: "ultrasharp", "animesharp"
  "scale_factor": 1.0,                     // Additional scaling (0.5-2.0)
  "content_type": "general"                // Auto-select model based on content
}

// Example usage
upscale_image({
  image_path: "output/my_image.png",
  model: "ultrasharp"
})

3. remove_background

Remove background using RMBG-2.0 AI model.

// Parameters
{
  "image_path": "output/image.png",  // Required
  "alpha_matting": true,              // Better edge quality (default: true)
  "output_format": "png"              // Options: "png", "webp"
}

// Example usage
remove_background({
  image_path: "flux_output_00001_.png"
})

4. check_models

Verify available models in ComfyUI.

// No parameters required
check_models()

5. connect_comfyui / disconnect_comfyui

Manage ComfyUI connection (usually auto-connects).

MCP Configuration

Add to Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "comfyui-flux": {
      "command": "wsl.exe",
      "args": [
        "bash", "-c",
        "cd /path/to/mcp-comfyui-flux && docker exec -i mcp-comfyui-flux-mcp-server-1 node /app/src/index.js"
      ]
    }
  }
}

For macOS/Linux:

{
  "mcpServers": {
    "comfyui-flux": {
      "command": "docker",
      "args": [
        "exec", "-i", "mcp-comfyui-flux-mcp-server-1",
        "node", "/app/src/index.js"
      ]
    }
  }
}

🐳 Docker Management

Service Commands

# Start services
docker-compose -p mcp-comfyui-flux up -d

# Stop services
docker-compose -p mcp-comfyui-flux down

# View logs
docker-compose -p mcp-comfyui-flux logs -f
docker-compose -p mcp-comfyui-flux logs -f comfyui

# Check status
docker-compose -p mcp-comfyui-flux ps

# Restart services
docker-compose -p mcp-comfyui-flux restart

Container Access

# Access ComfyUI container
docker exec -it mcp-comfyui-flux-comfyui-1 bash

# Access MCP server
docker exec -it mcp-comfyui-flux-mcp-server-1 sh

# Check GPU status
docker exec mcp-comfyui-flux-comfyui-1 nvidia-smi

# Test PyTorch
docker exec mcp-comfyui-flux-comfyui-1 python3.11 -c "import torch; print(f'PyTorch {torch.__version__}')"

Health Monitoring

# Full health check
./scripts/health-check.sh

# Check ComfyUI API
curl http://localhost:8188/system_stats

# Container health status
docker inspect mcp-comfyui-flux-comfyui-1 --format='{{.State.Health.Status}}'

πŸš€ Advanced Features

Performance Optimizations

The optimized build includes:

  • PyTorch 2.5.1: Latest stable with native RMSNorm support

  • BuildKit Cache Mounts: Reduces I/O operations in WSL2

  • FP8 Quantization: FLUX schnell fp8 uses ~10GB VRAM (vs 24GB fp16)

  • Multi-stage Builds: Separates build and runtime dependencies

  • Compiled Python: Pre-compiled bytecode for faster startup

FLUX Model Configurations

Schnell (Default - Fast)

  • Steps: 4 (optimized for schnell)

  • CFG Scale: 1.0 (works best with low guidance)

  • Scheduler: simple

  • Generation Time: ~2-4 seconds per image

  • VRAM Usage: ~10GB base + 1GB per batch

Dev (High Quality)

  • Steps: 20-50

  • CFG Scale: 7.0

  • Scheduler: normal/karras

  • Requires: Hugging Face authentication

  • VRAM Usage: ~12-16GB

Batch Generation

Generate multiple images efficiently:

generate_image({
  prompt: "fantasy landscape",
  batch_size: 4  // Generates 4 variations in parallel
})

Custom Nodes

Included custom nodes:

  • ComfyUI-Manager: Node management and updates

  • ComfyUI-KJNodes: Advanced processing nodes

  • ComfyUI-RMBG: Background removal (31 nodes)

πŸ”§ Troubleshooting

Common Issues

GPU Not Detected

# Verify NVIDIA driver
nvidia-smi

# Check Docker GPU support
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

# Ensure NVIDIA Container Toolkit is installed
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

Out of Memory

# Reduce batch size
batch_size: 1

# Use CPU mode (in .env)
CUDA_VISIBLE_DEVICES=-1

# Adjust PyTorch memory
PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:256

WSL2 Specific Issues

# If Docker/WSL2 crashes with I/O errors
# Avoid recursive chown on large directories
# Use the optimized Dockerfile which handles this

# Increase WSL2 memory in .wslconfig
memory=20GB

# Reset WSL2 if needed
wsl --shutdown

Port Conflicts

# Check what's using port 8188
lsof -i :8188  # macOS/Linux
netstat -ano | findstr :8188  # Windows

# Use different port
PORT=8189 docker-compose -p mcp-comfyui-flux up -d

Log Locations

  • Installation: install.log

  • Docker builds: docker-compose logs

  • ComfyUI: Inside container at /app/ComfyUI/user/comfyui.log

  • MCP Server: docker logs mcp-comfyui-flux-mcp-server-1

πŸ—οΈ Architecture

System Overview

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚      Claude Desktop (MCP Client)        β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
             β”‚ docker exec stdio
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚      MCP Server Container               β”‚
β”‚   β€’ Node.js 20 Alpine (581MB)          β”‚
β”‚   β€’ MCP Protocol Implementation        β”‚
β”‚   β€’ Auto-connects to ComfyUI           β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
             β”‚ WebSocket (port 8188)
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚      ComfyUI Container                  β”‚
β”‚   β€’ Ubuntu 22.04 + CUDA 12.1           β”‚
β”‚   β€’ Python 3.11 + PyTorch 2.5.1        β”‚
β”‚   β€’ FLUX schnell fp8 (4.5GB)           β”‚
β”‚   β€’ Custom nodes (KJNodes, RMBG)       β”‚
β”‚   β€’ Optimized image size: 10.9GB       β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Key Improvements

  1. Docker Optimization

    • Multi-stage builds reduce image size by 25%

    • BuildKit cache mounts speed up rebuilds

    • No Python venv (Docker IS the isolation)

  2. Model Configuration

    • FLUX schnell fp8: 4.5GB (vs 11GB fp16)

    • T5-XXL fp8: 4.9GB text encoder

    • CLIP-L: 235MB text encoder

    • VAE: 320MB decoder

  3. Performance

    • 4-step generation in 2-4 seconds

    • Batch processing up to 8 images

    • Native RMSNorm in PyTorch 2.5.1

    • High VRAM mode for 24GB+ GPUs

Directory Structure

mcp-comfyui-flux/
β”œβ”€β”€ src/                    # MCP server source
β”‚   β”œβ”€β”€ index.js           # MCP protocol handler
β”‚   β”œβ”€β”€ comfyui-client.js  # WebSocket client
β”‚   └── workflows/         # ComfyUI workflows
β”œβ”€β”€ models/                # Model storage
β”‚   β”œβ”€β”€ unet/             # FLUX models (fp8)
β”‚   β”œβ”€β”€ clip/             # Text encoders
β”‚   β”œβ”€β”€ vae/              # VAE models
β”‚   └── upscale_models/   # Upscaling models
β”œβ”€β”€ output/               # Generated images
β”œβ”€β”€ scripts/              # Utility scripts
β”œβ”€β”€ docker-compose.yml    # Service orchestration
β”œβ”€β”€ Dockerfile.comfyui    # Optimized ComfyUI
β”œβ”€β”€ Dockerfile.mcp        # MCP server
β”œβ”€β”€ requirements.txt      # Python dependencies
β”œβ”€β”€ build.sh             # Build script
└── install.sh           # Automated installer

πŸ”’ Security

  • Local Execution: All processing happens locally

  • No External APIs: Except model downloads from Hugging Face

  • Container Isolation: Services run in isolated containers

  • Non-root Execution: Containers run as non-root user

  • Token Security: Stored in .env (gitignored)

πŸ“„ Additional Documentation

🀝 Contributing

Contributions welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Submit a pull request

πŸ“ License

MIT License - see LICENSE file for details.

πŸ™ Acknowledgments

Made with ❀️ for efficient AI image generation

Available Tools

6 tools
check_modelsC

Check if Flux dev model is available in ComfyUI

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description lacks behavioral details beyond the basic function. It does not state whether the tool requires an active connection, what it returns (e.g., boolean, message), or any side effects. With no annotations, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no unnecessary words. It efficiently communicates the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is minimal and does not explain what the tool returns or how to interpret the result. Given no output schema, a bit more context about return values or examples would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so schema coverage is trivially 100%. The description does not add anything about parameters beyond the schema, but this is acceptable given no parameters exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'check' and the specific resource 'Flux dev model availability in ComfyUI'. It distinguishes this tool from siblings like 'generate_image' and 'connect_comfyui'. However, it could be slightly more specific about the output (e.g., boolean), so not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. While it is implied that one might check availability before generating, the description does not explicitly state usage context or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

connect_comfyuiC

Connect to ComfyUI server

ParametersJSON Schema
NameRequiredDescriptionDefault
server_addressNoComfyUI server address (default: 127.0.0.1:8188)127.0.0.1:8188

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavior. It only states 'Connect' without explaining side effects, state changes, authentication, or failure modes. This leaves the agent uncertain about what the tool does beyond establishing a connection.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. It is appropriately short for a simple connection tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having only one optional parameter, the description lacks important context such as whether the connection is persistent, returns a handle, or requires disconnection. Without an output schema, more detail is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the parameter already having a description. The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Connect' and the resource 'ComfyUI server', indicating a specific action. However, it does not distinguish this tool from siblings like 'disconnect_comfyui' or 'check_models'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool, such as prerequisites or that it should be called before other tools. There is no mention of alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

disconnect_comfyuiB

Disconnect from ComfyUI server

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description does not disclose any behavioral traits such as side effects (e.g., losing connection state), error conditions, or safety implications. It only states the action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that efficiently conveys the tool's purpose with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no annotations), the description is mostly complete. However, it could mention potential error states or prerequisites for a fully complete context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100%. The description adds no additional context about parameters, but the lack of parameters makes this adequate. A score of 3 is baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Disconnect from ComfyUI server' clearly specifies the action (disconnect) and the resource (ComfyUI server), distinguishing it from sibling tools like connect_comfyui.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool or when not to. There is no mention of prerequisites (e.g., being connected) or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageC

Generate an image using Flux dev model in ComfyUI

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoRandom seed for reproducibility (-1 for random)
stepsNoNumber of sampling steps
widthNoWidth of the generated image
heightNoHeight of the generated image
promptYesThe text prompt to generate an image from
cfg_scaleNoClassifier-free guidance scale
schedulerNoScheduler to usenormal
batch_sizeNoNumber of images to generate in parallel (1-4 recommended)
sampler_nameNoSampling method to useeuler
negative_promptNoNegative prompt to avoid certain features

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only says 'generate an image' without mentioning computational cost, time, or error handling. Minimal behavioral info.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, no wasted words. It efficiently conveys the core purpose, though it sacrifices detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters and no output schema or annotations, the description is insufficient. It does not explain return values, limitations, or how results are delivered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond what the schema provides; it is a single generic sentence.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates an image using the Flux dev model in ComfyUI, distinguishing it from sibling tools like 'check_models' or 'upscale_image'. However, it lacks specificity about the model's purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description only states the action without context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remove_backgroundC

Remove background from an image using AI-powered segmentation

ParametersJSON Schema
NameRequiredDescriptionDefault
image_pathYesPath to the input image file
alpha_mattingNoUse alpha matting for better edge quality (especially for hair/fur)
output_formatNoOutput image formatpng

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description should disclose behavioral aspects such as whether the input file is modified, where the output is saved, and any side effects. It only states the method without clarifying the outcome or operation side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence with clear action and method. No unnecessary words. Efficiently communicates the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fails to cover output details (e.g., where the result is saved, return value) and any constraints (e.g., file size limits, supported input formats). With three parameters and no annotations, more context is needed for full understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with adequate descriptions for each parameter (image_path, alpha_matting, output_format). The tool description adds no extra meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb-resource pair ('Remove background from an image') and mentions the AI method ('AI-powered segmentation'). It is clearly distinct from sibling tools like generate_image or upscale_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage context or alternatives are mentioned. The agent is not told when to prefer this tool over other image tools or any limitations (e.g., image size, supported formats).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upscale_imageC

Upscale an image using AI models

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoUpscaling model to useultrasharp
image_pathYesPath to the image file to upscale
content_typeNoContent type for auto model selectiongeneral
scale_factorNoAdditional scaling factor (1.0 = model native, usually 4x)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description is minimal and does not disclose any behavioral traits beyond the basic operation. There are no annotations, so the agent has no information about side effects (e.g., whether the original image is modified, what happens on failure). This is inadequate for a tool with 4 parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at 5 words, with no wasted sentences. However, it may be too minimal; a bit more detail could improve utility without sacrificing conciseness. Structure is front-loaded but sparse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of 4 parameters (including enum and scale factor) and no output schema, the description is incomplete. It does not explain what the tool returns (e.g., path to upscaled image) or any important context like supported image formats or resolution limits. The agent lacks key information to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter is already documented. The description adds no extra parameter-specific information beyond the schema. Baseline score of 3 is appropriate; the description provides no additional value to parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: upscaling an image using AI models. However, it does not differentiate from sibling tools like generate_image or remove_background, which could be confused with upscaling. The purpose is clear but lacks distinctiveness.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like check_models or generate_image. There is no mention of prerequisites (e.g., file format, size limits) or when not to use it. The usage context is entirely implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv1.0.0
    • First observedcheck_models
    • First observedconnect_comfyui
    • First observeddisconnect_comfyui
    • First observedgenerate_image
    • First observedremove_background
    • First observedupscale_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: model checking, connection management, image generation, and two distinct post-processing operations. No overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case, making them predictable and easy to understand.

Tool Count5/5

With 6 tools covering connection, model check, generation, and post-processing, the number is well-scoped for the server's purpose.

Completeness4/5

The tool set covers core workflows (connect, check, generate) and adds useful post-processing. Minor gap: only checks for one specific model; a general model listing could be useful.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers