# Connect SocialCutter to Codex CLI over MCP
> Register the SocialCutter MCP server in ~/.codex/config.toml with http_headers or env_http_headers, add it with codex mcp add and verify with /mcp.
- URL: https://socialcutter.theboomer.dev/en/guides/codex-cli/
- Idioma: en
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Codex CLI, MCP, SocialCutter, config.toml, X-API-Key, http_headers, API key
## What the SocialCutter MCP brings into Codex CLI

Codex CLI is OpenAI's terminal agent. It works on your repository, runs commands and proposes changes; connect the SocialCutter MCP server and it gains **28 tools** for generating image formats from the same session.

The server is deployed over streamable HTTP:

```
https://mcp.socialcutter.theboomer.dev/mcp
```

It identifies as `@theboomerdev/socialcutter-mcp` version **1.1.0**. 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. No tool accepts the key as an argument, so the client must be able to send custom headers.

The public tools (`list_platforms`, `list_formats`, `list_fit_modes`, `get_health`, `get_pricing_plans`, `get_credit_packs`) answer without credentials and let you verify the connection before you have a key. The private ones (`process_image`, `process_batch`, `get_wallet`, `get_history` and the rest) return `401` when the header does not arrive.

## The server table in ~/.codex/config.toml

Codex CLI reads MCP servers from TOML, not JSON. Global configuration lives in `~/.codex/config.toml` and project configuration in `.codex/config.toml`. The entry is a table:

```toml
[mcp_servers.socialcutter]
url = "https://mcp.socialcutter.theboomer.dev/mcp"
http_headers = { "X-API-Key" = "sc_your_key" }
# Same result with the other header: http_headers = { "Authorization" = "Bearer sc_your_key" }
```

The `url` key points at the HTTP endpoint. `http_headers` is the map of headers Codex adds to every request: that is where our `X-API-Key` goes — or `Authorization: Bearer sc_your_key`, which authenticates exactly the same.

### Without the secret in plain text: env_http_headers

Writing the key into `config.toml` is convenient but leaves the secret on disk in plain text. The alternative is `env_http_headers`, which asks for the **name of an environment variable** instead of the value:

```toml
[mcp_servers.socialcutter]
url = "https://mcp.socialcutter.theboomer.dev/mcp"
env_http_headers = { "X-API-Key" = "SOCIALCUTTER_API_KEY" }
```

Codex reads the value of `SOCIALCUTTER_API_KEY` from its own process, so the key never lands in the file. Export the variable in your shell or through your system's secrets manager:

```bash
export SOCIALCUTTER_API_KEY="sc_your_key"
```

| Field | What it does |
|---|---|
| `url` | MCP server endpoint |
| `http_headers` | Headers with literal values, including the key |
| `env_http_headers` | Headers whose value comes from an environment variable |
| `startup_timeout_sec` | Seconds Codex waits on startup (10 by default) |
| `tool_timeout_sec` | Maximum seconds per tool call (60 by default) |
| `enabled_tools` / `disabled_tools` | Lists to leave out tools you do not want to expose |

Use `http_headers` on a trusted machine and `env_http_headers` whenever the file might be shared, versioned or baked into an image. Because the configuration is shared with the IDE extension, a key written here is also available to the editor.

## Adding it with codex mcp add --url

If you would rather have Codex write the base entry, use the `mcp add` subcommand:

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

The command creates the `[mcp_servers.socialcutter]` table with the URL. Then open `config.toml` and add `http_headers` or `env_http_headers` with `X-API-Key`: the CLI does not know our header and it has to be declared by hand. Avoid pasting the key into the agent's chat or your shell history.

## Verifying: codex mcp list and /mcp

```bash
codex mcp list
codex mcp get socialcutter
```

`codex mcp list` shows the registered servers and their status; `codex mcp get socialcutter` gives the entry detail. Inside the interactive interface, the `/mcp` command lists the active servers and the tools they expose: that is where you confirm `socialcutter` appears with its catalogue.

For a real test, ask for a public tool:

> List the platforms and their formats.

If the catalogue comes back with the sizes, the transport and the URL are correct. Then ask for the wallet to confirm `X-API-Key` actually arrives.

## Three plain-language uses

| What you type | Tool | What comes back |
|---|---|---|
| "Take https://example.com/master.jpg and generate all 13 destinations" | `process_image` | An `image_id` and one URL per destination |
| "Process this list of images in a batch" | `process_batch` | One result per image with its outputs |
| "Show me the wallet and how many uses I have left" | `get_credits` and `get_wallet` | Daily uses, bonus bag and purchased balance |

The public catalogue is **6 platforms** and **13 destinations**, where a destination is a platform and format pair. Converting one master to all 13 destinations costs 13 uses and happens in a single `process_image` call, whose required arguments are `source_url` and `destinations`.

`process_batch` takes an `images` argument and handles several images at once, with the same cost of 1 use per destination. `get_history` requires no arguments (it has two optional ones) and `get_image` needs `image_id` to retrieve a previous job.

The product's boundary is the same as in the API: SocialCutter **generates the files**, it does not post to social networks and does not edit the image. Cropping is **centred**, with `cover`, `contain`, `fill` and `stretch` modes, and no content analysis. Output is `webp`, `jpg` or `png` with quality from 1 to 100 (85 by default), and each image can be up to 5 MB.

## Common errors

| Symptom | Cause | Fix |
|---|---|---|
| `401: Invalid or expired authentication token` | The entry declares no header | Add `http_headers` or `env_http_headers` with `X-API-Key` |
| `401: Invalid API key` | The key is invalid: mistyped, padded or revoked | Confirm it starts with `sc_` and only one is active per account |
| `401` only with `env_http_headers` | The environment variable is not exported in Codex's process | Export `SOCIALCUTTER_API_KEY` in the same shell you launch Codex from |
| `401` with `Authorization: Bearer` | The Bearer value does not start with `sc_`, so it is treated as a session token | Write `Authorization: Bearer sc_...` with your key, or use `X-API-Key` |
| The tools do not appear | Wrong URL or wrong transport | The endpoint ends in `/mcp` and is HTTP, not SSE; check the table with `codex mcp get socialcutter` |
| The entry is ignored | Wrong file edited | Global is `~/.codex/config.toml`; project is `.codex/config.toml` |
| The tool times out | It runs past `tool_timeout_sec` | Raise it in the table if your batches are large |

## Next steps

- MCP overview: [Connect SocialCutter to your LLM or editor with MCP](/en/guides/mcp/)
- Code path: [Process images with the SocialCutter API using curl](/en/guides/curl/)
- Bigger picture: [Automating social media images: the 4 routes](/en/guides/automatizar-imagenes-redes-sociales/)
- API reference: https://docs.socialcutter.theboomer.dev