# Connect SocialCutter to Claude Code over MCP
> Add the SocialCutter MCP server to Claude Code with .mcp.json or the CLI, the X-API-Key header, project approval and the user-scope header trap.
- URL: https://socialcutter.theboomer.dev/en/guides/claude-code/
- Idioma: en
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Claude Code, MCP, SocialCutter, X-API-Key, mcp.json, MCP server, API key
## What the SocialCutter MCP brings into Claude Code

Claude Code is Anthropic's terminal agent: it reads your repository, runs commands and edits files. Connect the SocialCutter MCP server and it gains **28 tools** for generating your image formats without leaving the session.

The server is already deployed and uses streamable HTTP:

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

Its identifier is `@theboomerdev/socialcutter-mcp` version **1.1.0**. SocialCutter accepts both headers: **`X-API-Key: sc_...`** and **`Authorization: Bearer sc_...`**. 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. No tool accepts the key as an argument, so the client has to support custom headers.

Before you have a key you can check the connection with the public tools: `list_platforms`, `list_formats`, `list_fit_modes`, `get_health`, `get_pricing_plans` and `get_credit_packs` answer without credentials. The rest — `process_image`, `process_batch`, `get_wallet`, `get_history` and the others — require the key.

## Where Claude Code reads the server list

Claude Code reads MCP servers from two places:

| Scope | File | Behaviour |
|---|---|---|
| Project | `.mcp.json` at the repository root | Can be versioned and shared with the team |
| User | `~/.claude.json` | Available across all your projects |

### Project file: .mcp.json

```json
{
  "mcpServers": {
    "socialcutter": {
      "type": "http",
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": { "X-API-Key": "sc_your_key" }
      // If your client only offers an Authorization field: { "Authorization": "Bearer sc_your_key" }
    }
  }
}
```

The `type` key is not decorative. An entry with `url` and **no `type`** is treated as a **stdio** server and will not connect: Claude Code replies with an error asking for `"type": "http"`. If you copy an example without that field, this is the first place to look.

### User scope: ~/.claude.json

The same `mcpServers` block works in `~/.claude.json` so SocialCutter is available in every project. There is, however, an important caveat with headers in that scope, covered below.

### Registering through the CLI

If you would rather not edit JSON by hand, let Claude Code write the entry:

```bash
claude mcp add --transport http socialcutter https://mcp.socialcutter.theboomer.dev/mcp \
  --header "X-API-Key: sc_your_key"
# Same result with the other header: --header "Authorization: Bearer sc_your_key"
```

The command registers the server with the HTTP transport and the custom header. Keep the key in a secrets manager rather than leaving it in your shell history on a shared machine.

## Approving project servers

Servers declared in `.mcp.json` belong to the project and **require interactive approval the first time**. The session shows you the list and you decide whether to trust them; until you approve, `claude mcp list` marks them as pending and the tools are unavailable.

Two points worth knowing:

- In non-interactive mode (`claude -p`) and in the SDK, project servers load without asking. That is convenient for automation, but it means the approval is not a barrier when a script launches the agent.
- A versioned project file carries the key into a shared file. If the repository is public or shared outside the team, use user scope or register the server through the CLI instead of leaving it written down.

## The custom-header issue in user scope

There is an open issue in the Claude Code repository (anthropics/claude-code#28293) about **custom headers not being forwarded in user scope**. The symptom is recognisable: the server shows up in the list, the public tools may answer, but the private ones return `401` because `X-API-Key` never arrives.

The workaround is to register the server with `claude mcp add --transport http` instead of editing `~/.claude.json` by hand, then check the result with `claude mcp list`. If it still fails in that scope, declare the server in the project `.mcp.json` and go through the interactive approval while the issue is resolved.

## Verifying with claude mcp list

```bash
claude mcp list
```

The listing shows each server with its transport and its status. What you want is `socialcutter` connected, not pending and not in error. Inside an interactive session the `/mcp` command shows the same detail.

For a functional test, ask for something that triggers a public tool:

> List the platforms and their formats with list_platforms.

If the answer comes back with the catalogue and its sizes, the transport and the connection are fine. Then ask for the wallet (`get_wallet`) to confirm the key is actually being sent, not just that the process starts.

## Three plain-language uses

| What you type in the session | Tool | What comes back |
|---|---|---|
| "Take the master https://example.com/master.jpg and generate all 13 destinations" | `process_image` | An `image_id` and one URL per destination |
| "Process these ten URLs in a batch" | `process_batch` | One result per image with its outputs |
| "How many uses do I have left?" | `get_credits` and `get_wallet` | Daily uses, bonus bag and balance |

The public catalogue has **6 platforms** and **13 destinations**, where a destination is a platform and format pair. Converting one master to all 13 destinations costs 13 uses, and Claude Code issues them in a single `process_image` call with the `destinations` array filled in: that tool requires `source_url` and `destinations`.

For batches, `process_batch` takes an `images` argument and handles several images at once; it still charges 1 use per destination. Before a large batch, ask for the wallet: `get_credits` reports the plan's uses and `get_wallet` the balance detail.

Remember the product's boundary: SocialCutter **generates the files**, it does not post to social networks and does not edit the image. Cropping is **centred**, with `cover`, `contain`, `fill` and `stretch` modes, and no content analysis. Output can be `webp`, `jpg` or `png` with quality from 1 to 100 (85 by default), and each image can be up to 5 MB.

## Common errors

| Symptom | Cause | Fix |
|---|---|---|
| `401: Invalid or expired authentication token` | The server receives no header at all | Check the entry has `headers` with `X-API-Key`; in user scope, re-register it with `claude mcp add` |
| `401: Invalid API key` | The key is mistyped or revoked | Confirm it starts with `sc_`, has no spaces or line breaks, and only one is active per account |
| The tools do not appear | The entry has `url` without `type`, so it is treated as stdio | Add `"type": "http"` or register with `--transport http` |
| The server shows as pending | It is a project server that was not approved | Grant the interactive approval and list again |
| It works in-session but fails in a script | The non-interactive process never approved the project server | Register the server in user scope or open it through the CLI |
| Connection or transport error | The endpoint is mistyped or the transport is not HTTP | The endpoint ends in `/mcp` and is not SSE |

## Next steps

- MCP overview: [Connect SocialCutter to your LLM or editor with MCP](/en/guides/mcp/)
- Code path: [Process images with the SocialCutter API using curl](/en/guides/curl/)
- Bigger picture: [Automating social media images: the 4 routes](/en/guides/automatizar-imagenes-redes-sociales/)
- API reference: https://docs.socialcutter.theboomer.dev