# Use SocialCutter from your LLM or editor with MCP
> Connect the SocialCutter MCP server to Claude, Cursor, VS Code or Windsurf. 28 tools to process images, check history, wallet and billing.
- URL: https://socialcutter.theboomer.dev/en/guides/mcp/
- Idioma: en
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: MCP, Model Context Protocol, SocialCutter, Claude Desktop, Cursor, VS Code, Windsurf, API key
## 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`:

```bash
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:

```json
{
  "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)

```json
{
  "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](/en/guides/claude-code/): the `.mcp.json` file and adding it from the CLI
- [Codex CLI](/en/guides/codex-cli/): the table in `~/.codex/config.toml`
- [Gemini CLI](/en/guides/gemini-cli/): `httpUrl` in `settings.json` (not `url`, which is SSE)
- [Cursor](/en/guides/cursor/): `.cursor/mcp.json`, shared with its CLI
- [Windsurf](/en/guides/windsurf/): Cascade's `mcp_config.json`
- [Cline](/en/guides/cline/): `streamableHttp` is required, otherwise it assumes SSE
- [Goose](/en/guides/goose/): the `streamable_http` extension in `config.yaml`
- [OpenCode](/en/guides/opencode/): `opencode.json` with `oauth: false`
- [Zed](/en/guides/zed/): the `context_servers` key
- [Aider](/en/guides/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)](/en/guides/curl/)
- API reference: https://docs.socialcutter.theboomer.dev
- Dashboard: https://dash.socialcutter.theboomer.dev