Zed and SocialCutter: MCP through context servers

Zed does not call MCP servers MCP

Zed speaks MCP, but it does not use that name in its configuration: it calls them context servers. That single detail breaks half of all first attempts, because the snippet that works in other tools gets copied over unchanged and does nothing.

What you expect	What Zed reads
mcpServers	Ignored: it is not a Zed key
context_servers	The correct root key for registering a server
~/.config/zed/settings.json	Global configuration, for every project
.zed/settings.json	Configuration for one project only

If you paste a block with mcpServers, Zed raises no error: no new server simply ever shows up. Before touching anything else, check the root key name.

Requirements: Zed v0.214.5 or later

The SocialCutter MCP server is remote and speaks HTTP with streaming at https://mcp.socialcutter.theboomer.dev/mcp. Nothing is launched with npx, there is no local process and nothing has to be installed on the machine.

Zed natively supports remote MCP servers over HTTP from v0.214.5. Earlier versions only talk to local servers over stdio, so an entry with a url will not connect no matter how correct the JSON is. If the server does not appear, or appears with no tools, the first thing to do is update Zed and reopen it.

The transport is HTTP, not SSE. The two are not interchangeable: point at the wrong transport and the server may register with no tools at all.

Two authentication headers

SocialCutter accepts both headers: X-API-Key: sc_... and Authorization: Bearer sc_.... 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.

Five tools answer without a key: list_platforms, list_formats, list_fit_modes, get_health and get_pricing_plans. They are the way to check that the connection is alive before you have credentials. The private ones —process_image, process_batch, get_credits, get_wallet, get_history, auth_me and the rest up to 28— require a valid key. With no header they answer 401: Invalid or expired authentication token; with a key that does not work, 401: Invalid API key.

Create the key in the dashboard under Profile → API keys. It is shown only once and only one can be active per account.

Configure settings.json

Open ~/.config/zed/settings.json (or .zed/settings.json if you want the configuration to travel with the repository) and add:

{
  "context_servers": {
    "socialcutter": {
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": {
        "X-API-Key": "sc_your_key"
        // same auth: "Authorization": "Bearer sc_your_key"
      }
    }
  }
}

You can also register it from the interface: Settings → AI → MCP Servers → Add Server. The interface writes the same entry into the same file, so either route ends up in the same place.

With no header declared, Zed starts its own OAuth flow

When Zed finds no authentication header configured for a server, it launches its own OAuth flow against it. If you let Zed try to authorise over OAuth, the request ends in 401 and all you see is an authentication error in the interface.

That is why the snippet above declares the header explicitly: X-API-Key: sc_... or Authorization: Bearer sc_... both work, and either one keeps Zed from opening the OAuth flow.

Verify the connection

1. Save the file and reopen Zed so it reloads the configuration.
2. Go to Settings → AI → MCP Servers and check that socialcutter is listed.
3. Ask the assistant something that needs no key: “list the platforms and their formats”. If it answers with the 6 platforms and 13 destinations, the connection works even before you paste the key.
4. Then ask “how many uses do I have left?” That one goes through get_credits and get_wallet, so it needs the header. If this second answer fails with 401, the problem is the key, not the transport.

What you can ask the model

What you ask	Tool involved	What comes back
“List the platforms and formats”	list_platforms and list_formats	The catalogue with sizes and aspect ratios
“Process this URL for Instagram post and TikTok cover”	process_image	An image_id and one URL per destination
“Process these four files”	process_upload_file or process_batch	The outputs for each image
“How many uses do I have left?”	get_credits and get_wallet	Daily uses, extra allowance and purchased balance
“Show me the last ten images”	get_history	The history with the source of every job

The billing unit is 1 use per destination, where a destination is a platform and format pair: one request for Instagram post, TikTok cover and YouTube thumbnail costs 3 uses. Failed processings are refunded.

Keep the product boundary in mind too: SocialCutter generates files and does not publish. The crop is centered, with the cover, contain, fill and stretch modes and no content analysis. Output is webp, jpg or png at quality 1 to 100 (85 by default) and the maximum size per image is 5 MB.

Common errors

Symptom	Cause	Fix
401: Invalid or expired authentication token	The entry carries no auth header, or the Bearer value has no sc_ prefix	Add X-API-Key: sc_... or Authorization: Bearer sc_... under headers and restart Zed
401: Invalid API key	Key mistyped or revoked	Create a new one under Profile → API keys and replace the value
The server does not show up in Zed	Wrong root key (mcpServers)	Rename it to context_servers and save
The server appears with no tools	Zed older than v0.214.5, or the wrong transport	Update Zed; confirm the URL is the HTTP one, not an SSE one
Zed opens an OAuth flow	No header configured for that server	Declare X-API-Key or Authorization: Bearer sc_... under headers so Zed does not try to authorise
413 while processing a file	The image is over 5 MB	Shrink the file before uploading
429 while processing	Wallet quota exhausted	Check get_credits, then buy a pack or upgrade the plan

Next steps

• Protocol overview: Use SocialCutter from your LLM or editor with MCP
• No editor, from the terminal: Process images with the API from the terminal (curl)
• From code: Process images with the SocialCutter API from Python
• If your tool has no MCP: Aider has no MCP: use the SocialCutter API instead
• The four automation paths: Automating social media images
• API reference: https://docs.socialcutter.theboomer.dev
• Zed MCP documentation: https://zed.dev/docs/ai/mcp