# MCP Servers Guide

> Comprehensive guide to MCP servers including PixelLab (async operations, asset download), ElevenLabs (cost warnings, tool selection), and Screenshot Analyzer workflows. Use when working with MCP servers for asset generation, audio processing, or screenshot analysis.

- Skill: `pmarashian/mcp-servers-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pmarashian/mcp-servers-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pmarashian/mcp-servers-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: pmarashian (https://skillmd.com/u/pmarashian)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/pmarashian/mcp-servers-guide

---


# MCP Servers Guide

This skill provides comprehensive guidance for working with MCP (Model Context Protocol) servers, including PixelLab, ElevenLabs, and Screenshot Analyzer.

## Overview

MCP servers provide specialized capabilities:
- **PixelLab**: Pixel art asset generation (characters, animations, tilesets)
- **ElevenLabs**: Audio processing (TTS, STT, voice cloning, music)
- **Screenshot Analyzer**: Visual analysis of screenshots

## PixelLab MCP Server

### Tools Available

- `create_character` - Generate pixel art characters
- `animate_character` - Create character animations
- `get_character` - Check character status and retrieve
- `list_characters` - List all created characters
- `delete_character` - Delete a character
- `create_topdown_tileset` - Generate top-down game tilesets
- `get_topdown_tileset` - Check tileset status
- `create_sidescroller_tileset` - Generate sidescroller tilesets
- `get_sidescroller_tileset` - Check sidescroller tileset status
- `create_isometric_tile` - Generate isometric tiles
- `get_isometric_tile` - Check isometric tile status
- `create_map_object` - Generate map objects with transparent backgrounds

### Critical: Non-Blocking Operations & Asset Download Workflow

**All creation tools return immediately with job IDs** - they process in the background (2-5 minutes). You MUST follow this complete workflow:

1. **Create**: Submit request → Get job ID instantly
2. **Wait**: Poll status using the appropriate `get_*` tool (e.g., `get_character`, `get_topdown_tileset`) until status is "completed"
3. **Download**: Use the download URL from the completed asset to download the file(s)
4. **Save**: Save downloaded files to appropriate locations in the codebase (e.g., `assets/`, `public/`, `src/assets/`, `public/images/`)
5. **Use Local Files**: Reference the local file paths in your code - NEVER use external URLs

### Async Operation Best Practices

**Polling Strategy:**
- Use exponential backoff: 5s → 10s → 20s → 40s intervals
- Respect API-provided ETAs when available
- Don't poll more frequently than every 5 seconds
- Stop polling when status === "completed"

**Download Validation:**
- ALWAYS verify status === "completed" before download
- Handle HTTP 423 (Locked) errors gracefully
- Don't attempt download until resource is ready

**Parallel Work:**
- Use waiting time for parallel work:
  - Code integration
  - Documentation
  - Test preparation
- Don't wait idly for async operations

**Timeout Handling:**
- Set maximum timeout (e.g., 5 minutes for character generation)
- Log progress and ETA for transparency
- Handle timeout errors gracefully

### Mandatory: All Assets Must Be Local Files

- **PROHIBITED**: Using external URLs from PixelLab download links in your code
- **REQUIRED**: Download all asset files and save them to the codebase
- **REQUIRED**: Use local file paths when referencing assets in code
- Save assets to project-appropriate directories:
  - Web projects: `public/`, `public/images/`, `src/assets/`, or `assets/`
  - Game projects: `assets/`, `src/assets/`, or project-specific asset directories
  - Check the project structure to determine the appropriate location

### Example Complete Workflow

```
1. create_character(...) → Returns character_id
2. get_character(character_id) → Check status, repeat until "completed"
3. Extract download URL from completed character data
4. Download ZIP/image files using the download URL
5. Save to codebase: assets/characters/character_name.zip or assets/characters/character_name.png
6. Reference in code: "./assets/characters/character_name.png" (NOT the external URL)
```

### Skill Reference

**When working with PixelLab tools:**
- Load the `pixellab-mcp` skill for complete documentation: `load_skill("pixellab-mcp")`
- The skill includes full API reference, workflows, examples, and best practices

## ElevenLabs MCP Server

### Tools Available

- `text_to_speech` - Convert text to speech
- `speech_to_text` - Transcribe audio to text
- `text_to_sound_effects` - Generate sound effects from text
- `voice_clone` - Clone voices from audio samples
- `create_agent` - Create conversational AI agents
- `compose_music` - Generate music from prompts
- `isolate_audio` - Isolate audio from files
- And more audio processing tools

### ⚠️ CRITICAL: AUDIO TOOLS ONLY - DO NOT USE FOR VISUAL ANALYSIS

- **NEVER** use ElevenLabs tools for screenshot analysis or visual tasks
- **NEVER** use `text_to_speech()` to "verbalize" or "speak about" screenshot content
- For visual analysis of screenshots, use `analyze_screenshot()` from Screenshot Analyzer MCP Server
- ElevenLabs tools are for AUDIO processing only: converting text to speech, speech to text, voice cloning, etc.
- If the task involves analyzing what you see in an image/screenshot, this is a VISUAL task requiring Screenshot Analyzer tools

### Critical: Cost Warnings

**MANY TOOLS INCUR API COSTS** - Only use when explicitly requested by the user:

- Text-to-Speech (TTS) operations
- Speech-to-Text (STT) operations
- Voice cloning
- Agent creation and conversations
- Music composition
- Audio processing
- Outbound phone calls

**Always check with the user before using cost-incurring tools** unless they explicitly request them.

### Skill Reference

**When working with ElevenLabs tools:**
- Load the `elevenlabs-mcp` skill for complete documentation: `load_skill("elevenlabs-mcp")`
- The skill includes full API reference, workflows, examples, parameters, and best practices
- Key capabilities: TTS with multiple voices/models, STT with diarization, voice cloning, conversational AI agents with knowledge bases, music composition, audio processing

## Screenshot Analyzer MCP Server

### Tools Available

- `analyze_screenshot(screenshot, prompt)` - Analyze screenshots with AI vision

### Screenshot Analyzer Workflow

1. **Load Skill**: Load the `screenshot-analysis` skill for complete documentation: `load_skill("screenshot-analysis")`
2. **Analyze**: Use `analyze_screenshot()` with a captured screenshot and custom analysis prompts

### When to Use Screenshot Analyzer

**MANDATORY**: Load the `screenshot-analysis` skill first: `load_skill("screenshot-analysis")`

The skill includes:
- Full API reference
- Workflows and examples
- Prompt crafting best practices
- Common use cases
- Cost optimization
- Error handling
- Workflow patterns

### ⚠️ CRITICAL: DO NOT USE ELEVENLABS TOOLS FOR VISUAL ANALYSIS

- **NEVER** use `text_to_speech()` or any ElevenLabs tool for screenshot analysis
- Screenshot analysis requires `analyze_screenshot()` - this is a VISUAL task, not an AUDIO task
- If you need to analyze what you see in a screenshot, use `analyze_screenshot()` from Screenshot Analyzer
- Only use ElevenLabs tools (`text_to_speech()`, `speech_to_text()`, etc.) for actual AUDIO processing tasks

### Tool Selection Examples

**✅ CORRECT: Screenshot Analysis Tasks**
- "Analyze this screenshot to see if the login button is visible" → `analyze_screenshot()`
- "Check if the error message appears on the page" → `analyze_screenshot()`
- "Describe what you see in this game screenshot" → `analyze_screenshot()`
- "Verify the UI layout matches the design" → `analyze_screenshot()`

**❌ INCORRECT: Using Audio Tools for Visual Tasks**
- "Analyze this screenshot to see if the login button is visible" → ~~`text_to_speech()`~~
- "Check if the error message appears on the page" → ~~`text_to_speech()`~~
- "Describe what you see in this game screenshot" → ~~`text_to_speech()`~~

**✅ CORRECT: Audio Processing Tasks**
- "Convert this text to speech" → `text_to_speech()`
- "Transcribe this audio file" → `speech_to_text()`
- "Create sound effects for the game" → `text_to_sound_effects()`
- "Clone this voice for the character" → `voice_clone()`

## Tool Selection Decision Framework

### Domain Validation

| Task Type | Correct Tool | ❌ Never Use |
|-----------|--------------|--------------|
| Analyze screenshot content | `analyze_screenshot()` | `text_to_speech()` |
| Check if UI element is visible | `analyze_screenshot()` | `text_to_speech()` |
| Describe what you see in image | `analyze_screenshot()` | `text_to_speech()` |
| Convert text to audio | `text_to_speech()` | `analyze_screenshot()` |
| Transcribe speech | `speech_to_text()` | `analyze_screenshot()` |
| Generate sound effects | `text_to_sound_effects()` | `analyze_screenshot()` |

### Key Principles

1. **Visual tasks** → Screenshot Analyzer
2. **Audio tasks** → ElevenLabs
3. **NEVER cross domains**: Visual ≠ Audio
4. **Cost awareness**: ElevenLabs costs money - Screenshot Analyzer is free

## Integration with Other Skills

This skill works with:

- **tool-selection-framework**: For comprehensive tool selection guidance
- **screenshot-handling**: For proper screenshot file management
- **asset-integration-workflow**: For integrating downloaded assets into projects