# Connect SocialCutter to Cursor and its agent CLI
> Set up the SocialCutter MCP server in .cursor/mcp.json with ${env:...}, understand per-project approval, and verify with agent mcp list.
- URL: https://socialcutter.theboomer.dev/en/guides/cursor/
- Idioma: en
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Cursor, mcp.json, MCP, agent CLI, SocialCutter, X-API-Key, environment variables
## 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`:

```json
{
  "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:

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

```bash
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:

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

To confirm the configuration is read and the tools arrive:

```bash
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](/en/guides/mcp/)
- Code path: [Process images with the API from curl](/en/guides/curl/) and [from Python](/en/guides/python/)
- Big picture: [Automating social media images: the 4 paths](/en/guides/automatizar-imagenes-redes-sociales/)
- API reference: https://docs.socialcutter.theboomer.dev