---
title: MCP Server Documentation
url: https://merchloom.ai/docs/mcp
---

# MCP Server Documentation

Connect AI assistants to MerchLoom for automated batch image processing.

MerchLoom exposes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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](https://merchloom.ai/account) page. Include it as a Bearer token in every request:

Authorization: Bearer ml_live_...

### 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](https://merchloom.ai/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

[View pricing plans →](https://merchloom.ai/pricing)

## 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.

1. Generate an API key in your [Account](https://merchloom.ai/account) page
2. Run:claude mcp add --transport http merchloom \ https://api.merchloom.ai/mcp/ \ --header "Authorization: Bearer YOUR_KEY"
3. Or use OAuth (run /mcp in Claude Code and sign in):claude mcp add --transport http merchloom https://api.merchloom.ai/mcp/
4. Start using: "Remove backgrounds from all images in ~/products/"

### Cursor

1. Generate an API key in your [MerchLoom account](https://merchloom.ai/account)
2. 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](mailto:support@merchloom.ai).