clipia-mcp

# Clipia MCP

**Generate AI images & video inside Claude, Cursor, ChatGPT — 50+ models in one MCP endpoint.**

[![npm clipia-ai](https://img.shields.io/npm/v/clipia-ai?label=npm%20clipia-ai&logo=npm)](https://www.npmjs.com/package/clipia-ai)
[![PyPI clipia](https://img.shields.io/pypi/v/clipia?label=PyPI%20clipia&logo=pypi&logoColor=white)](https://pypi.org/project/clipia/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-Streamable%20HTTP-7c5cff)](https://modelcontextprotocol.io)

Clipia is an AI image & video generation platform. This is its hosted, remote **Model Context Protocol (MCP)** server: a single endpoint that lets any MCP-capable AI agent generate images and video, poll results, browse models, search prompt templates and read your credit balance — no SDK and no code required.

**Endpoint:** `https://mcp.clipia.ai/mcp` — stateless **Streamable HTTP**, authenticated with a Clipia API key.

---

## Quick start

Connect Clipia to Claude Code in one command (replace the placeholder with your key):

```bash
claude mcp add --transport http clipia https://mcp.clipia.ai/mcp \
  --header "Authorization: Bearer <CLIPIA_API_KEY>"
```

Then just ask in the chat: _"Generate a neon city image with Clipia"_ — the preview lands right in the terminal.

**Where to get a key:** create one in the [Clipia Developer Console](https://clipia.ai/en/developer). The key is shown once.

**Sandbox without charges:** keys with the `clipia_test_` prefix run in a sandbox — instant mock results, no credits spent. Use a `clipia_test_*` key to validate your integration before going live.

---

## Connect from any client

The endpoint is the same everywhere: `https://mcp.clipia.ai/mcp`. IDEs and CLIs authenticate with an API key from the Developer Console; **claude.ai** and **ChatGPT** connect by signing in to your Clipia account over OAuth (no key needed).

Ready-to-paste configs live in [`examples/`](./examples).

| Client                             | How to connect                                               | Auth          |
| ---------------------------------- | ------------------------------------------------------------ | ------------- |
| **Claude Code**                    | `claude mcp add --transport http clipia …` (see Quick start) | API key       |
| **Claude Desktop**                 | `mcp-remote` bridge in `claude_desktop_config.json`          | API key       |
| **claude.ai** (web/desktop/mobile) | Settings → Connectors → Add custom connector                 | OAuth         |
| **Cursor**                         | `~/.cursor/mcp.json` (or project `.cursor/mcp.json`)         | API key       |
| **VS Code**                        | `.vscode/mcp.json` (`servers` + `inputs`)                    | API key       |
| **Cline**                          | `cline_mcp_settings.json` (`mcpServers`)                     | API key       |
| **Windsurf**                       | `~/.codeium/windsurf/mcp_config.json` (`serverUrl`)          | API key       |
| **Codex CLI**                      | `~/.codex/config.toml` (`bearer_token_env_var`)              | API key (env) |
| **Gemini CLI**                     | `gemini mcp add --transport http clipia …`                   | API key       |
| **ChatGPT**                        | Developer mode → Apps & Connectors → Create                  | OAuth         |

### Claude Code

```bash
claude mcp add --transport http clipia https://mcp.clipia.ai/mcp \
  --header "Authorization: Bearer <CLIPIA_API_KEY>"
```

### Claude Desktop

Claude Desktop bridges to remote HTTP servers through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). Add to `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart Claude Desktop:

```json
{
  "mcpServers": {
    "clipia": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.clipia.ai/mcp",
        "--header",
        "Authorization: Bearer <CLIPIA_API_KEY>"
      ]
    }
  }
}
```

### claude.ai (web / desktop / mobile)

1. Open **Settings → Connectors**.
2. Click **Add custom connector** and paste the URL: `https://mcp.clipia.ai/mcp`
3. Click **Connect** and sign in to your Clipia account — no key needed (OAuth).
4. In a new chat, ask for an image or a video: a live Clipia card with progress and the result appears inside the message.

> Credits are charged to the connected Clipia account.

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project), then restart Cursor:

```json
{
  "mcpServers": {
    "clipia": {
      "url": "https://mcp.clipia.ai/mcp",
      "headers": { "Authorization": "Bearer <CLIPIA_API_KEY>" }
    }
  }
}
```

### VS Code

Create `.vscode/mcp.json` in your workspace (or use the **MCP: Add Server** command). VS Code prompts for the key on first run and stores it securely:

```json
{
  "servers": {
    "clipia": {
      "type": "http",
      "url": "https://mcp.clipia.ai/mcp",
      "headers": { "Authorization": "Bearer ${input:clipia_api_key}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "clipia_api_key",
      "description": "Clipia API Key",
      "password": true
    }
  ]
}
```

### Cline

Cline reads `mcpServers` from its `cline_mcp_settings.json` (MCP Servers → Configure MCP Servers in the Cline panel):

```json
{
  "mcpServers": {
    "clipia": {
      "url": "https://mcp.clipia.ai/mcp",
      "headers": { "Authorization": "Bearer <CLIPIA_API_KEY>" }
    }
  }
}
```

Cline can also install this server itself — see [`llms-install.md`](./llms-install.md).

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json` (note the Windsurf-specific `serverUrl` field), then refresh **Cascade → MCPs**:

```json
{
  "mcpServers": {
    "clipia": {
      "serverUrl": "https://mcp.clipia.ai/mcp",
      "headers": { "Authorization": "Bearer <CLIPIA_API_KEY>" }
    }
  }
}
```

### Codex CLI

Add a block to `~/.codex/config.toml` and export the key into your environment — Codex injects `Authorization: Bearer` from the variable automatically:

```toml
# ~/.codex/config.toml
[mcp_servers.clipia]
url = "https://mcp.clipia.ai/mcp"
bearer_token_env_var = "CLIPIA_API_KEY"

# in your environment:
# export CLIPIA_API_KEY=<CLIPIA_API_KEY>
```

### Gemini CLI

```bash
gemini mcp add --transport http clipia https://mcp.clipia.ai/mcp \
  --header "Authorization: Bearer <CLIPIA_API_KEY>"
```

Verify the connection with `gemini mcp list`.

### ChatGPT (Developer Mode)

1. In ChatGPT (web): **Settings → Apps & Connectors → Advanced settings** → enable **Developer mode** (Plus, Pro, Business, Enterprise).
2. Back in **Apps & Connectors → Create**. Name it `Clipia`, MCP Server URL: `https://mcp.clipia.ai/mcp`.
3. Authentication — **OAuth**, tick "I trust this application", click **Create**.
4. Sign in to your Clipia account in the popup. In a chat press **+ → More → Clipia**, then ask in plain text.

**Supported auth header schemes:** `Authorization: Bearer clipia_*` (recommended), `Authorization: Key <key>`, or `X-Api-Key: <key>`.

---

## Tools

The server always exposes **10 core tools to the agent**. As of 2026-07-11, production exposes **14 agent tools**: the 10 core tools plus chat, scenario planning, server-side video composition and presentation generation. A separate app-only helper is hidden from the AI agent. Compact schemas keep the agent's context window light.

| Tool                    | What it does                                                                                                                                                                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `generate_image`        | Generate image(s) from a text prompt, optionally with reference images (editing / image-to-image). Waits briefly and usually returns the finished image inline (URL + small preview). Cost in credits is returned.               |
| `generate_video`        | Start a video generation from a text prompt (text-to-video) or from a start image (image-to-video, pass `image_url`). Returns `request_id` and cost in credits immediately — renders take 1–10 min, poll with `wait_generation`. |
| `generate_audio`        | Generate speech from text with a selected voice and language. Returns an MP3 when complete.                                                                                                                                      |
| `generate_music`        | Generate background music or a soundtrack from a description of mood, genre and tempo.                                                                                                                                           |
| `wait_generation`       | Wait for a generation to finish (long-poll up to `wait_seconds`, then returns current status). Call repeatedly until `COMPLETED`, `FAILED` or `CANCELED`. Returns output URLs (and an inline preview) when done.                 |
| `get_generation`        | Get the current status/result of a generation without waiting. When `COMPLETED`, `output.images[].url` is the inline webp preview and `output.images[].original_url` is the full-quality PNG/JPG.                                |
| `list_models`           | List available AI models with type (text/image/video/audio), capabilities and pricing in credits. Text models expose per-1K input/output rates; generation models expose a base price. Filter by `type` / `search`.              |
| `get_model`             | Get model details and pricing: `input_schema` for generation models; context limits and per-1K input/output rates for text models.