SocialCutter as an OpenCode MCP server

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.

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:

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

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

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:

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
• Without an agent, in code: the API from the terminal with curl and from Python
• The map of paths: Automating social media images: the 4 routes