# MCP Media Engine — LLM Documentation

MCP Media Engine is an async AI media generation API built for the Model Context Protocol (MCP). It lets AI agents generate images, video, and audio without leaving their workflow.

## What is this?

MCP Media Engine is an MCP-native API for async media generation. AI agents submit a generation job (with text prompt, model selection, webhook URL), receive a job ID immediately, and retrieve the finished asset via webhook or polling. Long-running jobs never block the request thread.

Use this when you are building an AI agent that needs to generate images for blog posts, video clips, voiceovers, product imagery, or social ad variants.

## Primary Use Cases

- **Hero images for agent-written blog posts**: An AI agent writes an article, then calls the MCP tool to generate a hero image matching the article topic.
- **Batch creative testing**: Submit hundreds of image variants, receive assets via webhooks as each completes.
- **Personalized media workflows**: Agents generate tailored product shots, thumbnails, or illustrations on demand.

## API Design

### Job lifecycle

1. **POST /v1/jobs** — Submit a generation job. Returns `{ jobId, status: "queued" }` immediately.
2. **GET /v1/jobs/:id** — Poll for status. Status transitions: `queued` → `processing` → `completed` | `failed`.
3. **Webhook** — When status is `completed`, the asset URL is delivered to your registered webhook URL.

### Media types

| Type | Models | Credit cost |
|------|--------|-------------|
| image | Flux 2 Turbo, Seedance, GPT Image 2, Stable Diffusion | varies per model |
| video | Short-form clip generation | varies |
| audio | Speech, voiceover | varies |

### Batch mode

**POST /v1/batch** — Submit up to 500 jobs in one request. Track each job individually or receive batch completion events via webhook.

### MCP tools

The MCP server exposes tools for each media type:

- `generate_image` — Text-to-image with intent-specific presets (blog_thumbnail, product_shot, social_post)
- `generate_video` — Short-form video generation
- `generate_audio` — Speech and voiceover generation
- `get_job_status` — Poll for job status
- `list_jobs` — List recent jobs with filtering

## Pricing

- **Free tier**: 25 credits, no credit card required
- **Starter**: $29/month, 400 credits
- **Pro**: $79/month, 1,400 credits
- **Enterprise**: Custom volume pricing

Credits are consumed per job. Different models and media types have different credit costs.

See current pricing at: https://mcpmediaengine.com/pricing

## Getting Started

1. Sign up at https://mcpmediaengine.com to get an API key
2. Install the MCP server: `npx mcp-media-engine` (stdio transport) or configure the HTTP/SSE endpoint for web deployments
3. Add to your Claude Desktop config or another MCP-compatible agent
4. Call `generate_image` with a prompt and webhook URL

## Key Terms

- **MCP (Model Context Protocol)**: An open protocol that lets AI agents connect to external tools. MCP Media Engine implements this protocol.
- **Async job queue**: A queue that accepts generation jobs and processes them in the background. Your agent submits a job, gets an immediate job ID, and retrieves the result later.
- **Webhook**: An HTTP POST to your server when a job completes. Enables real-time asset delivery without polling.
- **Batch mode**: Submit hundreds of jobs in one request. Ideal for bulk creative testing.

## Status

- Production-ready with 99.9% uptime SLA
- Supports auto-retry with exponential backoff on failures
- Rate limiting and quota management per API key

## Documentation

- Quickstart: https://mcpmediaengine.com/docs/quickstart
- API Reference: https://mcpmediaengine.com/docs/api
- MCP Integration: https://mcpmediaengine.com/docs/mcp-integration

## Contact

- Docs: https://mcpmediaengine.com/docs
- Email: support@mcpmediaengine.com
- GitHub: https://github.com/mcpmediaengine/mcp-media-engine