# Connect SocialCutter to Gemini CLI over MCP
> Register the SocialCutter MCP server in Gemini CLI with httpUrl, timeout and trust. CLI setup, a check that costs no uses, and common errors.
- URL: https://socialcutter.theboomer.dev/en/guides/gemini-cli/
- Idioma: en
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Gemini CLI, MCP, SocialCutter, httpUrl, settings.json, X-API-Key, API key
## 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`.

```json
"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`:

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

```bash
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](/en/guides/mcp/)
- Code path: [Process images with the API from curl](/en/guides/curl/) and [from Python](/en/guides/python/)
- Big picture: [Automating social media images: the 4 paths](/en/guides/automatizar-imagenes-redes-sociales/)
- API reference: https://docs.socialcutter.theboomer.dev