deAPI MCP Server

deAPI MCP Server

Production-ready Model Context Protocol (MCP) server for the deAPI REST API. This server exposes all deAPI AI capabilities as MCP tools, enabling LLMs to perform audio transcription, image generation, OCR, video generation, text-to-speech, and more.

deAPI v2 — this server targets the deAPI v2 client API (OpenAI-aligned noun paths under /api/v2/*). API v1 is not supported: the tools send v2 payloads only.

Features

• Complete API Coverage: 39 deAPI tools exposed via MCP, covering every v2 client endpoint
• Smart Adaptive Polling: Automatically polls async jobs with optimized intervals based on job type
• OAuth 2.0 Authentication: Secure token exchange via OAuth Authorization Code flow with PKCE
• Error Recovery: Automatic retry logic with exponential backoff
• Progress Reporting: Real-time progress updates to MCP clients
• Type Safety: Full Pydantic schema validation
• Production Ready: Built with FastMCP framework for reliability

Available Tools

Audio Tools

• audio_transcription - Transcribe audio files to text using Whisper models
• audio_transcription_price - Calculate transcription cost
• text_to_audio - Convert text to natural speech (TTS)
• text_to_audio_price - Calculate TTS cost
• text_to_music - Generate music from text description and lyrics
• text_to_music_price - Calculate music generation cost
• audio_url_transcription - Transcribe audio from URLs of completed Twitter Spaces
• audio_url_transcription_price - Calculate Twitter Spaces transcription cost

Video Transcription Tools

• video_file_transcription - Transcribe video files to text
• video_file_transcription_price - Calculate video file transcription cost
• video_url_transcription - Transcribe videos from URLs (YouTube, Twitter/X, Twitch, Kick, TikTok)
• video_url_transcription_price - Calculate video URL transcription cost

Image Tools

• text_to_image - Generate images from text prompts
• image_to_image - Transform images with text guidance
• image_to_text - Extract text from images (OCR)
• image_remove_background - Remove background from images
• image_upscale - Upscale images to higher resolution
• text_to_image_price - Calculate image generation cost
• image_to_image_price - Calculate image transformation cost
• image_to_text_price - Calculate OCR cost
• image_remove_background_price - Calculate background removal cost
• image_upscale_price - Calculate upscaling cost

Video Tools

• text_to_video - Generate videos from text prompts
• image_to_video - Animate static images into videos
• audio_to_video - Generate video conditioned on audio content
• video_description - Describe a video in text (from an uploaded file or a video URL)
• video_upscale - Upscale a video to higher resolution
• text_to_video_price - Calculate text-to-video cost
• image_to_video_price - Calculate image-to-video cost
• audio_to_video_price - Calculate audio-to-video cost
• video_description_price - Calculate video description cost
• video_upscale_price - Calculate video upscaling cost

Embedding Tools

• text_to_embedding - Generate text embeddings for semantic search
• text_to_embedding_price - Calculate embedding cost

Prompt Tools

• prompt_booster - Enhance a prompt for any deAPI inference type using AI guides (synchronous, returns refined prompt directly)
• prompt_booster_price - Calculate prompt-enhancement cost

Utility Tools

• get_balance - Check account balance
• get_available_models - List available AI models with specifications
• check_job_status - Query async job status by ID; with wait_seconds it waits for the job and returns the finished result in the original tool's shape. A failed job reports success: false with error_reason, error_code, retryable and refunded

Webhooks

Every generation tool accepts webhook_url (HTTPS) and an optional webhook_secret (32–255 chars). deAPI calls that URL when the job finishes, signed with X-DeAPI-Signature: sha256= . ")>; the tool still returns the result to the caller as usual.

Model-driven defaults

Generation parameters such as width, height, steps, frames and fps default to the selected model's own values when left unset — each model has different limits, so there is no fixed default that works everywhere. The get_available_models output and every tool description list each model's accepted ranges. Set enhance_prompt: true on text_to_image/image_to_image to let deAPI rewrite the prompt; the result then includes prompt_boost with the prompt actually used.

Installation

Prerequisites

For running the MCP server:

• Python 3.11 or higher
• uv, pip, or conda for package management

For a deAPI account:

• Sign up at deapi.ai and get your API token

Setup

1. Clone the repository:

git clone https://github.com/deapi-ai/mcp-server-deapi.git

cd mcp-server-deapi

1. Choose your Python environment setup:

Option A: Using `uv` (recommended - fastest)

uv pip install -e .

Option B: Using `pip`

pip install -e .

Option C: Using `conda`

# Create conda environment

conda create -n mcp-server-deapi python=3.11 conda activate mcp-server-deapi

Install dependencies

pip install -e .

1. (Optional) Create a .env file for configuration:

# Copy the example file

cp .env.example .env

Edit with your preferences (optional - defaults work fine locally).

Set DEAPI_JWT_SECRET_KEY before exposing the server beyond localhost.

DEAPI_API_BASE_URL=https://api.deapi.ai

DEAPI_HTTP_TIMEOUT=30.0

DEAPI_MAX_RETRIES=3

Usage

Running the Server

The server can run in two modes:

Local Mode (for use with Claude Desktop on the same machine):

MCP_HOST=127.0.0.1 python -m deapi_mcp.server_remote

The server starts on http://localhost:8000. On loopback it may run without DEAPI_JWT_SECRET_KEY (it then signs OAuth tokens with a per-process key, so a restart logs clients out).

Remote Mode (for deployment to a remote server):

# A fixed signing key is required whenever the server binds beyond loopback

(the default host is 0.0.0.0) or uses Redis; without it the server refuses to start.

export DEAPI_JWT_SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))") MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m deapi_mcp.server_remote

See the Remote Deployment section for production deployment options.

Connecting from Claude Desktop / Claude.ai

Option 1: Add Connector (Recommended)

Both Claude Desktop and Claude.ai support MCP connectors with built-in OAuth authentication.

1. Get your deAPI token from deapi.ai
2. In Claude Desktop or Claude.ai, go to Settings → Connectors → Add Connector
3. Fill in the connector details:

Name:              deAPI

Remote MCP server: https://your-server-domain:8000/mcp

▼ Advanced settings OAuth Client ID: deapi-mcp OAuth Client Secret: YOUR_DEAPI_TOKEN

1. Click Add — Claude will automatically authenticate via OAuth and discover all tools.

For details on the OAuth flow, see AUTH.md.

---

Option 2: Config File with Bearer Token (Local Development)

Best for: Server running on the same machine, quick setup without OAuth.

Edit your Claude Desktop config file:

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

{

"mcpServers": { "deapi": { "url": "http://localhost:8000/mcp", "headers": { "Authorization": "Bearer YOUR_DEAPI_TOKEN" } } } }

Replace YOUR_DEAPI_TOKEN with your actual deAPI token. Save the file and restart Claude Desktop.

Using the Tools

Authentication is handled at the connection level, not per-tool-call. Tools do NOT accept a deapi_api_token parameter.

Here's an example workflow:

1. Get available models:

Use get_available_models to see available models

1. Check your balance:

Use get_balance to check remaining credits

1. Generate an image:

Use text_to_image with:

• prompt: "A beautiful sunset over mountains"
• model: "Flux1schnell"

1. Transcribe audio:

Use audio_transcription with:

• audio: "base64-encoded-audio-or-url"
• include_ts: true

Note: When calling tools via Claude Desktop or MCP SDK, authentication is handled automatically through the server connection (OAuth or HTTP headers). See AUTH.md for detailed OAuth setup.

Architecture

Key Components

• DeapiClient (deapi_mcp/deapi_client.py): HTTP client with auth forwarding, built on the deAPI Python SDK transport
• PollingManager (deapi_mcp/polling_manager.py): Smart adaptive polling for async jobs
• Schemas (deapi_mcp/schemas.py): Pydantic models for type safety
• Auth code store (deapi_mcp/auth_code_store.py): single-use OAuth authorization codes, in Redis when DEAPI_REDIS_HOST is set (so any replica can finish a login), otherwise in process memory
• Webhooks (deapi_mcp/webhooks.py): optional HMAC-verified receiver for deAPI completion callbacks, so waiting tools wake on the callback instead of polling (DEAPI_WEBHOOKS_INTERNAL)
• Tools (deapi_mcp/tools/): Organized tool implementations
• audio.py - Audio transcription, TTS & music generation tools
• image.py - Image generation, transformation, OCR, background removal & upscaling
• video.py - Video generation, image/audio-to-video, description & upscale tools
• embedding.py - Text embedding tools
• prompt.py - Prompt booster tools
• utility.py - Balance, models, status tools

Smart Adaptive Polling

The server uses job-type-specific polling strategies:

Polling uses exponential backoff with a configurable multiplier (default: 1.5x, DEAPI_POLLING_ __BACKOFF_FACTOR).

Error Handling

• HTTP Errors: Reads are retried (3 attempts) with exponential backoff; a job submission is retried only when it provably was not processed (rate limited, or the connection never opened), so a job is never submitted twice
• Long jobs: one tool call waits at most DEAPI_TOOL_MAX_WAIT (45 s, below the 60 s call timeout many MCP clients use). A job still running then returns success: true, done: false with its job_id, and check_job_status(job_id, wait_seconds=...) resumes the wait
• Job Failures: Reported with the API's reason, error code, and whether the job is retryable / was refunded
• API Errors: Properly formatted error responses

Configuration

Configuration can be set via environment variables (prefixed with DEAPI_). A variable set to an empty value (DEAPI_REDIS_PORT=) counts as unset and takes the default. Comments go on their own line: some tools (docker --env-file, kubectl create configmap --from-env-file) keep text after a value, # ... included, as part of that value. .env.example lists every variable with its default; the block below shows the common ones.

# API Configuration

DEAPI_API_BASE_URL=https://api.deapi.ai DEAPI_API_VERSION=v2

HTTP Client

DEAPI_HTTP_TIMEOUT=30.0 DEAPI_MAX_RETRIES=3

Seconds one tool call waits before returning done=false and the job_id

DEAPI_TOOL_MAX_WAIT=45.0

Polling Configuration (override defaults)

DEAPI_POLLING