# SocialCutter as an OpenCode MCP server
> Set up SocialCutter in OpenCode with opencode.json: the mcp key, oauth set to false, the {env:VAR} substitution for the secret and mcp add from the CLI.
- URL: https://socialcutter.theboomer.dev/en/guides/opencode/
- Idioma: en
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: OpenCode, MCP, opencode.json, X-API-Key, oauth, mcp.servers, SocialCutter
## What OpenCode adds with an MCP server

OpenCode is a coding agent driven from the terminal and from its in-app interface. With an MCP server connected you do not write HTTP requests: you describe what you want and the agent decides which tool to call and with which arguments. The SocialCutter MCP server exposes the API as **28 tools**, so from the session you can ask for an image's formats, read the history or check your uses.

Using an agent does not change the product boundary: 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. Every destination consumed is **1 use**.

| Item | Value |
|---|---|
| Endpoint | `https://mcp.socialcutter.theboomer.dev/mcp` |
| Transport | Streamable HTTP (`remote` type in the client) |
| Auth header | `X-API-Key: sc_...` or `Authorization: Bearer sc_...` |
| Tools | 28, six of them public and credential-free |

The full picture of the server is in [the SocialCutter MCP server guide](/en/guides/mcp/).

## The opencode.json file

OpenCode reads its configuration from two places: the global `~/.config/opencode/opencode.json` and the project one, `opencode.json` or `opencode.jsonc` at the repository root. The server entry goes under the **`mcp`** key:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "socialcutter": {
      "type": "remote",
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "X-API-Key": "sc_your_key" }
      // authenticates the same: "headers": { "Authorization": "Bearer sc_your_key" }
    }
  }
}
```

### Field by field

| Field | What it is for |
|---|---|
| `type` | `remote` for a server over HTTP; `local` launches a process on your machine |
| `url` | Endpoint of the MCP server |
| `enabled` | Whether the server loads when the session starts |
| `oauth` | Whether the client attempts the OAuth flow. Here it goes to `false` |
| `headers` | Extra headers; this is where `X-API-Key` or `Authorization: Bearer` travels |

## Why `oauth: false` is the key line

OpenCode's documentation says it plainly for this case: when the server authenticates with a header key, configure `oauth` as `false`. Without that field, OpenCode sees a remote server with no declared credentials and attempts its own OAuth flow, which is not what SocialCutter offers. The usual result is a connection that never finishes registering its tools, or an authorisation error that has nothing to do with your key.

With `oauth: false` and the header in place, every request carries the key (`X-API-Key: sc_...` or `Authorization: Bearer sc_...`) and the client opens no authorisation flow.

## Keeping the key out of the file: {env:VAR}

A project `opencode.json` gets committed with the repository, so the secret does not belong in it. OpenCode supports environment variable substitution in the configuration using the **`{env:NAME}`** form:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "socialcutter": {
      "type": "remote",
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "X-API-Key": "{env:SOCIALCUTTER_API_KEY}" }
    }
  }
}
```

The variable is resolved from the process environment, so export `SOCIALCUTTER_API_KEY` in your shell or in whichever secrets manager you use before starting OpenCode. Create the key in the dashboard under **Profile → API keys**; it starts with `sc_`, is shown only once and only one can be active per account.

## Two shapes depending on the version

This is the trap that costs the most time: **not every version of the documentation describes the same schema**. Current docs place servers directly under `mcp`, while the V2 docs group them under `mcp.servers`, and the switch changes name: some pages use `enabled`, others `disabled`.

| Shape | Root key | Switch |
|---|---|---|
| Current docs | `mcp` | `enabled: true` |
| V2 docs | `mcp.servers` | `disabled: false` |

If no tools appear after configuring the server, check which shape your version expects before assuming the connection is broken. Switching between them means moving the entry one level and flipping the switch; the other fields (`type`, `url`, `oauth`, `headers`) stay the same.

## Registering it from the CLI

You do not have to edit the JSON by hand. The CLI ships its own registration command:

```bash
opencode mcp add socialcutter --url https://mcp.socialcutter.theboomer.dev/mcp
```

With `--global` the entry is stored in the user configuration and applies to every project; without the flag it stays in the current project scope. To review what is registered:

```bash
opencode mcp list
```

And inside the app, the `/mcps` command lists the connected servers and their tools.

## Verify the connection

Start with the public tools, which answer **without a key**. Asking for the catalogue or the service status confirms the transport and the URL are right:

- "List the platforms with their formats and sizes" → `list_platforms`
- "Is the service available?" → `get_health`
- "Which fit modes exist?" → `list_fit_modes`

Once the key is in place, the authentication check is a business question: "how many uses do I have left?" goes through `get_credits` and `get_wallet`.

## Limits and cost

- **1 use per destination** (platform and format); repeated destinations are not charged twice.
- **5 MB** per image.
- Output as `webp`, `jpg` or `png`, quality 1 to 100 (85 by default).
- Fit modes `cover`, `contain`, `fill` and `stretch`, always centre-cropped.
- **6 platforms and 13 destinations**; there is no 4:5.

## Common errors

| Symptom | Cause | Fix |
|---|---|---|
| `401: Invalid or expired authentication token` | The `X-API-Key` header is not being sent | Check the `headers` block and make sure the `{env:...}` variable is exported in the environment that starts OpenCode |
| `401: Invalid API key` | The key is mistyped, expired or revoked | Copy it again from Profile → API keys |
| The server appears but has no tools | The schema is not the one your version expects | Try `mcp.servers` and swap `enabled` for `disabled` as needed |
| OpenCode tries to authorise instead of using the header | `oauth: false` is missing from the entry | Add it and restart the session |
| Nothing responds after editing the JSON | Configuration is read at start-up, or the JSON is invalid | Validate the file and start again; `opencode mcp list` shows what it loaded |
| Wrong transport | It was configured as a `local` server | Ours is remote: `type` set to `remote` with the endpoint `url` |

## Next steps

- Big picture: [Use SocialCutter from your LLM or editor with MCP](/en/guides/mcp/)
- Without an agent, in code: [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/)