Connect an AI Assistant (MCP)¶

Fast Video Cataloger ships an MCP server, fvc-mcp.exe. MCP - the Model Context Protocol - is the standard way an AI assistant connects to an outside system. Point an assistant at this and it can search your catalog, look at scene thumbnails, read transcripts, and organise videos into bins, without you writing any code.

It connects to the Fast Video Cataloger server, not to the Fast Video Cataloger application. Everything goes through the REST API, so a catalog has to be shared before an assistant can reach it - having the program open is not enough. The server runs as a Windows service, so the connector keeps working with the application closed, and it serves whichever catalog was shared rather than whichever one you happen to have open.

Everything stays on your machine: the assistant reaches your catalog through a local address, and no video ever leaves the computer.

Before you start¶

Start the server. In Fast Video Cataloger open Start -> Server, click Setup and follow the wizard. When it finishes you have a server on an address like http://localhost:8754.
Create an API key. In Fast Video Cataloger open Start > Server and click Manage Users - the button appears once the server is running - then click Create key.... No login is needed: the application that shared the catalog is already connected to its own server as the administrator. Give the key the smallest role that does the job - Viewer if the assistant only needs to search and read, Editor if you want it to tag videos and build bins.

The same can be done over the REST API with an administrator session token (log in as admin; the password is admin until it has been changed):
```
curl -X POST http://localhost:8754/api/v1/apikeys \
     -H "Authorization: Bearer ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"my assistant\",\"role\":\"Viewer\"}"
```
The key is shown once, with a Copy button in the window or as data.key in the API answer. It cannot be shown again - a lost key is replaced, not recovered.

Configure your assistant¶

MCP hosts are configured with a small JSON file naming the program to run. The details differ per application, but the shape is the same. For Claude Desktop, the file is claude_desktop_config.json:

{
  "mcpServers": {
    "fast-video-cataloger": {
      "command": "C:\\Program Files\\FastVideoCataloger\\fvc-mcp.exe",
      "env": {
        "FVC_SERVER_URL": "http://localhost:8754",
        "FVC_API_KEY": "fvc_your_key_here"
      }
    }
  }
}

Setting	Meaning
`FVC_SERVER_URL`	Address of your catalog server. Defaults to `http://localhost:8754`.
`FVC_API_KEY`	The API key.
`FVC_MCP_LOG_LEVEL`	`Warning` by default. Set to `Information` or `Debug` when a connection will not come up.

Claude Code writes the same settings for you from the command line, so there is no file to edit:

claude mcp add fast-video-cataloger --env FVC_SERVER_URL=http://localhost:8754 --env FVC_API_KEY=fvc_your_key_here "--" "C:\Program Files\FastVideoCataloger\fvc-mcp.exe"

The quotes around "--" matter in PowerShell, which is the usual Windows shell. Written bare, PowerShell removes the -- before Claude Code sees it and the command fails with error: missing required argument 'commandOrUrl' - no connector is added, and claude mcp list simply will not show one.

claude mcp list then shows the connector and whether it connected.

Restart the assistant and it should list the Fast Video Cataloger tools. Ask it how many videos are in the catalog - that calls catalog_stats and confirms the whole chain works.

Connect from another machine¶

The assistant does not have to run on the machine that holds the catalog. fvc-mcp.exe reaches the catalog over HTTP like any other client, so it only needs to be able to see the server's address - the videos, the catalog and the indexing all stay where they are.

On the machine with the catalog

Share the catalog as above. The wizard sets the server to accept connections from the network, and it reports the address when it finishes - your computer's name rather than localhost, for example http://STUDIO-PC:8754.
Check the port is really open. The server opens its port in Windows Firewall itself when it starts, but it does so quietly - if security software or a group policy stops it, the server comes up anyway and only local connections work. Firewall Setup covers opening TCP 8754 by hand, and testing it.
Change the default admin password and give the assistant its own API key. Every catalog has a built-in admin account with the password admin until it is changed, so once the port is reachable anyone who knows that default can log in as the administrator. See Authentication.

On the machine running the assistant

Install Fast Video Cataloger there too. That is what puts fvc-mcp.exe on the machine, along with the .NET runtime it is built against. You do not have to share a catalog on this machine, and the application does not have to be open - the connector talks to the server on the other machine, not to the program beside it.

Configure the assistant exactly as above, with the server's address in place of localhost:

{
  "mcpServers": {
    "fast-video-cataloger": {
      "command": "C:\\Program Files\\FastVideoCataloger\\fvc-mcp.exe",
      "env": {
        "FVC_SERVER_URL": "http://STUDIO-PC:8754",
        "FVC_API_KEY": "fvc_your_key_here"
      }
    }
  }
}

Use the computer's name if the network resolves it, and its IP address if not. Server Setup shows both.

Check the address from the second machine before you involve the assistant: open http://STUDIO-PC:8754/api/docs in a browser there. If that page loads, the connector will reach the server too, and anything still wrong is the key or the configuration. If it does not, the problem is the network - Test-NetConnection -ComputerName STUDIO-PC -Port 8754 will say whether the port is reachable at all.

Several machines can use one server at the same time, each with its own key, and you can revoke one key without disturbing the others. Give each key the role that machine needs - there is no reason for a laptop that only searches to hold an Editor key.

Things to try¶

Every one of these has been run against a real catalog. Work down the list - it starts with confirming the connection and ends with the assistant doing something for you.

