MCP Server

Connect any MCP-compatible AI assistant to muapi.ai using the Model Context Protocol. Once connected, your assistant can generate images, videos, and audio, edit media, check your balance, and more — all without leaving your editor.

muapi supports two MCP transport modes:

Mode	Best for	Requires
Hosted (Streamable HTTP)	Cursor, Windsurf	Just your API key
stdio via CLI	Claude Code, Claude Desktop	muapi CLI installed

Claude Code users: use the stdio transport (muapi mcp serve), not the hosted HTTP URL. Claude Code's HTTP MCP client does not inject tools into the AI's context — the server will show as "Connected ✔" but no tools will be callable. The stdio transport is the only path that works reliably with Claude Code.

---

Option 1 — Hosted Server (Cursor, Windsurf)

The hosted MCP server at https://api.muapi.ai/mcp follows the standard Streamable HTTP transport. No installation required — just add the URL and your API key to your client.

Not for Claude Code. Claude Code's HTTP MCP client does not inject tools into the AI's context. Use Option 2 (stdio) instead.

Get your API key at muapi.ai/dashboard

Cursor

Open Cmd+Shift+P (or Ctrl+Shift+P) → Open MCP settings and add to mcp.json:

{
  "mcpServers": {
    "muapi": {
      "url": "https://api.muapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MUAPI_KEY"
      }
    }
  }
}

Restart Cursor after saving.

Windsurf

Open Settings → MCP and add:

{
  "mcpServers": {
    "muapi": {
      "serverUrl": "https://api.muapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MUAPI_KEY"
      }
    }
  }
}

Other MCP clients

Any client that supports Streamable HTTP transport can connect. Use the following:

• URL: https://api.muapi.ai/mcp
• Auth header: Authorization: Bearer YOUR_MUAPI_KEY

---

Option 2 — stdio via CLI (Claude Code + Claude Desktop)

Run the muapi CLI as a local stdio MCP server. Requires the CLI to be installed.

# Install the CLI
npm install -g muapi-cli

# Set your API key
muapi auth configure --api-key "YOUR_KEY"

Claude Code (CLI — run once, registers for the current project):

claude mcp add muapi -e MUAPI_API_KEY=YOUR_MUAPI_KEY -- muapi mcp serve

Then start a new Claude Code session. Verify with claude mcp list — you should see Type: stdio and ✔ Connected.

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "muapi": {
      "command": "muapi",
      "args": ["mcp", "serve"],
      "env": {
        "MUAPI_API_KEY": "your-key-here"
      }
    }
  }
}

---

Available Tools

The tool set differs slightly by transport:

