@metalevel/snapix-mcp-server

MCP server for SnapiX - image optimization, conversion, AI generation, and gallery management via the Model Context Protocol. Get a free API key and start using it with your AI clients today, no credits required!

Built on @metalevel/snapix-sdk-core - the official typed TypeScript SDK for the SnapiX REST API.

Quick Start - Local (stdio)

Add to your AI client configuration:

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "SNAPIX_API_KEY",
      "type": "promptString",
      "description": "SnapiX API key",
      "password": true
    },
    {
      "id": "SNAPIX_BUCKET_KEY",
      "type": "promptString",
      "description": "Custom bucket key, if you've setup one (optional)",
      "password": false
    }
  ],
  "servers": {
    "metalevel/snapix-mcp": {
      "command": "npx",
      "args": ["-y", "@metalevel/snapix-mcp-server"],
      "env": {
        "SNAPIX_API_KEY": "${input:SNAPIX_API_KEY}",
        "SNAPIX_BUCKET_KEY": "${input:SNAPIX_BUCKET_KEY}" // optional
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "metalevel/snapix-mcp": {
      "command": "npx",
      "args": ["-y", "@metalevel/snapix-mcp-server"],
      "env": {
        "SNAPIX_API_KEY": "your-api-key-here",
        "SNAPIX_BUCKET_KEY": "your-optional-custom-bucket-key"
      }
    }
  }
}

Quick Start - Remote (HTTP)

For clients that support Streamable HTTP transport, point to the hosted endpoint:

https://www.snapix.space/api/mcp

Pass your API key via the Authorization header:

Authorization: Bearer <your-api-key>

The remote endpoint is stateless - no session persistence between requests. It does not support imageFilePath; use imageBase64 for local images (with caution for large files) or imageUrl for publicly accessible URLs. See the full MCP docs for VS Code and Claude Desktop config examples.

Environment Variables

Variable	Required	Default	Description
SNAPIX_API_KEY	Yes	-	Your SnapiX API key
SNAPIX_BUCKET_KEY	No	primary bucket	Default storage bucket for uploads, generates, and gallery creation
SNAPIX_LOG_LEVEL	No	warn	SDK log verbosity: debug | info | warn | error | silent

Available Tools

Each tool carries MCP tool annotations that well-behaved clients (VS Code Copilot, Claude Desktop, etc.) use to show appropriate confirmation prompts. Because SnapiX retains no history and no soft-delete, every update or delete is irreversible — destructiveHint is set to true on all mutating tools accordingly.

Tool	Description	Credits	Read-only	Destructive	Idempotent	Open-world
snapix_get_docs	Fetch SDK, API, MCP, or About documentation	Free	✓	n/a	✓	–
snapix_convert_image	Guidance tool - explains how to convert images using the upload tool	Free	✓	n/a	✓	–
snapix_upload_image	Upload an image from URL or local file, optionally convert format and resize	1+	–	–	–	✓
snapix_generate_image	Generate an image from a text prompt, optionally guided by a template image (Gemini AI)*	40+	–	–	–	✓
snapix_list_images	List images with pagination and filtering	Free	✓	n/a	✓	–
snapix_get_image	Get full details for a single image	Free	✓	n/a	✓	–
snapix_update_image	Update image metadata, gallery assignments, or replace/re-convert the image	Free†	–	✓	–	✓
snapix_delete_image	Permanently delete an image	Free	–	✓	✓	–
snapix_create_gallery	Create a new gallery, optionally with existing images	Free	–	–	–	–
snapix_list_galleries	List all galleries	Free	✓	n/a	✓	–
snapix_get_gallery	Get gallery details with all images	Free	✓	n/a	✓	–
snapix_get_ungrouped_images	Get all images not assigned to any gallery	Free	✓	n/a	✓	–
snapix_update_gallery	Update gallery name or visibility	Free	–	✓	✓	–
snapix_delete_gallery	Delete a gallery, optionally with all its images	Free	–	✓	✓	–

• snapix_generate_image requires a paid subscription. Accepts a text prompt plus an optional template image (URL, local file path, or base64) and generates an image using Gemini AI.

† snapix_update_image is free for metadata-only updates. Costs 1+ App credits when formatOptions, resizeOptions, or a replacement image source is provided.

Resources

MCP Resources provide passive context that AI clients can pre-load without making explicit tool calls.

URI	Description
snapix://galleries	All galleries (name, id, visibility, image count)
snapix://galleries/{galleryId}	Gallery details with all images and CDN URLs
snapix://images/ungrouped	All images not assigned to any gallery
snapix://images	Recent images (first page) with metadata and CDN URLs
snapix://images/{imageId}	Full image metadata, variants, dimensions, and CDN URLs

Prompts

MCP Prompts are interactive workflow templates that AI clients can invoke on demand. Clients that support the MCP prompts capability (VS Code Copilot, Claude, and others) expose them as slash commands or selectable actions in the chat interface.

Prompt	Description
snapix_setup_sdk_core	Guided setup of @metalevel/snapix-sdk-core: reads live docs, installs the package with the detected package manager, and appends SNAPIX_* environment variables to the correct .env file

Rate Limiting

The MCP server respects the same rate limits as the REST API. When a rate limit is hit (HTTP 429), the server returns an MCP error with a retryable flag, signaling to the AI client that it should wait and retry the request.

Credits & Quotas

• Free operations: listing, getting, updating metadata, and deleting images/galleries
• Credit-consuming operations: uploading images (1+ credits), generating images (40+ credits)
• Credit costs follow the same rules as the REST API
• When credits are exhausted, the server returns a clear error message

Programmatic Usage

createSnapixMcpServer creates and returns a configured McpServer instance:

import { createSnapixMcpServer } from "@metalevel/snapix-mcp-server";

const server = createSnapixMcpServer({
  apiKey: process.env.SNAPIX_API_KEY!,
  baseUrl: "https://www.snapix.space",        // optional
  bucketKey: process.env.SNAPIX_BUCKET_KEY,   // optional
  logLevel: "warn",                           // optional: debug | info | warn | error | silent
  transport: "stdio",                         // optional: "stdio" (default) | "http"
});

handleStatelessRequest powers the hosted /api/mcp HTTP endpoint - it is designed for internal server-side usage and is not intended as a general-purpose public API:

import { handleStatelessRequest } from "@metalevel/snapix-mcp-server";

export async function POST(request: Request): Promise<Response> {
  return handleStatelessRequest(request, {
    apiKey: request.headers.get("Authorization")?.replace("Bearer ", "") ?? "",
    bucketKey: request.headers.get("X-Snapix-Bucket-Key") ?? undefined,
  });
}

Documentation

• Full MCP docs
• REST API docs
• Get API key

License

MIT