Connect SocialCutter to Cursor and its agent CLI

Two file paths, one configuration

Cursor reads MCP servers from two places depending on the scope you want:

Scope	File	Versioned
Project	.cursor/mcp.json at the repository root	Yes, that is the usual choice
Global	~/.cursor/mcp.json	No, it is yours

The important part is that the agent CLI reads the same configuration as the editor. There is no separate file for the terminal: whatever you register in .cursor/mcp.json is what the agent sees when you launch it inside the project, and whatever you put in ~/.cursor/mcp.json is what it sees anywhere. If something works in the editor but not in the CLI, the problem is not a different file: it is the approval scope, covered below.

The server entry

For a remote server the entry uses url plus an authentication header, X-API-Key or Authorization: Bearer:

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

Note the header: SocialCutter accepts both X-API-Key: sc_... and Authorization: Bearer sc_..., and the result is identical — use whichever your client documents. The sc_ prefix is what decides the route: if a Bearer value does not start with sc_ it is treated as a session token, and the private tools answer 401: Invalid or expired authentication token; with a wrong key they answer 401: Invalid API key. The key starts with sc_ and is created in the dashboard under Profile → API keys; it is shown once and only one is active per account.

No tool accepts the key as an argument, so the client must support custom headers. Cursor does.

Variables: ${env:...} and ${file:...}

Writing the secret into a versioned file is a bad idea. Cursor interpolates variables in the configuration, in url and in headers alike:

{
  "mcpServers": {
    "socialcutter": {
      "url": "${env:SOCIALCUTTER_MCP_URL}",
      "headers": { "X-API-Key": "${env:SOCIALCUTTER_API_KEY}" }
    }
  }
}

export SOCIALCUTTER_MCP_URL="https://mcp.socialcutter.theboomer.dev/mcp"
export SOCIALCUTTER_API_KEY="sc_your_key"

Two ways to resolve a value:

• ${env:NAME} takes the variable from the Cursor process environment. This is the recommended path: the key lives in your shell or your secrets manager and the JSON only carries the name.
• ${file:path} reads the value from a file. Handy when another tool deposits the secret, but mind the permissions: whatever sits in that file is sent as is.

Interpolation applies the same way in the URL and in the headers. Resolving the header from the environment is what lets you version .cursor/mcp.json without leaking anything.

envFile does not apply to remote servers

envFile exists in Cursor’s configuration, but it belongs to local servers: they are the only ones launched as a process, and therefore the only ones that can be handed an environment file at startup. Our server is remote; there is no local process to hand anything to, so envFile is ignored.

If you are coming from a local process configuration, the change is this: on a remote server variables are resolved inside the configuration itself, with ${env:...} in url and headers, not with a separate file. If you write envFile next to url it raises no error, it simply does nothing and the header ends up without a value, which shows up as a 401.

Approval: global versus project

Here is the difference that causes the most trouble in automation:

• Global servers (~/.cursor/mcp.json) do not ask for approval. They are yours and on your machine.
• Project servers (.cursor/mcp.json) need approval per workspace. Anyone can clone the repository; Cursor does not trust the tools it brings until you approve them in that workspace.
• On top of that, Cursor asks for confirmation before using an MCP tool by default, regardless of scope.

In the editor that is a couple of clicks. In a build pipeline there are no clicks. If the agent hangs waiting or reports that it has no tools, this is almost always why: the repo ships the .cursor/mcp.json, but that workspace has not approved it. The fix is to register the server at the machine’s global scope, or to launch the agent approving the servers explicitly:

agent --approve-mcps "process this image for Instagram post and TikTok cover"

To confirm the configuration is read and the tools arrive:

agent mcp list
agent mcp list-tools socialcutter

agent mcp list confirms the server is registered and whether it is approved. agent mcp list-tools socialcutter shows the tools it exposes: if the server is listed but the tool list comes back empty, the problem is the connection or the header, not the approval.

Verify without spending uses

The public tools answer without credentials, so they are the way to validate the connection and tell a transport failure apart from a key failure:

What you ask	Tool	What it confirms
“List the platforms and formats”	list_platforms	Connection and tool discovery
“Is the service up?”	get_health	Reaching the server
“How many uses do I have left?”	get_credits and get_wallet	A valid X-API-Key header

If list_platforms returns the catalogue, the connection is fine and any 401 comes from the header. If it returns nothing, the problem is earlier: the URL, the scope or the approval.

Common errors

Symptom	Cause	Fix
401: Invalid or expired authentication token	Missing header, or an Authorization: Bearer whose value does not start with sc_ (treated as a session token)	Send your sc_... key in X-API-Key or in Authorization: Bearer sc_...
401: Invalid API key	The key is wrong, expired or revoked	Create a new one under Profile → API keys
Tools are missing while the server is listed	A connection failure to the endpoint, not an approval issue	Check the URL and header with agent mcp list-tools socialcutter
The project server never activates	Workspace approval is missing	Approve it in the editor or register the server in ~/.cursor/mcp.json
The agent waits for you to approve each tool	Per-tool approval is on	Use agent --approve-mcps in the headless environment
envFile has no effect	It was set on a remote server	Pass the values with ${env:...} in url and headers
The JSON is not read	Trailing comma, or the file sits where Cursor does not look	Validate the JSON and confirm .cursor/mcp.json or ~/.cursor/mcp.json
The server answers but does not know the destination	A platform or format invented in the prompt	Check list_platforms for the 13 real destinations

Limits and cost

• 28 tools in total; 6 answer without credentials.
• 5 MB per image. Above that size the API returns 413.
• 1 use per destination (platform and format). Before a large batch, check get_credits and get_wallet.
• 13 destinations across 6 platforms, with a centred crop and output as webp, jpg or png.
• The server generates the files: it does not post to social networks and does not edit the image. Uploading or posting is the caller’s job.

Next steps

• Agents hub: Use SocialCutter from your LLM or editor with MCP
• Code path: Process images with the API from curl and from Python
• Big picture: Automating social media images: the 4 paths
• API reference: https://docs.socialcutter.theboomer.dev