# Connect an MCP client

> Set up the Clipbeat MCP server in Claude Code, Claude Desktop, Cursor, VS Code, ChatGPT, n8n or any Streamable HTTP client.

Source: https://docs.clipbeat.app/mcp/clients/

Every client needs two things: the server URL and your API key in an `Authorization` header.

```text
URL:     https://api.clipbeat.app/mcp
Header:  Authorization: Bearer cb_live_...
```

Create the key in Clipbeat Studio, **Settings**, **Developers**, **API keys** ([Authentication](https://docs.clipbeat.app/authentication/)).
Replace `cb_live_...` below with your key, or better, keep the key in an environment variable or the client's secret
store.

> **One click sign-in is coming:**
Clients that connect with a sign-in screen instead of a key (Claude and ChatGPT connectors, for example) need OAuth,
which is **available soon**. Until then use the key based setups on this page. See [MCP authentication](https://docs.clipbeat.app/mcp/authentication/).

## Claude Code

```bash
claude mcp add --transport http clipbeat https://api.clipbeat.app/mcp \
  --header "Authorization: Bearer $CLIPBEAT_API_KEY"
```

Check it with `claude mcp list`, then ask: "Make a preview music video for `https://example.com/my-song.mp3`".

## Claude Desktop

Claude Desktop starts local servers from `claude_desktop_config.json` (Settings, Developer, Edit Config). Use the
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge to reach the remote server with your key (needs
Node.js):

```json
{
  "mcpServers": {
    "clipbeat": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.clipbeat.app/mcp", "--header", "Authorization:${CLIPBEAT_AUTH}"],
      "env": { "CLIPBEAT_AUTH": "Bearer cb_live_..." }
    }
  }
}
```

Restart Claude Desktop after saving. The header is passed through `env` so the space in `Bearer cb_live_...` survives on
every operating system.

## Cursor

Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "clipbeat": {
      "url": "https://api.clipbeat.app/mcp",
      "headers": { "Authorization": "Bearer cb_live_..." }
    }
  }
}
```

## VS Code

Add to `.vscode/mcp.json`. VS Code asks for the key once and stores it securely:

```json
{
  "inputs": [
    { "type": "promptString", "id": "clipbeat-key", "description": "Clipbeat API key", "password": true }
  ],
  "servers": {
    "clipbeat": {
      "type": "http",
      "url": "https://api.clipbeat.app/mcp",
      "headers": { "Authorization": "Bearer ${input:clipbeat-key}" }
    }
  }
}
```

The tools appear in Copilot Chat in agent mode.

## ChatGPT

ChatGPT connects to MCP servers through a sign-in flow (OAuth), which Clipbeat will support soon. Today, add Clipbeat
to a custom GPT as an **Action** using the REST API:

1. In the GPT editor, open **Configure**, then **Create new action**.
2. Choose **Import from URL** and enter `https://api.clipbeat.app/v1/openapi.json`.
3. Under **Authentication**, choose **API Key**, auth type **Bearer**, and paste your key.

The GPT can then import songs, start videos and poll their status with the same rules as the MCP tools.

## n8n

Use the **MCP Client Tool** node with an AI Agent node:

| Setting | Value |
| --- | --- |
| Endpoint | `https://api.clipbeat.app/mcp` |
| Server Transport | HTTP Streamable |
| Authentication | Bearer Auth, with your key as the token |
| Tools to Include | All, or pick the tools you need |

For fixed workflows without an agent, the **HTTP Request** node calling the [REST API](https://docs.clipbeat.app/api/) is often simpler.

## Any Streamable HTTP client

The server speaks plain JSON-RPC 2.0 over `POST`. You can talk to it with nothing more than `curl`:

```bash
curl -s https://api.clipbeat.app/mcp \
  -H "Authorization: Bearer $CLIPBEAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'
```

With the official SDKs:

**TypeScript**

```js
// npm install @modelcontextprotocol/sdk

const transport = new StreamableHTTPClientTransport(new URL('https://api.clipbeat.app/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}` } },
});
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

const balance = await client.callTool({ name: 'get_balance', arguments: {} });
console.log(balance.structuredContent);
await client.close();
```

**Python**

```python
# pip install mcp

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"}
    async with streamablehttp_client("https://api.clipbeat.app/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            balance = await session.call_tool("get_balance", {})
            print(balance.structuredContent)

asyncio.run(main())
```

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| `401` on connect | The key is missing, mistyped or revoked. Check the header is exactly `Authorization: Bearer cb_live_...`. |
| Client tries `GET /mcp` and gets `405` | The server does not offer a server-sent event stream. Streamable HTTP clients fall back to `POST` only; older SSE-only clients are not supported. |
| `insufficient_credits` from a tool | The account needs credits. Open the `topup_url` from the result. |
| `429` | Too many requests for this key. See [Rate limits](https://docs.clipbeat.app/rate-limits/). |
| Tools do not appear | Restart the client after editing its config. Some clients only load MCP tools in agent mode. |
