# Connect an agent (MCP)


# Connect an agent (MCP)

Second Studio speaks the [Model Context Protocol](https://modelcontextprotocol.io), so any MCP-capable
agent can use it with your API key. There are two servers; most people want the remote one.

| | Remote server | Local server |
|---|---|---|
| Install | Nothing — a URL and a header | `npx second-studio-mcp` (Node 20+) |
| Uploads | Agent sends files to a one-time upload URL | Agent passes a local file path |
| Fetching social videos | On our servers, where enabled | On your machine with `yt-dlp`, if installed |
| Waiting for jobs | Agent polls `get_job` | Tools wait for completion by default |

Use the **agent key** in agent configuration. It cannot approve posts, so an agent can never release
its own drafts.

## Remote server

URL: `https://frugal-anteater-681.convex.site/mcp` · Transport: Streamable HTTP · Auth: `Authorization: Bearer <key>`

**Claude Code**

```bash
claude mcp add --transport http second-studio https://frugal-anteater-681.convex.site/mcp --header "Authorization: Bearer YOUR_AGENT_KEY"
```

**Cursor, Windsurf and other clients with a JSON config**

```json
{
  "mcpServers": {
    "second-studio": {
      "type": "http",
      "url": "https://frugal-anteater-681.convex.site/mcp",
      "headers": { "Authorization": "Bearer YOUR_AGENT_KEY" }
    }
  }
}
```

**Claude Desktop** (via the local bridge, since it reads `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "second-studio": {
      "command": "npx",
      "args": ["-y", "second-studio-mcp"],
      "env": { "SECOND_STUDIO_API_KEY": "YOUR_AGENT_KEY", "SECOND_STUDIO_URL": "https://frugal-anteater-681.convex.site" }
    }
  }
}
```

## Local server

Runs on your machine and talks to the same API. Use it when the agent works with files on your disk.

```bash
SECOND_STUDIO_API_KEY=YOUR_AGENT_KEY SECOND_STUDIO_URL=https://frugal-anteater-681.convex.site npx -y second-studio-mcp
```

```bash
claude mcp add second-studio --env SECOND_STUDIO_API_KEY=YOUR_AGENT_KEY \
  --env SECOND_STUDIO_URL=https://frugal-anteater-681.convex.site -- npx -y second-studio-mcp
```

Optional: `SECOND_STUDIO_MAX_WAIT` — seconds a tool waits for a job before returning it as still
running (default 900). Install [yt-dlp](https://github.com/yt-dlp/yt-dlp) to let `fetch_video` download
references on your own machine.

## Tools

| Tool | What it does | Credits |
|---|---|---|
| `whoami` | Account, key scope and settings | — |
| `get_credits` | Balance, prices and packs | — |
| `upload_file` *(local)* | Upload a file from disk | — |
| `create_upload_url` + `register_asset` *(remote)* | Upload in two steps | — |
| `get_asset`, `list_assets`, `delete_asset` | Manage files | — |
| `fetch_video` | A reference from a social URL | 1 if fetched on our servers |
| `analyze_style` | Reference video → reusable style | 2 |
| `get_style`, `list_styles` | Read styles, including the full spec | — |
| `create_edit` | Your clips cut to a style | 5 |
| `record_url` | Record a public web app | 3 |
| `create_character`, `get_character`, `list_characters`, `delete_character` | Stored identities you can reuse by id | like one image |
| `create_brand`, `get_brand`, `list_brands`, `delete_brand` | Brand kits for explainer videos | — |
| `write_script` | An editable scene-by-scene explainer script from a brief | 2 |
| `create_explainer` | A rendered, branded explainer video from a brief or script | 12 |
| `generate_image` | Character sheets, characters, locations, props, scenes, products | per image |
| `generate_video` | Video shots, from text, an image or references (+ a voice track) | quoted per request |
| `generate_voice` | Performed voiceover | 1 per 500 chars |
| `lipsync` | Re-time a mouth to an audio track | 15 |
| `get_job`, `list_jobs` | Job status and outputs | — |
| `list_social_accounts` | Connected accounts | — |
| `connect_social_account` | A link to connect a new account | — |
| `create_post`, `list_posts` | Draft and track posts | 1 per post |
| `list_models` | Image, video and swap models and what each supports | — |
| `create_skill`, `list_skills`, `get_skill`, `update_skill`, `delete_skill` | Your own versioned image recipes | — |
| `edit_image` | Masked edit of a real photo, rest untouched | per image |
| `swap_character`, `motion_transfer` | Keep the footage, change the subject | quoted |
| `finalize_video`, `cancel_job`, `upscale_video` | Drafts → keeper, cancel with refund, 2160p resample | quoted / — / 3 |
| `library` | Everything the team can reuse by id, with who made it | — |
| `list_members`, `invite_member`, `update_member`, `remove_member`, `create_member_key`, `list_keys`, `revoke_key` | Team members, roles, keys, credit and dollar caps, claim links (admin) | — |
| `list_providers`, `connect_provider`, `disconnect_provider` | Your own Higgsfield / ElevenLabs keys (admin, where enabled) | — |
| `list_voices`, `clone_voice`, `delete_voice` | Your workspace's voices and clones from your samples | like voice |
| `analyze_brand` | A suggested brand kit from your boards | 1 |
| `report_issue`, `list_reports` | File a bug, feature request or question; follow the response | — |

Approving posts is deliberately not a tool. A person approves with the admin key — see [Posting](social.html).

## Example prompts

- *"Analyze ./refs/viral.mp4 and tell me what makes its editing work."*
- *"Make three 15-second edits of ./footage in the style of that reference, with different hooks."*
- *"Record our pricing page at https://example.com/pricing on mobile, then cut it to my saved style."*
- *"Draft the best one to our TikTok for tomorrow 6pm Eastern."*