Matching with an AI assistant (MCP)

Credenza speaks the Model Context Protocol (MCP), so an AI assistant that supports MCP, such as Claude Code, can work through your Needs matching list and say what each title is.

This helps most with the titles automatic matching gives up on. A file called Akira.1988.1080p.BluRay.x264-GROUP.mkv is obvious to an assistant, and so is an anime release named with the Japanese title. The assistant looks at your files, searches the same metadata providers you would, and picks the right record.

Credenza doesn’t include or call any AI model itself, and it never asks for an AI provider’s key. The assistant runs wherever you run it and connects to your server as a client.

What an assistant can do

The endpoint offers seven tools. Six cover identifying titles, and one reads the server’s log.

Tool	What it lets the assistant do
list_libraries	See your libraries: their names, kinds (Movies, Shows, Anime, Games) and, for a games library, its console
list_unmatched	Go through the titles waiting in Needs matching, one kind at a time. It sees each title’s files on disk, with their paths, runtime, container format and size
get_library_item	Read one film, show or game in full, including one that’s matched to the wrong thing and so isn’t in the unmatched list
search_match_candidates	Search TMDB, or for a game every game provider you’ve switched on, for records the title could be. This changes nothing
assign_match	Say which record a title is. This is the correction
refresh_match	Ask the providers again about a title, keeping the record it’s already matched to. This fixes stale or half-downloaded details
read_logs	Read the server’s log, newest first, the same entries you see at Settings → Server → Logs. It can narrow by level, by text in the message or error, by the part of the server that wrote the entry, by time, or to everything one request wrote. This changes nothing

assign_match is the only tool that changes anything. It works like choosing a match yourself with Fix match…: the new title, artwork and synopsis arrive shortly after, a later correction by you overrides it, and the choice is saved in the match file next to your media. Correcting a show re-matches every episode under it. An assistant can’t correct a single episode on its own.

With read_logs, you can ask an assistant why something went wrong, such as “Why did last night’s scan skip files?” or “Look at the latest errors on my Credenza server and tell me what’s causing them.” It finds the error, then reads what else happened during the same request.

An assistant can’t delete items, edit titles or other details, start scans, or touch accounts, playback or any other setting. See Fixing matches for doing the same work by hand.

Turn the endpoint on or off

The endpoint is on by default, but it answers nothing until someone creates an API key. To control it, go to Settings → Server → Integrations and use Answer on the MCP endpoint.

When it’s off, the endpoint’s address returns not found, as if it didn’t exist. The change applies from the next request, with no restart. Your keys are kept and work again when you turn it back on.

Managing this page needs the Manage integrations permission, which administrators have.

Create an API key

An assistant can’t sign in with a password, so it uses an API key instead.

1. Go to Settings → Server → Integrations and select New key.
2. Under What is it for, give it a name you’ll recognise later, such as Claude Code on the laptop.
3. Under Expires, choose Never, 30 days, 90 days or A year. A key that never expires is right for a client you use every day. Choose a deadline for something temporary. You can’t extend an expiry later.
4. Select Create key.
5. Copy the key now. This is the only time it’s shown. Credenza stores only a hash of it, so it can’t be looked up again. If you lose it, revoke it and make another.
6. Select I’ve saved it when you’re done.

Each key in the list shows its name, whether it’s Active, Expired or Revoked, the first few characters of the key, when it was last used, when it expires, and which account it acts as. Every administrator sees every key. Select Revoke to stop a key working at once.

A key acts as the account that made it. It only works on the MCP endpoint and can’t open the rest of the server. The endpoint only accepts keys belonging to an administrator account, so a key made by an account that later stops being an administrator stops working.

Connect a client

The Integrations page shows the endpoint address under MCP endpoint. It’s your server’s address followed by /mcp:

https://media.example.com/mcp

The address uses the Public address from Settings → Server → General if you’ve set one, and otherwise the address your browser is on. If your assistant will reach the server by a different name, set the public address so the page shows the address the client will actually use.

The endpoint uses MCP’s streamable HTTP transport. The client sends the key in an Authorization header:

Authorization: Bearer YOUR_API_KEY

Under Add this server to a client, the page shows ready-made commands for three clients. Right after you create a key, the commands include it, so you can copy and run them as they are.

Claude Code

claude mcp add --scope user --transport http credenza https://media.example.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

Codex reads the key from an environment variable, so put the first line in your shell profile rather than typing it into one terminal:

export CREDENZA_API_KEY="YOUR_API_KEY"
codex mcp add credenza --url https://media.example.com/mcp --bearer-token-env-var CREDENZA_API_KEY

opencode writes the header as KEY=VALUE:

opencode mcp add credenza --url https://media.example.com/mcp --header "Authorization=Bearer YOUR_API_KEY"

Any other client that supports streamable HTTP and a custom Authorization header will work the same way.

Once connected, ask it something like “Go through the unmatched films on my Credenza server and fix the ones you’re confident about.” The assistant works in batches. After it assigns a match, the new details take a moment to arrive.

Security

• Treat a key like a password. Anyone holding it can list your libraries, read file paths and change matches as its account. Revoke any key you no longer use, and give temporary keys an expiry.
• Use HTTPS if the endpoint is reachable from outside your network. Over plain HTTP, the key travels unencrypted with every request.
• Your file paths go to the assistant. The tools show the assistant file paths, file names, runtimes and sizes from your libraries. Wherever the assistant sends what it reads, those details go too.
• Your log goes to the assistant too. read_logs shows the assistant log entries, which can include file paths, titles, the addresses of requests and error details.
• Check the list now and then. Last used shows whether a key is in use. Credenza doesn’t keep a separate record of each change a key made. A match an assistant chose looks the same as one you chose.
• Switch the endpoint off under Settings → Server → Integrations if you don’t use it. The address then answers as if it didn’t exist.