Connect SocialCutter to Codex CLI over MCP

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:

[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:

[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:

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:

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

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
• Code path: Process images with the SocialCutter API using curl
• Bigger picture: Automating social media images: the 4 routes
• API reference: https://docs.socialcutter.theboomer.dev