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.

If your client has no header field (claude.ai's connector dialog, Claude Cowork, etc.), do not use the bare URL below — it carries no key, so the server has nothing to authenticate with and every tool call fails with an API key error. Skip ahead to claude.ai / Claude Cowork / other connector UIs with no header field and use the URL-embedded key form instead.

Get your API key at muapi.ai/tr/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"
      }
    }
  }
}

claude.ai / Claude Cowork / other connector UIs with no header field

Some Custom Connector UIs — including claude.ai's own Settings → Connectors → Add custom connector dialog (web and desktop) and Claude Cowork — only accept a URL. There's no field for a custom Authorization header, and connectors are stored internally rather than in a config file you can edit by hand. For these, embed your key directly in the URL path instead:

https://api.muapi.ai/mcp/YOUR_MUAPI_KEY

This is equivalent to the header-based URL but works anywhere only a URL field is exposed. Prefer the header form (Authorization: Bearer) when your client supports it — the key ends up in server/proxy logs when passed in the URL.

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
• URL-embedded key (no header support): https://api.muapi.ai/mcp/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_upload_image	Upload base64-encoded image bytes and get back a hosted image_url — for clients with no local file access or outbound network access of their own (e.g. claude.ai's connector UI)	—
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 your client can shell out (has its own network egress), upload 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/..." }

If your client has no outbound network access at all (e.g. a sandboxed agent behind claude.ai's connector, which can only reach muapi through the MCP tool-call channel itself), use the muapi_upload_image tool instead — pass the image as base64 and it returns a hosted image_url you can feed into muapi_image_edit, muapi_video_from_image, etc. Or 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/tr/dashboard and re-add the server:

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

API key / unauthorized error on claude.ai, Claude Cowork, or other header-less connectors

This almost always means the bare URL (https://api.muapi.ai/mcp) was pasted into the connector's URL field with no way to attach an Authorization header — so no key was sent at all, and every tool call fails auth. Remove the connector and re-add it with the key embedded in the URL path:

https://api.muapi.ai/mcp/YOUR_MUAPI_KEY

See claude.ai / Claude Cowork / other connector UIs with no header field.

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/tr/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