Transport	Tools	Notes
Hosted HTTP (https://api.muapi.ai/mcp)	19	Includes search_models; no upload or social tools
stdio CLI (muapi mcp serve)	24	Adds muapi_upload_file + 5 social tools; no search_models

Discovery

Tool	Description	Transport
search_models	Search muapi's model catalog by keyword or category (text-to-image, video, audio, etc.)	Hosted only

Image Generation

Tool	Description	Key models
muapi_image_generate	Generate images from text prompts	flux-dev, flux-schnell, flux-kontext-dev/pro/max, hidream-fast/dev/full, midjourney, gpt4o, seedream, reve, qwen, wan2.1
muapi_image_edit	Edit or transform an image with a text prompt	flux-kontext-dev/pro/max/effects, gpt4o, seededit, reve, midjourney, qwen

Video Generation

Tool	Description	Key models
muapi_video_generate	Generate videos from text prompts	veo3, veo3-fast, veo3.1, veo3.1-fast, kling-master, wan2.1/2.2, seedance-pro/lite/2/2-fast, hunyuan, runway, pixverse, vidu, minimax-std/pro
muapi_video_from_image	Animate an image into a video	veo3, veo3-fast, veo3.1, veo3.1-fast, kling-std/pro/master, wan2.1/2.2, seedance-pro/lite/2/2-fast, midjourney, minimax-std/pro

Audio

Tool	Description
muapi_audio_create	Create original music with Suno (prompt, title, genre tags, instrumental mode)
muapi_audio_from_text	Generate sound effects or ambient audio with MMAudio

Image Enhancement

Tool	Description
muapi_enhance_upscale	AI super-resolution upscaling
muapi_enhance_bg_remove	Background removal
muapi_enhance_face_swap	Face swap in images or videos. Image mode: source_url (face) + target_url (target image). Video mode: source_url (face) + target_url (target video), set mode: "video".
muapi_enhance_ghibli	Studio Ghibli style transfer

Video Editing

Tool	Description
muapi_edit_lipsync	Sync lip movements to an audio track (sync, latentsync, creatify, veed)
muapi_edit_clipping	Extract AI-selected highlight clips from long videos

Async Polling

Tool	Description
muapi_predict_result	Check the status and result of any async generation job by request ID

Account & Keys

Tool	Description
muapi_account_balance	Check your current credit balance
muapi_account_topup	Create a Stripe checkout session to add credits
muapi_keys_list	List all API keys on your account
muapi_keys_create	Create a new API key
muapi_keys_delete	Delete an API key by ID

File Upload (CLI stdio only)

Tool	Description
muapi_upload_file	Upload a local file to muapi.ai and get back a hosted URL for use in generation tools

Hosted MCP users: muapi_upload_file is not available over the hosted HTTP server because it requires local filesystem access. If you need to pass a local file to a generation tool, upload it via the REST API first and use the returned URL:

curl -X POST https://api.muapi.ai/api/v1/upload_file \
  -H "x-api-key: YOUR_MUAPI_KEY" \
  -F "file=@/path/to/your/image.png"
# → { "url": "https://cdn.muapi.ai/..." }

Then pass the url to any tool that accepts image_url or video_url. Alternatively, switch to the CLI stdio transport which includes muapi_upload_file natively.

Social Publishing (CLI stdio only)

Tool	Description
muapi_social_accounts_list	List all connected social accounts (YouTube, TikTok, Instagram) and their IDs
muapi_social_publish	Publish a media URL to a connected social account. Pass scheduled_at (ISO 8601, e.g. "2026-06-15T14:00:00Z") to schedule instead of publishing immediately.
muapi_social_posts_list	List scheduled, published, failed, or cancelled posts
muapi_social_posts_cancel	Cancel a scheduled post or re-queue a failed one
muapi_social_connect	Get the OAuth URL to connect a new social account

---

Example Prompts

Once your client is connected, talk to your AI assistant naturally:

Generate an image:

"Generate a photorealistic mountain lake at golden hour using flux-dev"

Edit an image:

"Remove the background from this image" (attach image URL)

Create a video:

"Make a 5-second cinematic video of a robot walking through a rainy forest using kling-master"

Animate a photo:

"Turn this product photo into a short looping video" (attach image URL)

Create music:

"Create a 30-second lo-fi hip hop track, instrumental only"

Check balance:

"What's my muapi credit balance?"

Find models:

"What video generation models are available on muapi?"

---

How Async Generation Works

Generation tools (image, video, audio) return a request_id immediately:

{ "request_id": "abc123", "status": "processing" }

Your assistant automatically polls muapi_predict_result until the job is done:

{
  "request_id": "abc123",
  "status": "completed",
  "outputs": ["https://cdn.muapi.ai/..."]
}

You can also check manually at any time:

"Check the status of request abc123"

---

Self-Hosted MCP Server

For teams that want to run their own MCP server instance, the muapi-mcp-server repo provides a standalone FastAPI server with the full tool catalog.

git clone https://github.com/SamurAIGPT/muapi-mcp-server.git
cd muapi-mcp-server
pip install fastapi uvicorn requests pydantic
MUAPI_API_KEY=your_key python mcp_server.py

---

Troubleshooting

Tools not available after running claude mcp add (Claude Code)

There are two separate causes — check both:

1. Wrong transport. If you registered the server as HTTP (--transport http), Claude Code shows it as "Connected ✔" but the tools are never injected into the AI's context. Switch to stdio:

   claude mcp remove muapi
   claude mcp add muapi -e MUAPI_API_KEY=YOUR_MUAPI_KEY -- muapi mcp serve
   

2. Session not restarted. MCP tools load at session startup. If you ran claude mcp add inside an active session — including when you ask Claude itself to set it up — you must start a new session before the tools are available.

If you need muapi immediately in the current session, fall back to the REST API directly:

# Submit a job
curl -X POST https://api.muapi.ai/api/v1/flux-schnell-image \
  -H "x-api-key: YOUR_MUAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "..."}'

# Poll for result
curl https://api.muapi.ai/api/v1/predictions/{request_id}/result \
  -H "x-api-key: YOUR_MUAPI_KEY"

---

claude mcp list shows ✔ Connected but tools aren't callable

This almost always means you're using the HTTP transport. ✔ Connected only confirms the server is reachable — it does not mean tools were injected into the AI's tool namespace. Switch to stdio (see above).

If you're already on stdio and tool calls return a 403 or auth error, the API key is wrong or expired. Get a fresh key at muapi.ai/dashboard and re-add the server:

claude mcp remove muapi
claude mcp add muapi -e MUAPI_API_KEY=YOUR_NEW_KEY -- muapi mcp serve

Not authorized: missing or invalid credentials error

The CLI reads your key from ~/.config/muapi/config.json. That file can hold a stale or invalid key left over from a previous install — the CLI won't warn you and will silently return a 401.

Run muapi auth login to fetch a fresh key automatically (prompts for email + password):

muapi auth login

Or paste a key directly from muapi.ai/dashboard:

muapi auth configure --api-key "YOUR_KEY"

After saving the key, re-add the MCP server so Claude Code picks it up:

claude mcp remove muapi
claude mcp add muapi -e MUAPI_API_KEY=YOUR_NEW_KEY -- muapi mcp serve

Then start a new Claude Code session.

---

Claude Desktop shows "tools missing" but the server works in terminal

Claude Desktop launches the MCP server in a clean environment that does not inherit your shell's env vars. The server starts but fails to load without MUAPI_API_KEY. Pass the key explicitly in claude_desktop_config.json:

{
  "mcpServers": {
    "muapi": {
      "command": "muapi",
      "args": ["mcp", "serve"],
      "env": { "MUAPI_API_KEY": "your-key-here" }
    }
  }
}

search_models is not available

search_models is only available on the hosted HTTP transport. If you are using the CLI stdio server (muapi mcp serve), this tool is not present.

muapi_upload_file is not available

muapi_upload_file is only available on the CLI stdio transport. See the File Upload section above for the hosted MCP workaround.

---

Related

• MuAPI CLI — Terminal interface with its own muapi mcp serve stdio command
• Agent Skills — Shell script skills for Claude Code, Cursor, Gemini CLI
• Authentication — API key management
• API Reference — Full REST API docs