MCP Serv­er In­te­gra­tion

SnapiX sup­ports the Mod­el Con­text Pro­to­col (MCP) - an open stan­dard that lets AI as­sis­tants like Claude, VS Code Copi­lot, and oth­er LLM tools in­ter­act with ex­ter­nal ser­vices through a struc­tured API.

Our MCP serv­er en­ables AI agents to up­load, con­vert, gen­er­ate, and man­age im­ages and gal­leries pro­gram­mat­i­cal­ly - all through nat­ur­al lan­guage.

Contents

• Overview
  • Which Trans­port Should I Use?
• Quick Start - Lo­cal (stdio)
  • VS Code (Copi­lot)
  • Claude Desk­top
• Quick Start - Re­mote (HTTP)
  • VS Code (Copi­lot)
• Con­fig­u­ra­tion
• Avail­able Tools
• Re­sources
• Prompts
• Rate Lim­it­ing
• Cred­its & Quo­tas
• Pro­gram­mat­ic Us­age

Overview

The SnapiX MCP serv­er wraps the REST API and ex­pos­es it as MCP tools and re­sources. It is built on the SnapiX SDK - the of­fi­cial typed Type­Script client for the REST API. It can be used in two ways:

1. Lo­cal (stdio) - in­stall the npm pack­age and con­fig­ure your AI client to run it lo­cal­ly
2. Re­mote (HTTP) - point your AI client to our host­ed end­point at https://www.snapix.space/api/mcp

Both meth­ods re­quire a SnapiX API key. Get yours from the API Keys page. It re­quires free reg­is­tra­tion, but you can get a key with­out en­ter­ing any pay­ment de­tails.

Which Trans­port Should I Use?

We rec­om­mend us­ing the lo­cal (stdio) trans­port for the best ex­pe­ri­ence. Here's why:

• Lo­cal file up­loads: The stdio trans­port ex­pos­es an imageFilePath pa­ra­me­ter on the snapix_upload_image and snapix_generate_image tools. The MCP serv­er runs on your ma­chine, reads the file di­rect­ly from disk, and sends the bi­na­ry to the SnapiX API - no en­cod­ing over­head, no size lim­i­ta­tions from the pro­to­col.
• No base64 crash­es: The HTTP trans­port uses imageBase64 for lo­cal im­ages, which re­quires the AI client to pass the en­tire im­age as a base64 string through the JSON-RPC pro­to­col. For large im­ages (mul­ti-megabyte), this can cause per­for­mance is­sues or crash some MCP clients (e.g. VS Code).
• imageUrl re­quires pub­lic ac­cess: Both trans­ports sup­port imageUrl, but the SnapiX API serv­er fetch­es the im­age from the pro­vid­ed URL. This means localhost or lo­cal net­work URLs won't work - only pub­licly ac­ces­si­ble URLs are sup­port­ed.

Sce­nario	stdio	HTTP
Up­load a lo­cal file from disk	imageFilePath ✅	Not avail­able
Up­load from a pub­lic URL	imageUrl ✅	imageUrl ✅
Up­load lo­cal im­age with­out a URL	imageFilePath ✅	imageBase64 ⚠️ (risk of crash­es with large im­ages)
No lo­cal process re­quired	❌	✅

Quick Start - Lo­cal (stdio)

Add to your AI client con­fig­u­ra­tion:

VS Code (Copi­lot)

Add to your .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": {
      "type": "stdio",
      "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 Desk­top

Add to your Claude Desk­top con­fig (~/Library/Application Support/Claude/claude_desktop_config.json on ma­cOS):

{
  "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 - Re­mote (HTTP)

For clients that sup­port Stream­able HTTP trans­port, point to our host­ed end­point:

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

Pass your API key via the Authorization head­er:

Authorization: Bearer <your-api-key>

The re­mote end­point op­er­ates in state­less mode - no ses­sion per­sis­tence be­tween re­quests.

VS Code (Copi­lot)

Add to your .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": {
      "type": "http",
      "url": "https://www.snapix.space/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:SNAPIX_API_KEY}",
        "X-Snapix-Bucket-Key": "${input:SNAPIX_BUCKET_KEY}" // optional
      }
    }
  }
}

Con­fig­u­ra­tion

Vari­able	Re­quired	De­fault	De­scrip­tion
SNAPIX_API_KEY	Yes	-	Your SnapiX API key from the API Keys page
SNAPIX_BUCKET_KEY	No	pri­ma­ry buck­et	De­fault stor­age buck­et for up­loads, gen­er­ates, and gallery cre­ation
SNAPIX_LOG_LEVEL	No	warn	SDK log ver­bosi­ty: debug | info | warn | error | silent

Avail­able Tools

