MCP Server Documentation
Connect AI assistants to MerchLoom for automated batch image processing.
MerchLoom exposes an MCP (Model Context Protocol) server that lets AI assistants — Claude, ChatGPT, Cursor, and any MCP-compatible client — process images on your behalf. Remove backgrounds, AI-edit with natural language prompts, and upscale product photos at scale, all through conversational AI.
Endpoint
URL: https://api.merchloom.ai/mcp/
Transport: Streamable HTTP (MCP specification)
Authentication
Two authentication methods are supported:
API Key (Cursor, custom clients)
Generate an API key in your Profile page. Include it as a Bearer token in every request:
OAuth 2.1 (Claude Desktop, ChatGPT)
Claude Desktop and ChatGPT use OAuth 2.1 with PKCE for automatic authentication. When you add MerchLoom as a connection, the client handles the OAuth flow — you just log in and approve access.
Discovery: https://api.merchloom.ai/.well-known/oauth-protected-resource
Authorization: https://api.merchloom.ai/auth/mcp/authorize
Token: https://api.merchloom.ai/auth/mcp/token
Registration: https://api.merchloom.ai/auth/mcp/register
PKCE: Required (S256 only)
Scope: mcp:tools
Available Services
| Service | ID | Cost | Description |
|---|---|---|---|
| Background Removal | bg_remove | $0.08/img | Remove backgrounds, output transparent PNG. Multiple AI models for different product types. |
| AI Editing | edit_ai | $0.12–0.32/img | Prompt-driven editing: reframe to any aspect ratio, place products in scenes, change colors, extend canvas, swap backgrounds. Multi-image fusion mode: $0.30–0.60/img. |
| AI Upscaling | upscale | $0.08/MP | 1x–200x upscaling with AI detail enhancement. Per-megapixel pricing — remove backgrounds first to shrink images and save up to 87%. |
Pipeline steps are auto-ordered for cost optimization: bg_remove (early) → edit_ai (middle) → upscale (middle).
List rates at 1 credit = $1. Credit packs bring effective prices 15–33% lower — see pricing.
MCP Tools (14)
The MCP server exposes 14 tools, split into read-only queries and mutating actions.
Read-Only
| Tool | Description |
|---|---|
| recommend_pipeline | Get service catalog, costs, settings, and pipeline planning guide. Call this first. |
| list_services | List services with IDs, costs, settings schemas, and ordering categories. |
| estimate_cost | Estimate credits for a job given file count, operations, and average dimensions. |
| get_credit_balance | Check your available credit balance. |
| get_job_status | Poll job progress — status, percentage, ETA, current pipeline step. |
| get_results | Get download URLs for completed job files (valid for 1 hour). |
| get_recent_jobs | List recent jobs, optionally filtered by status. |
| download_result | Download a specific result file. Returns image data directly through the API. |
Mutating
| Tool | Description |
|---|---|
| configure_pipeline | Validate and auto-order pipeline steps. Returns pipeline dict for submit_job. |
| get_upload_url | Get a signed upload URL for one file. Returns file_key for submit_job. |
| get_upload_urls | Batch: get signed upload URLs for multiple files in one call. Returns file_keys + a parallel bash script. |
| submit_job | Submit images for processing. Returns job_id for tracking. |
| cancel_job | Cancel a running or queued job. Unprocessed file credits are refunded. |
| retry_job | Retry a failed job. |
Typical Workflow
1. recommend_pipeline(use_case="product photos for Amazon")
2. configure_pipeline(steps=[{"operation": "bg_remove"}, {"operation": "upscale"}])
3. estimate_cost(file_count=50, operations=["bg_remove", "upscale"])
4. get_credit_balance()
5. submit_job(pipeline=..., file_urls=["https://..."])
6. get_job_status(job_id=...) // poll every 10-15 seconds
7. get_results(job_id=...) // when status == "completed"
8. Download files from returned URLs
File Input Methods
| Method | When to Use | How |
|---|---|---|
| file_urls | Images accessible via public HTTPS URLs | Pass URLs directly to submit_job |
| file_keys | Local files or large images (>2MB) | Call get_upload_url → PUT bytes → pass file_key to submit_job |
| file_images | Tiny images only (<2KB after base64) | Pass base64 strings to submit_job |
Limits & Polling
- Maximum 200 files per job via MCP
- Upload URLs expire in 5 minutes
- Result download URLs expire in 1 hour
- Poll get_job_status every 10–15 seconds (not more frequently)
- Job statuses: pending → processing → completed | failed | cancelled
Credits
- 1 MerchLoom Credit (MC) = $1 USD
- Each service has a per-file cost (see services table above)
- Multi-step pipelines: cost = sum of all step costs × file count
- Credits are reserved on submit, refunded on cancel for unprocessed files
- Purchase credits to start processing (1 MC = $1 USD)
Example Use Cases
Clean product photos for Amazon
Remove backgrounds and upscale 50 product images. Background removal runs first to shrink file sizes, saving up to 87% on upscaling costs.
configure_pipeline(steps=[{"operation": "bg_remove"}, {"operation": "upscale"}])
submit_job(pipeline=..., file_urls=[...])
Reframe products to square for Instagram
AI extends backgrounds naturally to fit 1:1 aspect ratio — no cropping, no distortion.
configure_pipeline(steps=[{"operation": "edit_ai", "settings": {"prompt": "Extend canvas to square 1:1. Preserve subject exactly.", "aspect_ratio": "1:1"}}])
Scene placement for Shopify
Place products on lifestyle backgrounds and upscale for web.
configure_pipeline(steps=[
{"operation": "edit_ai", "settings": {"prompt": "Place product on a marble countertop with natural light."}},
{"operation": "upscale"}
])
Quick Setup
Claude Code (recommended)
Claude Code has full bash access — upload and download files directly via curl. The fastest way to process images at scale.
- Generate an API key in your Profile page
- Run:claude mcp add merchloom -- npx -y mcp-remote \ https://api.merchloom.ai/mcp/ \ --header "Authorization:Bearer YOUR_KEY"
- Or use OAuth (opens browser to log in):claude mcp add merchloom -- npx -y mcp-remote \ https://api.merchloom.ai/mcp/
- Start using: "Remove backgrounds from all images in ~/products/"
Cursor
- Generate an API key in your MerchLoom profile
- In Cursor settings, add MCP server with URL: https://api.merchloom.ai/mcp/ and your API key as Bearer token
Other MCP Clients
Any MCP client with bash/shell access can use MerchLoom. Connect via https://api.merchloom.ai/mcp/ with OAuth 2.1 or API key Bearer token. The client needs network access to api.merchloom.ai for file uploads and downloads.
Support
Questions or issues? Contact us at support@merchloom.ai.