The Model Context Protocol (MCP) lets you connect AI assistants like Claude Desktop directly to Mosaic’s hosted server. Once configured, you can upload videos, run agents, and download outputs using natural language – no local server required.

​
Prerequisites

  1. A Mosaic API key (mk_…) from the Developer Portal
  2. Claude Desktop installed on your machine
  3. Node.js (for npx command)

​
1 · Configure Claude Desktop

Edit Claude Desktop’s config file: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json Add the Mosaic MCP server: 
{
  "mcpServers": {
    "mosaic-api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.usemosaic.ai",
        "--http-only",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

​
2 · Test the connection

  1. Restart Claude Desktop completely (quit and reopen)
  2. Start a new conversation
  3. You should see a small 🔌 icon indicating MCP tools are available
  4. Try asking: “What Mosaic tools do you have available?”
Claude should respond with a list of available tools like upload_video_from_url (upload_video_from_local_file is not supported on the remotely hosted MCP server), create_or_run_agent, etc.

​
3 · Example usage

Once connected, you can ask Claude to:
  • “Upload this video file from this url and create a 30-second trailer with captions”
  • “List my available Mosaic agents”
  • “Check the status of run ID abc123”
  • “Give me the download link for the outputs from my latest agent run”
Claude will automatically call the appropriate MCP tools and handle the Mosaic API interactions for you.

​
Local development (optional)

If you want to run the MCP server locally for development:
  1. Clone the examples repo
  2. Follow the setup in mosaic-mcp/README.md
  3. Change the URL to http://localhost:8000 in your Claude config

​
Troubleshooting

IssueSolution
🔌 icon not showingCheck the config file path and restart Claude Desktop
”Authorization failed”Verify your API key is correct and starts with mk_
”Command not found” errorEnsure Node.js is installed (node --version)
Tools timeoutCheck your internet connection to mcp.usemosaic.ai
The hosted MCP server is the easiest way to get started. For advanced use cases or custom modifications, see the Mosaic MCP Server example.