Tool	De­scrip­tion	Cred­its	Key Per­mis­sion
snapix_get_docs	Fetch SDK, API, MCP, or About doc­u­men­ta­tion	Free	None (pub­lic)
snapix_convert_image	Guid­ance tool - ex­plains how to con­vert im­ages us­ing the up­load tool	Free	None
snapix_upload_image	Up­load an im­age from URL or lo­cal file, op­tion­al­ly con­vert for­mat and re­size	1+	images-create
snapix_generate_image	Gen­er­ate an im­age from a text prompt, op­tion­al­ly guid­ed by a tem­plate im­age (Gem­i­ni AI)*	40+	images-generate
snapix_list_images	List im­ages with pag­i­na­tion and fil­ter­ing	Free	images-read
snapix_get_image	Get full de­tails for a sin­gle im­age	Free	images-read
snapix_update_image	Up­date im­age meta­da­ta, gallery as­sign­ments, or re­place/re-con­vert the im­age	Free†	images-update
snapix_delete_image	Per­ma­nent­ly delete an im­age	Free	images-delete
snapix_create_gallery	Cre­ate a new gallery, op­tion­al­ly with ex­ist­ing im­ages	Free	galleries-create
snapix_list_galleries	List all gal­leries	Free	galleries-read
snapix_get_gallery	Get gallery de­tails with all im­ages	Free	galleries-read
snapix_get_ungrouped_images	Get all im­ages not as­signed to any gallery	Free	galleries-read
snapix_update_gallery	Up­date gallery name or vis­i­bil­i­ty	Free	galleries-update
snapix_delete_gallery	Delete a gallery, op­tion­al­ly with all its im­ages	Free	galleries-delete / galleries-delete-with-images

• * snapix_generate_image re­quires a paid sub­scrip­tion. It ac­cepts a text prompt plus an op­tion­al tem­plate im­age (URL, lo­cal file path, or base64) and gen­er­ates an im­age us­ing Gem­i­ni AI.
• † snapix_update_image is free for meta­da­ta-only up­dates (name, de­scrip­tion, gal­leries). Costs 1+ App cred­its when formatOptions, resizeOptions, or a re­place­ment im­age source is pro­vid­ed.

Per­mis­sions are en­forced by the SnapiX API based on your API key con­fig­u­ra­tion - not at the tool lev­el. See API Key Per­mis­sions for the full list of avail­able per­mis­sions.

Re­sources

MCP Re­sources pro­vide pas­sive con­text that AI clients can pre-load with­out mak­ing ex­plic­it tool calls.

URI	De­scrip­tion
snapix://galleries	All gal­leries (name, id, vis­i­bil­i­ty, im­age count)
snapix://galleries/{galleryId}	Gallery de­tails with all im­ages and CDN URLs
snapix://images/ungrouped	All im­ages not as­signed to any gallery
snapix://images	Re­cent im­ages (first page) with meta­da­ta and CDN URLs
snapix://images/{imageId}	Full im­age meta­da­ta, vari­ants, di­men­sions, and CDN URLs

Prompts

MCP Prompts are in­ter­ac­tive work­flow tem­plates that AI clients can in­voke on de­mand. Clients that sup­port the MCP prompts ca­pa­bil­i­ty (VS Code Copi­lot, Claude, and oth­ers) ex­pose them as slash com­mands or se­lec­table ac­tions in the chat in­ter­face.

Prompt	De­scrip­tion
snapix_setup_sdk_core	Guid­ed set­up of @metalevel/snapix-sdk-core: reads live docs, in­stalls the pack­age with the de­tect­ed pack­age man­ag­er, and ap­pends SNAPIX_* en­vi­ron­ment vari­ables to the cor­rect .env file

In VS Code, type / in the Copi­lot chat pan­el and se­lect snapix_setup_sdk_core to run the work­flow in any project.

Rate Lim­it­ing

The MCP serv­er re­spects the same rate lim­its as the REST API. When a rate lim­it is hit (HTTP 429), the serv­er re­turns an MCP er­ror with a retryable flag, sig­nal­ing to the AI client that it should wait and retry the re­quest.

Cred­its & Quo­tas

• Free op­er­a­tions: list­ing, get­ting, up­dat­ing meta­da­ta, and delet­ing im­ages/gal­leries
• Cred­it-con­sum­ing op­er­a­tions: up­load­ing im­ages (1+ cred­its), gen­er­at­ing im­ages (40+ cred­its)
• Cred­it costs fol­low the same rules as the REST API
• When cred­its are ex­haust­ed, the serv­er re­turns a clear er­ror mes­sage

Pro­gram­mat­ic Us­age

createSnapixMcpServer cre­ates and re­turns a con­fig­ured McpServer in­stance. Use it to em­bed the MCP serv­er in your own trans­port lay­er:

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

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

handleStatelessRequest is used in­ter­nal­ly by SnapiX to pow­er the host­ed /api/mcp HTTP end­point. It cre­ates a fresh serv­er in­stance per re­quest and is not in­tend­ed as a gen­er­al-pur­pose pub­lic API:

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

// Internal usage - powers https://www.snapix.space/api/mcp
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,
  });
}