Connect SocialCutter to Gemini CLI over MCP

What connecting over MCP gives you

Gemini CLI talks to external services through MCP (Model Context Protocol). With the SocialCutter server registered you do not write HTTP requests or maintain scripts: you describe what you want in plain language and the model picks the tool and its parameters. The server exposes 28 tools over the same API: process images, read history, wallet, coupons, keys and billing.

Using an agent does not change the product’s boundary. SocialCutter generates the files at the size each platform and format needs; it does not post to social networks and does not edit the image. The crop is centred, with the cover, contain, fill and stretch modes, and output is served as webp, jpg or png.

Item	Value
Endpoint	https://mcp.socialcutter.theboomer.dev/mcp
Transport	streamable HTTP (not SSE)
Authentication	X-API-Key: sc_... or Authorization: Bearer sc_...
Tools	28 (6 public, no credentials)
Cost	1 use per destination

The right header

Before touching the file, settle this: SocialCutter accepts both headers, X-API-Key: sc_... and Authorization: Bearer sc_..., and you can use whichever your client documents because the result is identical. The sc_ prefix is what decides the route: a Bearer whose value does not start with sc_ is treated as a session token, and the private tools answer 401: Invalid or expired authentication token.

"headers": { "X-API-Key": "sc_your_key" }
// also works: "headers": { "Authorization": "Bearer sc_your_key" }

No tool accepts the key as an argument. Authentication always travels in the header, which is why the client you configure must support custom headers. Gemini CLI does.

The transport trap: httpUrl, not url

This is the most common confusion when registering an HTTP server in Gemini CLI, and Google documents it: there are three different keys for three different transports, and you set only one.

Key	Transport
httpUrl	streamable HTTP, our case
url	SSE (the older transport)
command	local process over stdio

If you put an HTTP server’s address in url, Gemini CLI tries to speak SSE to an endpoint that does not serve it. The usual outcome is not a clear error: the server shows up in the list with no tools at all, as if it were alive but empty. Move the address to httpUrl, drop the other two keys and restart.

Configuration in ~/.gemini/settings.json

The user file lives at ~/.gemini/settings.json. A project-scoped .gemini/settings.json is also supported. The entry goes under mcpServers:

{
  "mcpServers": {
    "socialcutter": {
      "httpUrl": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": { "X-API-Key": "sc_your_key" },
      // if your client only offers Authorization: "headers": { "Authorization": "Bearer sc_your_key" },
      "timeout": 30000,
      "trust": true
    }
  }
}

Three fields worth tuning:

• timeout. Measured in milliseconds. The default is 600000 (ten minutes), meant for local processes that start slowly. For a remote server that answers right away that is a huge margin: 30000 gives thirty seconds per call, enough for a batch without leaving the session hanging if the network drops.
• trust. With trust: true the server’s tools run without a confirmation prompt for each one. On a trusted server like this one it spares you a string of prompts per image; you stop approving process_image, get_credits and the rest every time.
• Allowlist and denylist. The mcp.allowed and mcp.excluded keys limit which servers Gemini CLI may use at all. They are the practical way to leave only socialcutter on a shared machine, or to block it entirely in an environment where you want no external tools.

Adding it from the command line

If you would rather not edit the JSON by hand, Gemini CLI ships its own command:

gemini mcp add --transport http socialcutter \
  https://mcp.socialcutter.theboomer.dev/mcp \
  --header "X-API-Key: sc_your_key"

The --transport http flag is what marks the correct transport and avoids the httpUrl trap outright. The command writes the entry into your configuration for you. It also works as a second path when something does not add up: if hand-editing the file gets you nowhere, adding it with gemini mcp add usually leaves the JSON in the shape the tool expects.

Why we do not use the interactive OAuth flow

Gemini CLI can authenticate remote MCP servers over OAuth with /mcp auth. That flow opens a browser and starts a local server to receive the callback at http://localhost:<port>/oauth/callback. On a laptop with a graphical desktop it works; on a headless server, in a container or inside a build pipeline there is no browser to open and no way to complete the callback, so the flow just waits.

Our server does not need it. Authentication is a static header you write once in the configuration file. That makes the connection reproducible, templatable in a versioned file and valid for an automated environment, with no interactive session and no browser.

Checking that it is connected

Restart Gemini CLI after editing the file. To confirm the connection without spending uses, ask for one of the public tools:

What you ask	Tool	What it confirms
“List the platforms and formats”	list_platforms	Transport and tool discovery
“Is the service up?”	get_health	Reaching the server
“How many uses do I have left?”	get_credits and get_wallet	A valid X-API-Key header

The first two rows answer without credentials: if list_platforms returns the catalogue, the transport is fine even if the key is not valid yet. The third is what confirms the header. If the catalogue arrives but the balance does not, the problem is the key, not the transport.

Common errors

Symptom	Cause	Fix
401: Invalid or expired authentication token	No header reaches the server, or an Authorization: Bearer whose value does not start with sc_ (treated as a session token)	Send your sc_... key in X-API-Key or in Authorization: Bearer sc_...
401: Invalid API key	The key is mistyped, expired or revoked	Create a new one under Profile → API keys
The server shows up with no tools	The HTTP endpoint sits in url (SSE) instead of httpUrl	Move the address to httpUrl and remove url or command
The server is not listed at all	Malformed JSON, trailing comma, or the file is elsewhere	Validate the JSON and confirm ~/.gemini/settings.json
The server is excluded although it is in the file	mcp.allowed does not list it or mcp.excluded blocks it	Review both lists
A large batch gets cut off	timeout too low for the batch	Raise the timeout in milliseconds
Nothing responds on a headless machine	You tried the interactive OAuth flow	Use the static X-API-Key header

Limits worth remembering

• 5 MB per image. Above that size the API returns 413.
• 1 use per destination (platform and format). Check the wallet with get_credits before a batch.
• 13 destinations across 6 platforms. The public catalogue from list_platforms is the source, not a list pasted into the prompt.
• For batches, process_batch in a single call beats many separate calls.

Next steps

• Agents hub: Use SocialCutter from your LLM or editor with MCP
• Code path: Process images with the API from curl and from Python
• Big picture: Automating social media images: the 4 paths
• API reference: https://docs.socialcutter.theboomer.dev