Check it is really connected

How many videos are in my Fast Video Cataloger catalog? One number you can check against your own window. If this is right, the connection, the key and the catalog path are all correct.
Summarise my catalog - how many videos, what kinds of content, and what bins do I have?

Look around

What bins do I have?
Which people are registered in my catalog?
Which videos does [one of those people] appear in? If two people share a name, the assistant will ask which you meant.
What keywords can I search for? Worth doing before any keyword search - a keyword that is not in your catalog just returns nothing. The list is the vocabulary, not a count, and it mixes keywords you typed with ones written automatically by object detection, so it can include things that appear nowhere in your footage.
Are any of my videos still waiting to be indexed?

Find a moment

Which of my videos have someone saying "[a word you know is spoken]" out loud?
What is said in the first couple of minutes of "[one of your videos]"?

Look at the footage

List the thumbnails for "[one of your videos]" with their timecodes, so I can see how it is structured.
Look at a few scenes from "[one of your videos]" and tell me what the footage actually shows. This is the one worth trying first if you only try one. The assistant fetches the actual frames and describes them, rather than guessing from the file name.

Ask it to do something (needs an Editor key)

Create a bin called "Review" and add the videos where someone says "[your word]".

Three things worth knowing before you start:

Transcript search matches the words as they were transcribed. There is no spelling correction, so "colour grading" and "color grading" are different searches and the one that does not match simply returns nothing. If you get no results, try the other spelling or another word. Only videos that have been transcribed are searched at all.
Scenes are thumbnails taken through the video, at whatever interval you indexed with - they are not detected shot changes. A list of scenes tells you how the video was sampled, not where the cuts are.
The assistant cannot undo a bin. It can create bins and add videos, but there is no tool to delete a bin or take a video out of one - do that in Fast Video Cataloger itself.

What the assistant can do¶

Searching

Tool	What it does
`search_videos`	Find videos by free text or by keyword.
`search_scenes`	Find individual scenes, with their timecodes - this is how it finds a moment inside a video.
`search_transcripts`	Find spoken words. Returns the matching transcript lines with their video and timecode.
`search_actors`	Find people by name or tag.

Reading

Tool	What it does
`get_video`	One catalog entry in full.
`get_video_scenes`	A video's scene thumbnails in timecode order.
`get_video_transcript`	The transcript as timed lines.
`get_video_tags`, `get_video_actors`	Keywords and cast.
`get_scene_image`	The actual thumbnail image, so the assistant can see the shot.
`catalog_stats`, `list_bins`, `get_bin_videos`	Catalog size and existing collections.

Organising (needs an Editor key)

Tool	What it does
`tag_video`, `tag_scene`	Add keywords to a video or a single scene.
`untag_video`, `untag_scene`	Remove named keywords again, so the assistant can undo its own mistakes. Only the keywords you name are removed.
`create_bin`, `add_video_to_bin`	Build a collection.
`index_video`, `list_videos_needing_indexing`	Index catalog entries that have no thumbnails yet.

get_scene_image is what makes the difference in practice. The assistant is not guessing from filenames - it can look at the frame and tell you whether the shot is what you asked for.

What it cannot do¶

The MCP server works on the catalog. It cannot capture a single frame at an arbitrary time, drive the video player, or run a specific AI model over one existing thumbnail. Those live in the scripting API, which runs inside the desktop application.

Running it by hand¶

Useful when checking a connection. The server speaks MCP on standard input and output, so on its own it will just sit and wait - that is normal.

fvc-mcp.exe --url http://localhost:8754 --key fvc_your_key_here

If it cannot reach the server it says so, naming the address it tried.

Troubleshooting¶

The assistant lists no Fast Video Cataloger tools. The host could not start the program. Check that the path in the config is the installed fvc-mcp.exe and that the backslashes are doubled, as in the example above. Most hosts keep their own MCP log - that is where the reason appears.

"Could not reach the catalog server." The message names the address it tried. Either the server is not running (open Start -> Server and run Setup again) or FVC_SERVER_URL points somewhere else. Confirm the address answers by opening http://localhost:8754/api/docs in a browser.

"The catalog server rejected the credentials." FVC_API_KEY is missing, mistyped or revoked. Keys are shown once when created, so if it was not saved, make a new one.

"This API key does not have permission for that." The key is a Viewer and the assistant tried to write. Tagging, bins and indexing need an Editor key.

"Indexing is not available on this server." Indexing is done by a helper program that lives in the Fast Video Cataloger program folder, so the server has to be running from a full installation. Everything else works without it.

Nothing obvious in the logs. Set FVC_MCP_LOG_LEVEL to Information. Diagnostics are written to the error stream, never the output stream - the output stream carries the protocol itself and anything else printed there would break the connection.

Security¶

An API key is a long-lived credential. Treat it like a password: it grants whatever its role allows, to anything holding it.
Prefer a Viewer key. Only grant Editor when you actually want the assistant writing to your catalog.
Revoke a key you no longer use with DELETE /api/v1/apikeys/{id}.
The MCP server connects to whatever FVC_SERVER_URL names. Keep it pointed at your own machine unless you have deliberately set up remote access.
A catalog with no user accounts has no authentication at all. The server then accepts every request that reaches the port, with no key, and the assistant works without one. That is reasonable on your own machine and not reasonable on a shared or public network. If the catalog holds anything you would not hand to a stranger, add a user account so authentication is required, and give the assistant its own key.