Use SocialCutter from your LLM or editor with MCP

What the SocialCutter MCP server is

MCP (Model Context Protocol) is an open protocol that lets a language model call tools on an external service. The SocialCutter MCP server exposes the API as 28 tools: process images, read history, wallet, coupons, API keys and billing.

With the server connected you do not write HTTP requests: you describe what you want in plain language and the model picks the tool and the parameters. The API is unchanged; MCP is an access layer on top of it.

• npm package: @theboomerdev/socialcutter-mcp, version 1.1.0.
• Tools: 28.
• Measured speed: about 0.2 s per image and format.
• Cost: 1 use per destination (platform and format pair).

Two connection modes

Remote mode (recommended)

The server is already deployed at:

https://mcp.socialcutter.theboomer.dev/mcp

Nothing to install or update. The key travels with each request from your client: no global key is stored on the server. The transport is streamable HTTP.

Local mode (stdio)

If your client does not support remote servers, run the package through npx:

npx @theboomerdev/socialcutter-mcp

The process reads two environment variables on start:

Variable	Value
SOCIALCUTTER_API_URL	https://api.socialcutter.theboomer.dev
SOCIALCUTTER_API_KEY	your sc_... key

In this mode the client launches the process and the process talks to the API with your key.

Create the API key and send it

1. Open the dashboard: https://dash.socialcutter.theboomer.dev
2. Go to Profile → API keys.
3. Create a key. The secret starts with sc_ and is shown only once.
4. Store it in a secrets manager.

Each request carries the key in a header:

• X-API-Key: sc_... (preferred)
• Authorization: Bearer sc_... (alias)

SocialCutter accepts both headers. Use whichever your client documents; the result is identical. A Bearer without the sc_ prefix is treated as a session token and will return 401.

Only one active key per account is allowed. If you try to create another one, the API returns error 400: revoke the previous key first.

Configuration examples

Note: file paths, JSON key names and remote server support change between client versions. Check your client’s documentation for the exact format. The examples below are the common shape.

Local mode with npx (stdio clients)

In the client configuration file:

{
  "mcpServers": {
    "socialcutter": {
      "command": "npx",
      "args": ["-y", "@theboomerdev/socialcutter-mcp"],
      "env": {
        "SOCIALCUTTER_API_URL": "https://api.socialcutter.theboomer.dev",
        "SOCIALCUTTER_API_KEY": "sc_your_key"
      }
    }
  }
}

Remote mode (clients with HTTP support)

{
  "mcpServers": {
    "socialcutter": {
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": {
        "X-API-Key": "sc_your_key"
        // same auth: "Authorization": "Bearer sc_your_key"
      }
    }
  }
}

Common configuration file paths:

Client	Typical path
Claude Desktop	claude_desktop_config.json
Cursor	.cursor/mcp.json (project) or ~/.cursor/mcp.json
VS Code	.vscode/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json

Plain-language examples

What you ask	Tool involved	What comes back
“Process this image for Instagram post and TikTok cover”	process_image (URL) or process_upload_file (file)	An image_id and one URL per destination
“How many uses do I have left?”	get_credits and get_wallet	Daily uses, bonus bag and purchased balance
“List the last 10 items in my history”	get_history	The last 10 images with their origin

Most useful tools

Tool	What it does	Endpoint
process_image	Process an image from a URL	POST /api/v1/images/process
process_upload_file	Process a local file (multipart)	POST /api/v1/images/process/upload
process_batch	Process several images in one call	POST /api/v1/images/batch
get_image	Retrieve a previous job	GET /api/v1/images/{image_id}
list_platforms	Platforms and formats with sizes	GET /api/v1/platforms
list_formats	Supported output formats	GET /api/v1/formats
list_fit_modes	Available fit modes	GET /api/v1/fit-modes
get_history	History of processed images	GET /api/v1/history
get_credits / get_wallet	Uses and wallet	GET /api/v1/credits, GET /api/v1/wallet
get_health	Service status	GET /api/v1/health
auth_me	Identity of the authenticated account	GET /api/v1/auth/me

The remaining tools cover coupons, API keys and billing.

Good practices

• Never paste the key into the chat. The model does not need to see it: it belongs in the client configuration or the environment variable.
• Watch the wallet before large batches with get_credits and get_wallet.
• Remember the billing unit: 1 use per destination (platform and format). Two destinations in one request cost 2 uses.
• Upload limit: 5 MB per file.
• Use process_batch for batches instead of many separate calls.

Common problems

Symptom	Cause	Fix
Error 401	Missing, malformed or revoked key	Check it starts with sc_ and the header is X-API-Key or Authorization: Bearer sc_... (a Bearer without sc_ is treated as a session token)
Error 429	Wallet quota exhausted	Check get_credits, then buy a pack or upgrade the plan
Error 413	The file is over 5 MB	Shrink the image before uploading
The client shows no tools	Configuration not read or wrong path	Restart the client and confirm the format in its documentation

Guides per client

The server is the same for everyone: what changes is where you declare it. These guides give the exact configuration file path, a snippet ready to copy and each client’s pitfalls:

• Claude Code: the .mcp.json file and adding it from the CLI
• Codex CLI: the table in ~/.codex/config.toml
• Gemini CLI: httpUrl in settings.json (not url, which is SSE)
• Cursor: .cursor/mcp.json, shared with its CLI
• Windsurf: Cascade’s mcp_config.json
• Cline: streamableHttp is required, otherwise it assumes SSE
• Goose: the streamable_http extension in config.yaml
• OpenCode: opencode.json with oauth: false
• Zed: the context_servers key
• Aider: it has no MCP; call the REST API from its commands

Next steps

• Terminal guide: Process images with the API from the terminal (curl)
• API reference: https://docs.socialcutter.theboomer.dev
• Dashboard: https://dash.socialcutter.theboomer.dev