VidMage MCP

1. Open your user configuration

Install or update Codex, then open ~/.codex/config.toml in a local editor. On Windows, the default path is %USERPROFILE%\.codex\config.toml. If you set CODEX_HOME, use its config.toml. Use this user-level file for VidMage MCP.

2. Add VidMage MCP

Create a dedicated API key in the Developer Console. An active VidMage subscription is required. Replace YOUR_API_KEY only in your local client configuration. Keep the Bearer prefix and do not paste the key into chat or source control.

Prefer the complete configuration shown when you create the key. Its structure is below. Replace an existing [mcp_servers.vidmage] entry instead of adding a duplicate. Preserve all other servers and settings.

[mcp_servers.vidmage]
url = "https://vidmage.ai/api/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }
enabled = true
required = false
startup_timeout_sec = 30
tool_timeout_sec = 120

This is a direct MCP registration. VidMage MCP uses your API key; this setup does not use codex mcp login. Keep required = false so a VidMage connection failure does not block Codex startup. Inspect the direct server error when VidMage is needed. On macOS or Linux, restrict the saved file with the command below. If you use a custom CODEX_HOME, adjust the path to that configuration file:

chmod 600 ~/.codex/config.toml

3. Restart and verify

Run the command below to check the saved entry. Fully quit and restart Codex, then repeat it and open a new task. An existing task may not load newly configured tools.

codex mcp get vidmage

In a new conversation, ask: Use VidMage MCP to call list_capabilities with a small limit. Do not generate anything. A successful tool response verifies authenticated access and consumes no credits.

A saved entry or plugin card alone does not prove that VidMage MCP tools are available. If initialization fails, check the direct vidmage server error and the troubleshooting section.

Client reference: Official Codex MCP documentation.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

1. Register the user-level server

Install or update Claude Code. In Bash or zsh, run this command as shown. On Windows, you can instead add the JSON below directly to your user configuration. It registers a placeholder in the user configuration without putting your real API key in shell history. If vidmage already exists, edit that entry instead.

claude mcp add-json vidmage '{"type":"http","url":"https://vidmage.ai/api/mcp","headers":{"Authorization":"Bearer YOUR_API_KEY"}}' --scope user

2. Add your key locally

Create a dedicated API key in the Developer Console. An active VidMage subscription is required. Replace YOUR_API_KEY only in your local client configuration. Keep the Bearer prefix and do not paste the key into chat or source control.

Open ~/.claude.json in a local editor, or %USERPROFILE%\.claude.json on Windows. If CLAUDE_CONFIG_DIR is set, use the configuration location for that installation. Update only mcpServers.vidmage. Preserve every unrelated setting and server. The complete minimal JSON structure is:

