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.

Other assistants¶

The same connector works with any assistant that can start a local program. Gemini CLI, for example, writes the same settings for you:

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

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

If it says the server is disabled because the folder is untrusted, that is Gemini CLI's own folder trust, not a problem with the connector. It disables MCP servers - including ones you added at user level - in any folder you have not trusted, and the assistant then lists no Fast Video Cataloger tools at all. Trust the folder you are working in and it connects.

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.

Connecting ChatGPT¶

ChatGPT is the one assistant that cannot be pointed at fvc-mcp.exe the way the others are. The reason is where it runs: Claude Desktop, Claude Code and the other hosts above run on your computer and start the connector as a program beside them. ChatGPT runs in OpenAI's cloud, so it cannot start a program on your machine and cannot reach localhost - there is no address on your computer that its servers can call.

OpenAI's answer to this is Secure MCP Tunnel. You run a small program from OpenAI, tunnel-client, next to Fast Video Cataloger. It makes an outgoing connection to OpenAI and forwards ChatGPT's requests inward to the connector. Nothing on your machine has to be reachable from the internet, no port is opened, and your API key stays in the local tunnel-client settings and is never sent to OpenAI. As with every other assistant, the catalog and the video files stay where they are.

What you need first

A paid ChatGPT plan with developer mode switched on, under Settings -> Apps -> Advanced settings. Developer mode is what allows a connector of your own.
An OpenAI Platform account at platform.openai.com - this is the developer account, and it is separate from your ChatGPT subscription. From it you create a tunnel, which gives you a tunnel_id, and an API key for tunnel-client to identify itself with.

Both of those are OpenAI's requirements, not ours. If that is more setup than you want, any of the assistants above connects with the single configuration file shown earlier, and does the same work on the same catalog.

Setting it up

Share the catalog and create an API key exactly as in Before you start. Use a Viewer key unless you want ChatGPT tagging your catalog.
Create a tunnel in the Platform settings and note its tunnel_id.
Download tunnel-client from the same page, then point it at the connector:
```
tunnel-client init --sample sample_mcp_stdio_local --profile fvc --tunnel-id YOUR_TUNNEL_ID --mcp-command "C:\Program Files\FastVideoCataloger\fvc-mcp.exe"
```
Put FVC_SERVER_URL and FVC_API_KEY in the profile's environment, the same two settings the configuration file uses.
Check it before involving ChatGPT:
```
tunnel-client doctor --profile fvc --explain
tunnel-client run --profile fvc
```
Leave it running. ChatGPT can only see the connector while tunnel-client run is up.
In ChatGPT, create a developer-mode app, choose Tunnel as the connection, and select your tunnel. Then ask it how many videos are in your catalog - that calls catalog_stats and confirms the whole chain.

If the tunnel does not appear in the list, it is associated with your Platform organisation but not with the ChatGPT workspace you are using. That is fixed in the Platform tunnel settings.

Do not turn off authentication to make this simpler. A catalog with no user accounts accepts every request that reaches it without a key. That is a reasonable trade on your own machine; it is not one to make on a connection that reaches out to the internet.

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.