> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Describes the deAPI MCP server, its available tools, and how to connect agents or IDE integrations to use deAPI as a structured toolbox.

<Warning>
  The MCP server is currently in beta. You may encounter occasional issues or unexpected behavior as we continue to refine the service. We actively welcome feedback and bug reports — join the conversation on [Discord](https://discord.com/invite/UFfK5YRBsr).
</Warning>

In addition to the HTTP API, deAPI exposes an **MCP (Model Context Protocol) server**. This allows AI assistants, IDE extensions, and MCP-aware tools to call deAPI capabilities as structured tools instead of manually constructing HTTP requests.

***

### What is MCP?

The **Model Context Protocol (MCP)** is an open standard that enables AI models and agents to interact with external tools and services in a structured way. Instead of crafting raw HTTP requests, your AI assistant discovers available tools and calls them using a standardized protocol.

With deAPI's MCP server, Claude, ChatGPT, Cursor, and other MCP-compatible clients can:

* Generate images, videos, and audio directly within conversations
* Transcribe YouTube / X / Twitch / Kick / TikTok videos or audio files
* Remove image backgrounds and upscale images and videos
* Check pricing before running expensive operations
* Access all deAPI capabilities through natural language

New tools and capabilities will be added as the MCP server evolves. Follow our [Discord](https://discord.com/invite/UFfK5YRBsr) for updates and to share feature requests.

The full source code for the MCP server is available on GitHub: [github.com/deapi-ai/mcp-server-deapi](https://github.com/deapi-ai/mcp-server-deapi)

***

### Server Details

| Property                | Value                      |
| ----------------------- | -------------------------- |
| **MCP Server URL**      | `https://mcp.deapi.ai/mcp` |
| **OAuth Client ID**     | `deapi-mcp`                |
| **OAuth Client Secret** | Your deAPI API key         |
| **Transport**           | Streamed HTTP              |

***

### Available Tools

The deAPI MCP server exposes the following tools:

#### Image Generation & Manipulation

| Tool                            | Description                                                                                                           |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `text_to_image`                 | Generate images from text prompts using AI diffusion models (Flux, Z-Image-Turbo) — uses `/api/v2/images/generations` |
| `image_to_image`                | Transform existing images using text prompts (style transfer, editing) — uses `/api/v2/images/edits`                  |
| `image_to_text`                 | Extract text from images using OCR — uses `/api/v2/images/ocr`                                                        |
| `image_remove_background`       | Remove background from images (transparent PNG output) — uses `/api/v2/images/background-removals`                    |
| `image_upscale`                 | Upscale images to higher resolution — uses `/api/v2/images/upscales`                                                  |
| `text_to_image_price`           | Calculate price for text-to-image generation                                                                          |
| `image_to_image_price`          | Calculate price for image transformation                                                                              |
| `image_to_text_price`           | Calculate price for OCR extraction                                                                                    |
| `image_remove_background_price` | Calculate price for background removal                                                                                |
| `image_upscale_price`           | Calculate price for image upscaling                                                                                   |

#### Video Generation & Processing

| Tool                             | Description                                                                                          |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `text_to_video`                  | Generate videos from text prompts — uses `/api/v2/videos/generations`                                |
| `image_to_video`                 | Animate static images into videos — uses `/api/v2/videos/animations`                                 |
| `audio_to_video`                 | Generate video conditioned on audio and text prompt — uses `/api/v2/videos/audio-syncs`              |
| `video_replace`                  | Replace a person in a video with a character image — uses `/api/v2/videos/replacements`              |
| `video_upscale`                  | Upscale videos to higher resolution — uses `/api/v2/videos/upscales`                                 |
| `video_file_transcription`       | Transcribe uploaded video files to text — uses `/api/v2/audio/transcriptions`                        |
| `video_url_transcription`        | Transcribe videos from URLs (YouTube, X, Twitch, TikTok, Kick) — uses `/api/v2/audio/transcriptions` |
| `text_to_video_price`            | Calculate price for text-to-video generation                                                         |
| `image_to_video_price`           | Calculate price for image-to-video generation                                                        |
| `audio_to_video_price`           | Calculate price for audio-to-video generation                                                        |
| `video_replace_price`            | Calculate price for video character replacement                                                      |
| `video_upscale_price`            | Calculate price for video upscaling                                                                  |
| `video_file_transcription_price` | Calculate price for video file transcription                                                         |
| `video_url_transcription_price`  | Calculate price for video URL transcription                                                          |

#### Audio & Speech

| Tool                            | Description                                           |
| ------------------------------- | ----------------------------------------------------- |
| `text_to_audio`                 | Convert text to natural-sounding speech (TTS)         |
| `text_to_music`                 | Generate music tracks from text descriptions          |
| `audio_transcription`           | Transcribe uploaded audio files to text using Whisper |
| `audio_url_transcription`       | Transcribe audio from URLs (X/Twitter Spaces)         |
| `text_to_audio_price`           | Calculate price for text-to-speech                    |
| `text_to_music_price`           | Calculate price for music generation                  |
| `audio_transcription_price`     | Calculate price for audio file transcription          |
| `audio_url_transcription_price` | Calculate price for audio URL transcription           |

#### Embeddings

| Tool                      | Description                                  |
| ------------------------- | -------------------------------------------- |
| `text_to_embedding`       | Generate text embeddings for semantic search |
| `text_to_embedding_price` | Calculate price for embedding generation     |

#### Utility

| Tool                   | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `get_available_models` | List all available AI models with specifications |
| `get_balance`          | Check your deAPI account balance                 |
| `check_job_status`     | Check status of submitted jobs                   |

***

### How to Connect

#### Claude (claude.ai)

To use deAPI MCP tools directly in Claude conversations:

**Step 1.** Get your API key from the [deAPI Dashboard](https://app.deapi.ai/dashboard)

**Step 2.** Add the MCP connector in Claude settings:

* Go to **Settings** → **Connectors**
* Click **Add Connector** or **Add MCP Server**
* Select **New OAuth Connector**
* Enter the following credentials:

| Field                   | Value                      |
| ----------------------- | -------------------------- |
| **OAuth Client ID**     | `deapi-mcp`                |
| **OAuth Client Secret** | Your deAPI API key         |
| **Server URL**          | `https://mcp.deapi.ai/mcp` |

**Step 3.** Grant permissions — After adding the connector, Claude will ask you to authorize the connection. Click **Allow** to enable deAPI MCP tools in your conversations.

**Step 4.** Start using deAPI MCP by asking Claude to generate images, transcribe videos, or use any other capability. Make sure to mention "deAPI MCP" in your prompt so Claude knows to use the MCP tools.

**Example prompts:**

* *"Using deAPI MCP, generate an image of a futuristic city at sunset"*
* *"With deAPI MCP, transcribe this YouTube video: \[URL]"*
* *"With deAPI MCP, transcribe this Twitch video: \[URL]"*
* *"Check my deAPI MCP balance"*
* *"Using deAPI MCP, create a video of waves crashing on a beach"*

***

#### Claude Desktop

To use deAPI MCP in the Claude Desktop app, configure it via the config file with a Bearer token. This is the recommended approach for desktop — no OAuth setup required.

**Config file setup:**

Edit your Claude Desktop configuration file:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json theme={null}
{
  "mcpServers": {
    "deapi": {
      "url": "https://mcp.deapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Replace `YOUR_API_KEY` with your actual deAPI key. Save the file and restart Claude Desktop.

***

#### Cursor IDE

To integrate deAPI MCP into Cursor for AI-assisted development:

<Tip>
  **Quick setup:** Press `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux), type **"MCP Settings"** and press Enter — this opens the MCP configuration file directly.
</Tip>

**Step 1.** Get your API key from the [deAPI Dashboard](https://app.deapi.ai/dashboard)

**Step 2.** Open Cursor Settings:

* Press `Cmd/Ctrl + Shift + P`
* Search for **"Cursor Settings"** or navigate to **Settings** → **Cursor Settings**

**Step 3.** Add MCP Configuration:

* Find the **MCP** or **Model Context Protocol** section
* Add a custom MCP server configuration
* Paste the following JSON (replace `YOUR_API_KEY` with your actual key):

```json theme={null}
{
  "mcpServers": {
    "deapi": {
      "name": "DEAPI MCP",
      "url": "https://mcp.deapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

**Step 4.** Restart Cursor to apply the configuration.

**Step 5.** Invoke deAPI MCP in chat by using phrases like:

* *"Using deAPI MCP, generate an image of…"*
* *"With deAPI MCP, transcribe this audio…"*
* *"Via deAPI MCP, check my balance"*

<Tip>
  Cursor recognizes deAPI MCP tools when you mention keywords like "using deAPI MCP", "with deAPI MCP", or "via MCP" in your prompts.
</Tip>

***

#### ChatGPT

To use deAPI MCP tools in ChatGPT conversations:

<Info>
  MCP is available in beta to **Pro, Plus, Business, Enterprise, and Education** accounts. The MCP apps work on both web and desktop, but Developer mode settings are only accessible in the **web version** at [chatgpt.com](https://chatgpt.com).
</Info>

**Step 1.** Get your API key from the [deAPI Dashboard](https://app.deapi.ai/dashboard)

**Step 2.** Enable Developer mode:

* Go to **Settings** → **Apps & Connectors**
* Scroll to **Advanced settings** at the bottom
* Enable **Developer mode**
* Go back — a **Create App** button will appear next to Advanced settings

**Step 3.** Create a new MCP App:

* Click **Create App**
* Fill in the following details:

| Field                   | Value                            |
| ----------------------- | -------------------------------- |
| **Name**                | `deAPI` (or any name you prefer) |
| **Description**         | `deAPI MCP` (optional)           |
| **MCP Server URL**      | `https://mcp.deapi.ai/mcp`       |
| **Authentication**      | `OAuth`                          |
| **OAuth Client ID**     | `deapi-mcp`                      |
| **OAuth Client Secret** | Your deAPI API key               |

**Step 4.** Check the risk acknowledgment checkbox ("I understand and want to continue")

**Step 5.** Click **Create**

**Step 6.** Start using deAPI MCP by asking ChatGPT to generate images, transcribe videos, or use any other capability.

**Example prompts:**

* *"Using deAPI MCP, generate an image of a cyberpunk cat"*
* *"With deAPI MCP, transcribe this YouTube video: \[URL]"*
* *"Check my deAPI MCP balance"*
* *"With deAPI MCP, transcribe this Kick video: \[URL]"*

***

#### Claude Code

To use deAPI MCP in Claude Code, open a terminal in your project directory and run:

```bash theme={null}
claude mcp add deapi -s user -t http https://mcp.deapi.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with your actual deAPI key. The server will be available in all your Claude Code sessions.

***

#### Codex

To use deAPI MCP in Codex, add the server to your configuration file.

Edit `~/.codex/config.toml` (user-level) or `.codex/config.toml` (project-level) and add:

```toml theme={null}
[mcp_servers.deapi]
url = "https://mcp.deapi.ai/mcp"
bearer_token_env_var = "DEAPI_TOKEN"
```

Then set the environment variable with your deAPI key:

```bash theme={null}
export DEAPI_TOKEN="YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with your actual deAPI key.

***

#### Gemini CLI

To use deAPI MCP in Gemini CLI, open a terminal in your project directory and run:

```bash theme={null}
gemini mcp add --transport http --header "Authorization: Bearer YOUR_API_KEY" deapi https://mcp.deapi.ai/mcp
```

Replace `YOUR_API_KEY` with your actual deAPI key.

***

### Self-Hosting

You can run the MCP server on your own infrastructure. The full source code is available at [github.com/deapi-ai/mcp-server-deapi](https://github.com/deapi-ai/mcp-server-deapi) under the MIT license.

#### Prerequisites

* Python 3.10 or higher
* `uv`, `pip`, or `conda` for package management
* A deAPI API key from the [Dashboard](https://app.deapi.ai/dashboard)

#### Quick Start

```bash theme={null}
git clone https://github.com/deapi-ai/mcp-server-deapi.git
cd mcp-server-deapi

# Install dependencies (uv recommended)
uv pip install -e .

# Start the server
python -m src.server_remote
```

The server will start on `http://localhost:8000` by default. For external access:

```bash theme={null}
MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m src.server_remote
```

#### Docker Deployment

```bash theme={null}
# Build and run
docker build -t mcp-server-deapi .
docker run -d -p 8000:8000 --name mcp-server-deapi mcp-server-deapi

# Or with Docker Compose
docker-compose up -d
```

#### Cloud Deployment Options

The server can be deployed to any platform that supports Python or Docker containers: Railway, Fly.io, Heroku, DigitalOcean App Platform, AWS ECS, GCP Cloud Run, and others. Detailed deployment instructions are available in [DEPLOYMENT.md](https://github.com/deapi-ai/mcp-server-deapi/blob/main/DEPLOYMENT.md) in the repository.

#### Connecting a Self-Hosted Server

Point your MCP client to your server URL instead of the default `https://mcp.deapi.ai/mcp`:

```json theme={null}
{
  "mcpServers": {
    "deapi": {
      "url": "http://your-server-ip:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

***

### Supported Models

The MCP server provides access to all deAPI models.

Use the `get_available_models` tool to retrieve the full list with current specifications and limits.

***

### Usage Examples

#### Generate an Image

Ask your AI assistant:

> "Using deAPI MCP, generate an image of an astronaut riding a horse on Mars, photorealistic style"

The assistant will call `text_to_image` with appropriate parameters and return the generated image URL.

#### Transcribe a YouTube Video

> "With deAPI MCP, transcribe this YouTube video with timestamps: [https://www.youtube.com/watch?v=7qaiNfoMRts](https://www.youtube.com/watch?v=7qaiNfoMRts)"

The assistant calls `video_url_transcription` and returns the full transcript.

#### Convert Text to Speech

> "Using deAPI MCP, convert this text to speech with a British female voice: 'Welcome to our platform'"

The assistant calls `text_to_audio` with the Kokoro model and appropriate voice settings.

#### Remove Background from Image

> "Using deAPI MCP, remove the background from this product photo"

The assistant calls `image_remove_background` and returns a transparent PNG.

#### Transcribe X/Twitter Spaces

> "With deAPI MCP, transcribe this Twitter Space: [https://twitter.com/i/spaces/…](https://twitter.com/i/spaces/…)"

The assistant calls `audio_url_transcription` and returns the full transcript.

***

### Architecture

#### Smart Adaptive Polling

For async jobs, the server automatically polls for results with optimized intervals based on job type:

| Job Type | Initial Delay | Max Delay | Timeout |
| -------- | ------------- | --------- | ------- |
| Audio    | 1s            | 5s        | 5 min   |
| Image    | 2s            | 8s        | 5 min   |
| Video    | 5s            | 30s       | 15 min  |

Polling uses exponential backoff (1.5× multiplier by default), so jobs receive fast initial checks while heavier workloads avoid unnecessary load.

#### Token Security

The MCP server does **not** store your API token. Authentication works at the connection level:

* **Remote hosted server**: OAuth 2.0 Authorization Code with PKCE, or Bearer token in HTTP headers
* **Self-hosted server**: Bearer token forwarded per-request to the deAPI API
* Tokens are never persisted or logged; tools do **not** accept `deapi_api_token` as a parameter

***

### When to Use MCP vs HTTP API

| Use Case                                           | Recommended    |
| -------------------------------------------------- | -------------- |
| AI assistants & chatbots                           | **MCP Server** |
| IDE integrations (Cursor, VS Code)                 | **MCP Server** |
| Terminal AI tools (Claude Code, Codex, Gemini CLI) | **MCP Server** |
| Backend services & workers                         | **HTTP API**   |
| Batch processing                                   | **HTTP API**   |
| Direct programmatic control                        | **HTTP API**   |
| Agent-driven workflows                             | **MCP Server** |

Use the **MCP server** when you want an AI agent to decide which tools to call, with which parameters, and in what order. Use the **HTTP API + queue** for typical backend integrations where you directly manage requests and results.

***

### Troubleshooting

#### Connection Issues

* **Verify your API key** is valid and has sufficient balance
* **Check the server URL** is exactly `https://mcp.deapi.ai/mcp`
* **For Claude:** Ensure OAuth Client ID is `deapi-mcp` and Secret is your API key
* **For Cursor / Claude Desktop:** Ensure Bearer token format — the Authorization header should be `Bearer YOUR_API_KEY`

#### Tools Not Appearing

* Restart your MCP client (Claude, ChatGPT, Cursor) after configuration changes
* **In Claude:** Make sure you clicked **Allow** when prompted to grant permissions
* **In ChatGPT:** Ensure Developer mode is enabled in Advanced settings
* Verify JSON syntax in configuration files (Cursor, Claude Desktop)
* Check that your API key has the necessary permissions

#### Jobs Stuck in Processing

* Use `check_job_status` tool with the job ID to monitor progress
* Large video generation or transcription jobs may take several minutes
* Check [status.deapi.ai](https://status.deapi.ai/) for system status

#### Remote Connection Issues (Self-Hosted)

* Test the endpoint: `curl -N http://your-server:8000/mcp`
* Check server logs: `docker logs mcp-server-deapi` or `journalctl -u mcp-server-deapi`
* Verify firewall rules allow the configured port
* For SSL issues, confirm certificates are valid and paths are correct in your proxy config