# SocialCutter as a Goose MCP extension
> Add SocialCutter to Goose as a streamable_http extension: config.yaml, the X-API-Key header, secrets in the system keyring and the errors you will hit.
- URL: https://socialcutter.theboomer.dev/en/guides/goose/
- Idioma: en
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Goose, Block Goose, MCP, streamable_http, X-API-Key, extensions, config.yaml, SocialCutter
## What Goose adds when you connect an MCP server

Goose is an open-source agent from Block that runs in your terminal or in its desktop app and works through **extensions**: each extension adds a set of tools the model can call. The SocialCutter MCP server comes in through that door, so a single configuration entry lets you ask for an image's formats in plain language instead of writing HTTP requests.

Set the boundary first: SocialCutter **creates the files, it does not publish**. It takes an image, centre-crops it to the exact size of each platform and format, and returns one URL per output. It does not analyse the image content and it does not edit the original: it fits the central area according to the chosen mode. Publishing or moving those files is up to the caller. The cost is **1 use per destination**, meaning one platform and format pair.

The server details you need:

| Item | Value |
|---|---|
| Endpoint | `https://mcp.socialcutter.theboomer.dev/mcp` |
| Transport | Streamable HTTP |
| Tools | 28 |
| Auth header | `X-API-Key: sc_...` or `Authorization: Bearer sc_...` |
| Public tools | `list_platforms`, `list_formats`, `list_fit_modes`, `get_health`, `get_pricing_plans`, `get_credit_packs` |

If this is your first connection, start with [the SocialCutter MCP server guide](/en/guides/mcp/), which covers the 28 tools and the connection modes.

## The file: config.yaml under the extensions key

Goose keeps everything in one YAML file and servers are declared under the root key **`extensions`**:

| System | File path |
|---|---|
| Linux and macOS | `~/.config/goose/config.yaml` |
| Windows | `%APPDATA%\Block\goose\config\config.yaml` |

The SocialCutter entry:

```yaml
extensions:
  socialcutter:
    type: streamable_http
    name: socialcutter
    enabled: true
    uri: "https://mcp.socialcutter.theboomer.dev/mcp"
    headers:
      X-API-Key: "sc_your_key"
      # authenticates the same: Authorization: "Bearer sc_your_key"
    env_keys: []
    envs: {}
    timeout: 300
```

`sc_your_key` is a placeholder for the key you created in the dashboard. Goose forwards whatever you put in `headers` verbatim, and SocialCutter accepts both headers (`X-API-Key: sc_...` and `Authorization: Bearer sc_...`), so 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. That form, with the value written out, is fine for a first local test. The clean form, with no secret in the file, comes further down.

### Field by field

| Field | What it is for |
|---|---|
| `type` | Extension transport. Here `streamable_http`, which is what our endpoint speaks |
| `name` | Name the extension shows up under in the session |
| `enabled` | Whether it is active. To turn it off without deleting it, set it to `false` |
| `uri` | URL of the remote MCP server |
| `headers` | Headers Goose forwards on every request; `X-API-Key` or `Authorization: Bearer` travels here |
| `env_keys` | Names of the variables whose values are kept in the system keyring |
| `envs` | Non-secret variables, written straight into the file |
| `timeout` | Seconds to wait before giving a call up as lost |

## SSE is retired: migrate to streamable_http

If you are carrying an old entry with `type: sse`, it will not work: **SSE is retired in Goose** and the transport in use today is `streamable_http`. The migration is changing the type and keeping the same `uri`:

```diff
 extensions:
   socialcutter:
-    type: sse
+    type: streamable_http
     uri: "https://mcp.socialcutter.theboomer.dev/mcp"
```

Our endpoint serves streamable HTTP, so an extension configured for SSE ends up with no tools even when the URL is right. This is the first thing to check when Goose says it cannot find any SocialCutter tool.

## Add it without editing the file by hand

There are two paths besides editing the YAML. For a one-off test:

```bash
goose session --with-streamable-http-extension "https://mcp.socialcutter.theboomer.dev/mcp"
```

That starts a session with the extension loaded for that run only, without touching anything. To keep it:

```bash
goose configure
```

Pick **Remote Extension (Streamable HTTP)** in the wizard and paste the URL. Goose writes the entry for you, which is also the safest way to see the exact shape your version expects.

## Secrets belong in the keyring, not the file

`config.yaml` is a file that ends up in a repository more often than it should. The clean way in Goose is to leave the key out: declare its **name** in `env_keys` and keep the value in the **system keyring** (Keychain on macOS, the desktop secret store on Linux, Credential Manager on Windows). `env_keys` is the list of variables the extension has to read from there:

```yaml
    headers:
      X-API-Key: "sc_your_key"
      # or Authorization: "Bearer sc_your_key"
    env_keys:
      - SOCIALCUTTER_API_KEY
```

The value of `SOCIALCUTTER_API_KEY` stays outside the file, so you can version the configuration without leaking anything. The wizard confirms the exact variable name and format your version expects: if the entry you saved does not look right, run `goose configure` again before hand-editing the YAML.

## Verify the connection

The public tools answer **without a key**, so they are the way to check the setup before creating credentials:

- "List the platforms and their formats" → `list_platforms`
- "Is the service up?" → `get_health`
- "Which fit modes exist and what do the plans cost?" → `list_fit_modes`, `get_pricing_plans`

With the key in place, a business question confirms authentication: "how many uses do I have left?" goes through `get_credits` and `get_wallet`. If it answers with your balance, the extension is wired up correctly.

## What you usually ask from the session

| What you ask | Tool | 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 |
| "Send these three to every square feed format" | `process_batch` | One result per image in the batch |
| "How many uses do I have left?" | `get_credits` and `get_wallet` | Daily uses, bonus bag and purchased balance |
| "Show me the last ten" | `get_history` | The ten most recent images with their origin |
| "Which formats does LinkedIn have?" | `list_platforms` | Platforms, formats and sizes |

## Limits and cost

- **1 use per destination** (platform and format). Remember that 13 destinations for one image are 13 uses.
- **5 MB** per image, both for the URL variant and for a file upload.
- Output as `webp`, `jpg` or `png`, quality 1 to 100, 85 by default.
- Fit modes `cover`, `contain`, `fill` and `stretch`, all centre-cropped.
- **6 platforms and 13 destinations** in the public catalogue; there is no 4:5.

## Common errors

| Symptom | Cause | Fix |
|---|---|---|
| `401: Invalid or expired authentication token` | The `X-API-Key` header is not reaching the server | Check the `headers` block and save the file before restarting Goose |
| `401: Invalid API key` | The key is mistyped, expired or revoked | Copy it again from Profile → API keys; only one key can be active per account |
| Goose shows no SocialCutter tools at all | Wrong transport: an entry still set to `type: sse` | Change `type` to `streamable_http` and start the session again |
| The extension exists but stays off | `enabled` is `false`, or you edited a file Goose does not read | Set `enabled: true` and confirm the path for your system |
| Still missing after editing the YAML | Goose reads the configuration at start-up | Close the session and open it again |
| A large batch cuts off | The run takes longer than `timeout` | Raise `timeout` (in seconds) or split the batch into smaller parts |

## Next steps

- Big picture: [Use SocialCutter from your LLM or editor with MCP](/en/guides/mcp/)
- The same flow in code, without an agent: [the API from the terminal with curl](/en/guides/curl/) and [from Python](/en/guides/python/)
- The map of paths: [Automating social media images: the 4 routes](/en/guides/automatizar-imagenes-redes-sociales/)