● Operate · AI assistants

MCP server
let an AI assistant work in a workspace.

Vodmill includes a small Model Context Protocol server. An assistant that speaks MCP can bring a video in, wait for the analysis, list the clips and render one, with the rights of one API key and nothing more.

stdio6 toolsNode.js 22+No extra packages

01What it is

The MCP server (src/mcp/server.ts) is a thin layer over the REST API. It talks to the assistant over standard input and output, and to your install over https with an API key. It has no npm dependencies, so it runs on any computer with Node.js 22 or newer that can reach your server. It usually runs on the customer's computer, next to their assistant.

Everything the tools do is what the key may do: one workspace, the plan's limits, the workspace's credits.

02The six tools

Tool	What it does
`get_workspace`	The workspace's name, credit balance and plan with its limits
`import_source`	Brings a long video in from a link and analyses it. Needs `rights: true`: the user owns the content or has the owner's permission to clip it. Costs credits per minute.
`get_source`	A source's status, current step, progress and number of clips
`list_clips`	Clips of the workspace or of one source, with title, times, score, reason, hooks and status
`render_clip`	Queues a clip for rendering in one or more aspect ratios. Costs credits per aspect; they are returned when the render fails.
`get_render`	A render's status and progress and, when done, its files with links that work for one hour

import_source needs import from a link switched on by the operator and included in the plan (Imports).

03Get the two files

After npm run build the server is two files in the product folder:

dist/src/mcp/server.js
dist/src/shared/product.js

As the operator, give customers both files with their folder layout kept (src/mcp/server.js and src/shared/product.js under one folder), or run the MCP server from the product folder itself with npm run -s mcp.

04Run it

It needs two environment variables: APP_URL, the address of your install, and APP_API_KEY, a key from the app's Developers page.

APP_URL=https://clips.your-agency.com APP_API_KEY=vdm_your_key node dist/src/mcp/server.js

It then waits for the assistant on standard input. To check it by hand, send it one request:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  APP_URL=https://clips.your-agency.com APP_API_KEY=vdm_your_key node dist/src/mcp/server.js

It answers with the six tools.

05Connect an assistant

Any MCP client that starts a local command works. Most use a JSON entry like this one (the file and its place depend on the client; see its documentation):

{
  "mcpServers": {
    "vodmill": {
      "command": "node",
      "args": ["/full/path/to/dist/src/mcp/server.js"],
      "env": {
        "APP_URL": "https://clips.your-agency.com",
        "APP_API_KEY": "vdm_your_key"
      }
    }
  }
}

A typical conversation then runs: get_workspace (credits and plan), import_source, get_source until ready, list_clips, render_clip, get_render until done, and the assistant hands over the file links.

06Notes

When run through npm, use npm run -s mcp: without -s npm prints a line of its own that breaks the protocol.
If APP_URL or APP_API_KEY is missing, each tool answers with a sentence that says which one.
Treat the key like a password. Revoke it on the Developers page if the computer is lost.
Protocol revisions spoken: 2025-06-18, 2025-03-26, 2024-11-05.

MCP serverlet an AI assistant work in a workspace.