MCP Setup

MCP lets any MCP-capable AI call VideoFree directly for generation, queries, and project management. It starts with the gateway — no separate MCP service to run.

connection path

AI clientMCP-capable

→JSON-RPC

/mcpstarts with the gateway

→

VideoFree gatewaycapabilities · projects · jobs

→

ComfyUIplugin workflows

a registered plugin shows up in list_capabilities automatically — zero extra MCP configuration

1Confirm the gateway address

Start VideoFree first. The default port is 8765 and the MCP path is fixed at /mcp.

Same machine: use http://127.0.0.1:8765/mcp.
Another machine on the LAN: replace 127.0.0.1 with the gateway machine’s real LAN IP, e.g. http://192.168.50.8:8765/mcp. Never use 0.0.0.0, and never change the path to /sse.

2Paste the client configuration

Add a server named videofree to your AI client’s MCP configuration and paste the JSON below. Some clients require type to be streamable-http — follow your client’s documentation.

{
  "mcpServers": {
    "videofree": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Connecting from another machine only requires replacing the address with the gateway machine’s IP:

{
  "mcpServers": {
    "videofree": {
      "type": "http",
      "url": "http://192.168.50.8:8765/mcp"
    }
  }
}

3Add authentication when a token is set

The token is empty by default and no auth header is needed. If you configured a gateway access token in workspace Settings, add headers to the server configuration and replace the example value with your real token:

{ "mcpServers": { "videofree": { "type": "http", "url": "http://127.0.0.1:8765/mcp", "headers": { "X-API-Token": "your-token" } } } }

Never put tokens into public prompts, screenshots, or code repositories. The HTTP API and MCP share the same token from workspace Settings.

4Refresh tools and verify the connection

After saving, refresh the MCP tool list in your AI client. Have the AI call get_health, list_capabilities, and list_voices first — normal results mean the connection works.

The client must support HTTP POST with JSON responses. Legacy SSE-only clients cannot use this address directly; do not switch the path to /sse.

If the LAN connection fails, check the gateway bind address, the firewall, and that tokens match. A healthy gateway does not mean ComfyUI is connected — if generation fails, re-check the ComfyUI address in Settings.

5Need a smaller tool surface?

The full MCP exposes 30+ tools covering the entire workspace. For fully automated pipelines, you can wrap a narrow MCP containing just the few tools you need over the HTTP API — see Narrow MCP.