# Zed and SocialCutter: MCP through context servers
> Connect the SocialCutter MCP server to Zed with the context_servers key and the X-API-Key header: settings.json, step by step checks and common errors.
- URL: https://socialcutter.theboomer.dev/en/guides/zed/
- Idioma: en
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Zed, context servers, MCP, X-API-Key, settings.json, SocialCutter
## 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:

```json
{
  "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](/en/guides/mcp/)
- No editor, from the terminal: [Process images with the API from the terminal (curl)](/en/guides/curl/)
- From code: [Process images with the SocialCutter API from Python](/en/guides/python/)
- If your tool has no MCP: [Aider has no MCP: use the SocialCutter API instead](/en/guides/aider/)
- The four automation paths: [Automating social media images](/en/guides/automatizar-imagenes-redes-sociales/)
- API reference: https://docs.socialcutter.theboomer.dev
- Zed MCP documentation: https://zed.dev/docs/ai/mcp