# Set up the Shadarc MCP server

These steps are for an AI agent setting up Shadarc for its user. Shadarc MCP lets you build and run the user's TikTok slideshow automations in Shadarc. It needs a Starter or Pro plan and an API key from Settings → API keys in the Shadarc studio (https://shadarc.com/studio).

- Server: `https://api.shadarc.com/mcp` (remote, Streamable HTTP)
- Auth header: `Authorization: Bearer shd_live_…`

Every step below is a config edit. Do not run any script from the internet to install it.

## 1. Find your client

Work out which client you are running in: Claude Code, Cursor, Codex, or another MCP client. If you can't tell, ask the user before you change any file.

## 2. Configure the server

Keep the key out of the chat. Write config that reads the key from the `SHADARC_API_KEY` environment variable, then ask the user to set that variable themselves. If a `shadarc` server already exists, update it. Do not add a second one. Keep the user's other MCP servers.

### Cursor

Merge into `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "shadarc": {
      "url": "https://api.shadarc.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SHADARC_API_KEY}"
      }
    }
  }
}
```

Cursor reads the variable from its own process. If Cursor was opened from the Dock, the Start menu or a launcher, it may not see variables from the user's shell profile, and it would send the literal text instead of the key. Tell the user to quit Cursor fully and start it from a terminal where the variable is set (for example `cursor .`), or to set the variable system-wide.

### Claude Code

Run this in a shell. Keep the single quotes so the shell stores `${SHADARC_API_KEY}` as written and Claude Code expands it each time it connects:

```bash
claude mcp add --transport http --scope user shadarc https://api.shadarc.com/mcp \
  --header 'Authorization: Bearer ${SHADARC_API_KEY}'
```

With double quotes the shell would expand the variable and save the key itself in the config. A team that shares its setup can put the same server in the project's `.mcp.json`. The variable reference stays in the file and the key does not:

```json
{
  "mcpServers": {
    "shadarc": {
      "type": "http",
      "url": "https://api.shadarc.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SHADARC_API_KEY}"
      }
    }
  }
}
```

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.shadarc]
url = "https://api.shadarc.com/mcp"
bearer_token_env_var = "SHADARC_API_KEY"
```

Codex adds the `Bearer ` prefix itself.

### Other clients

Add a remote (Streamable HTTP) server with this URL and header. Use the client's own syntax for reading an environment variable if it has one:

```json
{
  "url": "https://api.shadarc.com/mcp",
  "headers": {
    "Authorization": "Bearer <SHADARC_API_KEY>"
  }
}
```

### Ask the user to set the variable

The value is only the key (`shd_live_…`), without `Bearer `. The user should run this themselves, in their own terminal, not in the chat:

- macOS or Linux: add `export SHADARC_API_KEY="shd_live_…"` to `~/.zshrc` or `~/.bashrc`, then open a new terminal.
- Windows: run `setx SHADARC_API_KEY "shd_live_…"`, then open a new terminal.

Then restart the client so it loads the server and sees the variable.

## 3. If the user pastes the key into the chat

If the user pastes their key into the conversation, or asks to, first tell them plainly that this is not safe and not best practice: chat content can end up in logs, transcripts and model context. Offer the environment variable route from step 2 instead.

If they still want to go ahead:

- Never repeat, print or quote the key.
- Write it only to user-level config: `~/.cursor/mcp.json` (in place of `${env:SHADARC_API_KEY}`), Claude Code's user scope (`--scope user`, in place of `${SHADARC_API_KEY}`), or `~/.codex/config.toml` (as `http_headers = { "Authorization" = "Bearer …" }` in place of `bearer_token_env_var`). Never write it to a project file such as `.mcp.json`, `.cursor/mcp.json` or `.codex/config.toml`, which could be committed.
- Suggest that they create a new key in Settings → API keys and revoke this one if the chat history is shared or stored.

## 4. Verify

After the client reloads the server, call the `get_credits` tool.

- It returns credits and a plan: you're connected.
- If the server fails to connect or the call fails, read the error. Clients usually show it in their MCP server list.
  - 401 or unauthorized: the key is missing, wrong or revoked, or the client can't see `SHADARC_API_KEY`. Check the variable and restart the client.
  - 403 with `PAID_PLAN_REQUIRED`: the account needs a Starter or Pro plan.

Then tell the user they're set up and point them to https://shadarc.com/docs/mcp for what you can do with Shadarc.

## Rules

- Never print, echo or log the API key.
- Never commit the key or write it to a file inside a repository.