Connect SocialCutter to Claude Code over MCP

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

{
  "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:

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

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
• Code path: Process images with the SocialCutter API using curl
• Bigger picture: Automating social media images: the 4 routes
• API reference: https://docs.socialcutter.theboomer.dev