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 Account 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.15–$0.40/img | Prompt-driven editing: reframe to any aspect ratio, place products in scenes, change colors, extend canvas, swap backgrounds. Combine mode: $0.40–$0.80 per result. |
| 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).
Rates are in dollars. Bundles put more on your balance than you pay — 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 the cost of a job given file count, operations, and average dimensions. |
| get_credit_balance | Check your available 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. |
| 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
Your balance
- Each service has a per-file cost (see services table above)
- Multi-step pipelines: cost = sum of all step costs × file count
- Top up your balance to start processing
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 Account page
- Run:claude mcp add --transport http merchloom \ https://api.merchloom.ai/mcp/ \ --header "Authorization: Bearer YOUR_KEY"
- Or use OAuth (run /mcp in Claude Code and sign in):claude mcp add --transport http merchloom https://api.merchloom.ai/mcp/
- Start using: "Remove backgrounds from all images in ~/products/"
Cursor
- Generate an API key in your MerchLoom account
- 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.