{
  "mcpServers": {
    "vidmage": {
      "type": "http",
      "url": "https://vidmage.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Keep type set to http. A URL without a transport type is not a valid Claude Code HTTP entry.

3. Restart and verify

Restart Claude Code, then run claude mcp get vidmage or claude mcp list. In the session, open /mcp and confirm the server is connected. An Added message only confirms the configuration was saved.

In a new conversation, ask: Use VidMage MCP to call list_capabilities with a small limit. Do not generate anything. A successful tool response verifies authenticated access and consumes no credits.

Client reference: Claude Code MCP reference.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

1. Open the global MCP configuration

Install or update Cursor. Open or create ~/.cursor/mcp.json, or %USERPROFILE%\.cursor\mcp.json on Windows. This global file makes VidMage MCP available across projects.

2. Add VidMage MCP and your key

Create a dedicated API key in the Developer Console. An active VidMage subscription is required. Replace YOUR_API_KEY only in your local client configuration. Keep the Bearer prefix and do not paste the key into chat or source control.

Merge the vidmage entry into the existing mcpServers object. If that entry already exists, replace it. Preserve other servers and valid JSON commas. Use the complete example below only when creating a new file.

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

3. Enable, restart, and verify

Save the file and restart Cursor. Open its MCP settings or Customize panel, enable vidmage, and check its available tools. Follow any client trust or tool approval prompts.

In a new conversation, ask: Use VidMage MCP to call list_capabilities with a small limit. Do not generate anything. A successful tool response verifies authenticated access and consumes no credits.

If tools do not appear, open the Output panel and select MCP Logs. Check the URL and Authorization value. Cursor supports environment interpolation in remote headers, but this example stores the key directly in your private global configuration.

Client reference: Cursor MCP documentation.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

1. Open your user MCP configuration

Install or update VS Code and sign in to GitHub Copilot. In the Command Palette, run MCP: Open User Configuration. This opens the active user profile file; its location varies by operating system and profile. Use the user file for this setup.

2. Add VidMage MCP

Create a dedicated API key in the Developer Console. An active VidMage subscription is required. Merge the vidmage entry into servers and the input definition into inputs. Preserve other entries. Do not duplicate an existing input ID or server. A new file can use this complete JSON:

{
  "inputs": [
    {
      "id": "vidmage-api-key",
      "type": "promptString",
      "description": "VidMage API key",
      "password": true
    }
  ],
  "servers": {
    "vidmage": {
      "type": "http",
      "url": "https://vidmage.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:vidmage-api-key}"
      }
    }
  }
}

Save the file. VS Code will ask for the key when the server starts; paste only the key, without Bearer . The input hides the value and VS Code stores it for later use.

3. Start and verify

Run MCP: List Servers, choose vidmage, and start or restart it. Review the trust prompt. In Copilot Chat, use Agent mode and enable the VidMage MCP tools in the tool picker. Reload the VS Code window if the configuration is not picked up.

In a new conversation, ask: Use VidMage MCP to call list_capabilities with a small limit. Do not generate anything. A successful tool response verifies authenticated access and consumes no credits.

This input-based setup is for VS Code Copilot Chat. Interactive ${input:...} values are not forwarded to Agent Host sessions; use the separate Copilot CLI instructions for that client. VS Code uses the root key servers, while Copilot CLI uses mcpServers.

Client reference: VS Code MCP setup · Configuration reference.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

1. Open the user configuration

Install or update GitHub Copilot CLI and sign in. Open or create ~/.copilot/mcp-config.json, or %USERPROFILE%\.copilot\mcp-config.json on Windows. If COPILOT_HOME is set, use mcp-config.json in that directory.

2. Add VidMage MCP and your key

Create a dedicated API key in the Developer Console. An active VidMage subscription is required. Replace YOUR_API_KEY only in your local client configuration. Keep the Bearer prefix and do not paste the key into chat or source control.

Merge vidmage into the existing mcpServers object and preserve other entries. Replace an existing vidmage entry instead of adding a second copy. A new file can use:

{
  "mcpServers": {
    "vidmage": {
      "type": "http",
      "url": "https://vidmage.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "tools": [
        "*"
      ]
    }
  }
}

Keep tools: ["*"] to make the VidMage MCP tools available. This is the Copilot CLI schema; do not paste the VS Code servers configuration here.

3. Restart and verify

Save the file, restart Copilot CLI, and open /mcp to inspect the server. Follow the client permission prompts. If you prefer the interactive /mcp add form, choose HTTP, enter the same URL and Authorization header, set Tools to *, and save with Ctrl+S.

In a new conversation, ask: Use VidMage MCP to call list_capabilities with a small limit. Do not generate anything. A successful tool response verifies authenticated access and consumes no credits.

Client reference: GitHub Copilot CLI MCP setup.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

1. Prepare the desktop bridge

Install or update Claude Desktop and install a current Node.js LTS release, including npm and npx. Confirm that these commands work in your terminal:

node --version
npx --version

This setup uses mcp-remote, a third-party local bridge, to connect Claude Desktop to VidMage MCP with an API key. The bridge is not a VidMage package. Native remote Custom Connectors use a separate account-level flow; their documented OAuth fields do not provide this static-header configuration.

2. Open the desktop configuration

Open Claude Desktop Settings, then Developer, then Edit Config. The file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

Create a dedicated API key in the Developer Console. An active VidMage subscription is required. Replace YOUR_API_KEY only in your local client configuration. Keep the Bearer prefix and do not paste the key into chat or source control.

Merge vidmage into the existing mcpServers object. Replace an existing entry and preserve other settings. Use the example for your operating system. The key is stored in the local file; do not share the completed JSON.

3a. macOS configuration

{
  "mcpServers": {
    "vidmage": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://vidmage.ai/api/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${VIDMAGE_AUTH_HEADER}"
      ],
      "env": {
        "VIDMAGE_AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

3b. Windows configuration

The Windows example launches npx through cmd. Keep the header argument exactly as shown; the bridge expands VIDMAGE_AUTH_HEADER from its environment.

{
  "mcpServers": {
    "vidmage": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://vidmage.ai/api/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${VIDMAGE_AUTH_HEADER}"
      ],
      "env": {
        "VIDMAGE_AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

4. Restart and verify

Save the file, fully quit Claude Desktop, and reopen it. The first launch needs network access to obtain the bridge package. Open Connectors or Developer settings and check vidmage.

In a new conversation, ask: Use VidMage MCP to call list_capabilities with a small limit. Do not generate anything. A successful tool response verifies authenticated access and consumes no credits.

If startup reports that npx was not found, check the Node.js installation and restart the app. Desktop logs are in ~/Library/Logs/Claude on macOS or %APPDATA%\Claude\logs on Windows. These instructions are based on the documented client and bridge formats; they are not a claim of end-to-end testing on every desktop version.

Client reference: Desktop configuration · Remote connector behavior · mcp-remote bridge.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

Connect VidMage MCP through Gemini CLI's native Streamable HTTP support. Use the user settings file for a personal API key.

1. Open ~/.gemini/settings.json. Create the file if it does not exist. This user configuration applies across projects.
2. Merge the vidmage entry below into the existing mcpServers object. Preserve other settings and server entries. If vidmage already exists, update that entry instead of adding a duplicate key.
3. Replace YOUR_API_KEY with your VidMage API key. Keep Bearer and the space before the key. Save this private user file and keep the key out of shared repositories.
4. Exit and restart Gemini CLI so it reloads the settings.

{
  "mcpServers": {
    "vidmage": {
      "httpUrl": "https://vidmage.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Use httpUrl for Streamable HTTP. Gemini CLI reserves url for the legacy SSE transport.

Run gemini mcp list in your terminal, or /mcp inside Gemini CLI. Check that vidmage is connected and its available tools are listed. If authentication fails, check the API key and Authorization header before retrying.

Official reference: Gemini MCP setup, Gemini configuration.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

Use this configuration for the legacy Cascade agent in Windsurf or Devin Desktop. The current official documentation directs the newer Devin Local agent to the separate Devin CLI configuration described below.

1. Open the MCPs panel in Cascade, or open Settings, then Cascade, then MCP Servers. Open the raw configuration file at ~/.codeium/windsurf/mcp_config.json.
2. Merge the vidmage entry below into the existing mcpServers object. Preserve your other server entries and settings. Update an existing vidmage entry instead of duplicating it.
3. Replace YOUR_API_KEY with your VidMage API key, keeping Bearer and its trailing space. Save the file in this private user location.
4. Restart the application, reopen Cascade, and open its MCPs panel.

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

Select vidmage and confirm that its tools are listed and enabled. Tool discovery is the first setup check. You can then ask Cascade to use an available read-only VidMage MCP tool after reviewing its description.

A team administrator can restrict MCP access or allowed servers. If the configuration is present but the tools remain unavailable, check your team settings as well as the API key.

This file applies to Cascade. Follow the Devin Local / Devin CLI section when using the newer Devin Local agent.

Official reference: Cascade MCP setup.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

Devin Local uses the Devin CLI MCP configuration. This is a separate setup from legacy Cascade. The following example uses an API key in an HTTP Authorization header.

1. Open ~/.config/devin/mcp_config.json on macOS or Linux, or %APPDATA%\devin\mcp_config.json on Windows. Create the user configuration file if it does not exist.
2. Merge the vidmage entry below into the existing mcpServers object. Preserve other servers and settings. Update any existing vidmage entry rather than adding a duplicate.
3. Replace YOUR_API_KEY with your VidMage API key, keeping the Bearer prefix and space. Save the file in this private user location.
4. Restart Devin CLI, or restart the desktop application before opening a new Devin Local session.

{
  "mcpServers": {
    "vidmage": {
      "url": "https://vidmage.ai/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Run devin mcp list to confirm that vidmage is configured. In the agent session, ask it to list the tools available from VidMage MCP and confirm that discovery succeeds.

VidMage MCP uses the API key supplied in headers. An OAuth login or OAuth client ID is not required for this configuration.

These dedicated MCP files apply to Devin CLI v3000.3 and later. Earlier versions store mcpServers in the main config.json files; current versions migrate those entries on startup.

Official reference: Devin MCP configuration.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

Cline supports VidMage MCP through Streamable HTTP in its IDE extension and CLI. Set the transport explicitly so Cline uses the correct connection type.

1. In the Cline IDE panel, open the MCP Servers icon, choose Configure, then click Configure MCP Servers. This opens the settings JSON used by the extension. For Cline CLI, open ~/.cline/mcp.json.
2. Merge the vidmage entry below into the existing mcpServers object. Preserve other server entries and settings. Update an existing vidmage entry instead of creating a duplicate.
3. Replace YOUR_API_KEY with your VidMage API key. Keep Bearer and the space before the key. Save the private settings file and keep it out of shared repositories.
4. Restart the server from Cline's MCP settings. If it does not reload, restart the IDE. For the CLI, exit and restart Cline.

{
  "mcpServers": {
    "vidmage": {
      "type": "streamableHttp",
      "url": "https://vidmage.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Keep type set to streamableHttp. Cline defaults to the legacy SSE transport when this field is omitted.

Check the MCP settings for the available VidMage MCP tools, then test an available read-only tool after reviewing its description. The CLI command cline mcp opens the server management wizard, where you can review enabled status and configuration.

The empty autoApprove list keeps tool calls subject to your normal approval flow. If authentication fails, check the API key and the Authorization header.

Official reference: Cline MCP setup.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

Add VidMage MCP as a remote server in OpenCode. OpenCode uses a top-level mcp object and supports API keys through custom HTTP headers.

1. Open your user configuration at ~/.config/opencode/opencode.json. Create the file if it does not exist.
2. Merge the vidmage entry below into the existing mcp object. Preserve other configuration and server entries. Update any existing vidmage entry instead of duplicating it.
3. Replace YOUR_API_KEY with your VidMage API key, keeping the Bearer prefix and space. Save this private user configuration and keep the key out of shared repositories.
4. Exit and restart OpenCode to load the updated configuration.

{
  "mcp": {
    "vidmage": {
      "type": "remote",
      "url": "https://vidmage.ai/api/mcp",
      "oauth": false,
      "enabled": true,
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Keep oauth set to false for this API key configuration. You do not need to run opencode mcp auth.

Run opencode mcp list to check server status. In an OpenCode session, ask it to list the tools available from VidMage MCP, then test an available read-only tool after reviewing its description.

OpenCode also reads opencode.json from the project root. Project settings can override user settings. If the expected configuration is not active, check for an existing project entry and keep real API keys out of committed files.

Official reference: OpenCode MCP setup, OpenCode configuration.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.

Use the local Kiro IDE user configuration for this setup. Open the command palette and choose Kiro: Open user MCP config (JSON), or open ~/.kiro/settings/mcp.json.

1. Merge the vidmage entry into your existing mcpServers object. Update an existing entry instead of adding a duplicate; preserve other servers and settings.
2. Replace YOUR_API_KEY in this private file with your VidMage API key. Keep the Bearer prefix and its space.
3. Save the file. Kiro reconnects after configuration changes. If needed, reconnect the server from the MCP panel or restart Kiro.

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

Confirm that vidmage is connected and enabled in the MCP panel, then run the read-only connection check in a new conversation.

Official reference: Kiro MCP configuration. This local file is for the IDE setup; other Kiro surfaces may use a different configuration entry point.

Finish by running the VidMage MCP connection check. A saved entry or tool list alone does not prove that an authenticated tool call works.