MCP Configuration

Configure the SpriteSynth MCP server for your specific AI assistant and environment.

Server Configuration

Claude Desktop

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spritesynth": {
      "command": "npx",
      "args": ["-y", "@spritesynth/mcp-server"],
      "env": {
        "SPRITESYNTH_API_KEY": "sk_live_xxx"
      }
    }
  }
}

Cursor

Config location: Settings > MCP > Add Server

{
  "name": "spritesynth",
  "command": "npx",
  "args": ["-y", "@spritesynth/mcp-server"],
  "env": {
    "SPRITESYNTH_API_KEY": "sk_live_xxx"
  }
}

Windsurf

Config location: Settings > MCP Servers

{
  "name": "spritesynth",
  "command": "npx",
  "args": ["-y", "@spritesynth/mcp-server"],
  "env": {
    "SPRITESYNTH_API_KEY": "sk_live_xxx"
  }
}

Cline (VS Code)

Config location: Cline Settings > MCP Servers

{
  "name": "spritesynth",
  "command": "npx",
  "args": ["-y", "@spritesynth/mcp-server"],
  "env": {
    "SPRITESYNTH_API_KEY": "sk_live_xxx"
  }
}

Environment Variables

Using a Custom Base URL

For self-hosted or staging environments:

{
  "env": {
    "SPRITESYNTH_API_KEY": "sk_test_xxx",
    "SPRITESYNTH_BASE_URL": "https://staging.spritesynth.com"
  }
}

Global Installation

If you prefer not to use npx on each startup:

npm install -g @spritesynth/mcp-server

Then use the installed binary directly:

{
  "mcpServers": {
    "spritesynth": {
      "command": "spritesynth-mcp",
      "env": {
        "SPRITESYNTH_API_KEY": "sk_live_xxx"
      }
    }
  }
}

Troubleshooting

MCP Server Not Connecting

1. Check Node.js version: Run node --version — requires 18+
2. Verify API key: Ensure key starts with sk_live_ or sk_test_
3. Check network: Verify https://spritesynth.com is accessible
4. Restart assistant: Quit and reopen Claude Desktop / Cursor / Windsurf after config changes

"Command not found" Error

If using global install, ensure npm global bin is in your PATH:

# Check npm global prefix
npm config get prefix

# Add to PATH if needed (macOS/Linux)
export PATH="$(npm config get prefix)/bin:$PATH"

Or switch to using npx:

{
  "command": "npx",
  "args": ["-y", "@spritesynth/mcp-server"]
}

"Unauthorized" / 401 Errors

• Verify your API key is valid and not revoked
• Check you're using the correct key prefix (sk_live_ for production)
• Generate a new key at spritesynth.com/account/api-keys

"Insufficient Credits" / 402 Errors

• Check your credit balance at spritesynth.com/account/billing
• Upgrade your plan if needed
• Generation costs vary by model (1-3 credits per generation)

Model Not Available

If a specific model fails:

• fast — Fast, always available
• slow — Balanced, always available

Try a different model or retry after a moment.

Rate Limited (429)

• Default rate limit: 60 requests per minute per API key
• Wait for the rate limit window to reset
• Reduce request frequency in automated workflows

Tool Not Appearing in AI Assistant

1. Ensure the MCP server config is valid JSON
2. Check for typos in the config file
3. Restart the AI assistant completely
4. Check the assistant's MCP/debug logs for connection errors

Debug Mode

Run the MCP server directly to see debug output:

SPRITESYNTH_API_KEY=sk_live_xxx npx -y @spritesynth/mcp-server

This shows connection logs and error messages from the server.