MCP · MODEL CONTEXT PROTOCOLPROPRO ONLY
Your media library,
in your agent's hands.
Point Claude Desktop, Claude Code, Cursor, or any MCP-capable Pro client at MetaTana and your agent can browse, query, dedupe, organize, and clean up — using the same REST surface the app uses, with the same auth as your account.
Requires MetaTana ≥ 1.0.2Free + Pro account · MCP is ProREST passthroughRead-only by default
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"metatana": {
"command": "npm",
"args": ["run", "mcp:stdio"],
"cwd": "/path/to/metatana/app",
"env": {
"METATANA_MCP_BASE_URL": "http://127.0.0.1:3000"
}
}
}
}WHAT IS MCP?PRO
The open standard from Anthropic for connecting AI agents to local tools and data.
Model Context Protocol (MCP) lets a Pro AI client like Claude Desktop, Claude Code, or Cursor connect to local services and use their tools — read your library, run a scan, apply a metadata patch — all under your control.
MetaTana ships its own MCP server for Pro. The bridge verifies a signed-in Pro account before exposing any tools, then forwards your hosted account session to the app so existing route checks decide what each request can do.
TOOL SURFACE · METATANA MCP PRO
Small surface. Full coverage.
metatana_statusApp reachability, local API auth discovery, hosted session discovery, entitlement status.read · idem
metatana_accountVerify Pro account and entitlements without exposing the hosted session token.read · idem
metatana_openapiRead the local OpenAPI contract, optionally filtered by path prefix.read · idem
metatana_workflowsCommon scan, scrape, sidecar, AI, subtitle, sync, and hook workflows.workflow-map
metatana_apiCatch-all REST passthrough. GET / POST / PATCH / PUT / DELETE.full surface
CATEGORY COVERAGE · INSPECT · SCAN · SCRAPE · WRITE · AI · SUBTITLES · TRAKT
WIRE IT UP IN 30 SECONDS PRO
Three clients. Same five-line config.
1
Open Settings → MCP in MetaTana and click Generate token.
2
Open Claude Desktop's config at ~/Library/Application Support/Claude/claude_desktop_config.json.
3
Paste the snippet (right). Replace METATANA_API_TOKEN with the token from step 1.
4
Restart Claude Desktop. The MetaTana server appears in ⚙ MCP Servers.
5
Ask Claude anything about your library. Tool calls show up live in the agent UI.
claude_desktop_config.json
{
"mcpServers": {
"metatana": {
"command": "npm",
"args": ["run", "mcp:stdio"],
"cwd": "/path/to/metatana/app",
"env": {
"METATANA_MCP_BASE_URL": "http://127.0.0.1:3000"
}
}
}
}verify · run metatana_status in your agent
1
Open Settings → MCP in MetaTana and click Generate token.
2
Run the claude mcp add command (right) in your project directory.
3
Claude Code will prompt for any required env vars.
4
Restart Claude Code or reload the workspace.
5
Verify by asking Claude to call metatana_status.
terminal
claude mcp add metatana \ --cwd /path/to/metatana/app \ --env METATANA_MCP_BASE_URL=http://127.0.0.1:3000 \ -- npm run mcp:stdio
verify · run metatana_status in your agent
1
Open Settings → MCP in MetaTana and click Generate token.
2
Open Cursor's Settings → MCP Servers.
3
Click + Add new MCP server, paste the JSON (right).
4
Save and reload the Cursor workspace.
5
The MetaTana tools appear in Cursor's tool picker.
cursor mcp settings
{
"name": "metatana",
"command": "npm",
"args": ["run", "mcp:stdio"],
"cwd": "/path/to/metatana/app",
"env": {
"METATANA_MCP_BASE_URL": "http://127.0.0.1:3000"
}
}verify · run metatana_status in your agent
AUTH MODEL · PRO STARTUP GATE PRO
Pro at startup, then the app's existing route checks decide.
The MCP stdio bridge verifies a signed-in Pro hosted account before exposing any tools. If the account is Free or unverifiable, the bridge exits at startup and the client sees no tools.
After that startup gate, the bridge forwards the hosted session to the app and the app's existing route checks decide whether each request can run. Free routes pass through; Pro routes return 402 when the entitlement is missing and 503 when hosted verification is unreachable.
Credential discovery order · Pro
local api key (Pro) · METATANA_MCP_API_KEY → METATANA_LOCAL_API_KEY → METATANA_API_KEY → settings DB
hosted session (Pro) · METATANA_MCP_HOSTED_SESSION_TOKEN → METATANA_HOSTED_SESSION_TOKEN → desktop hosted-auth store
Settings · MCP
PROAPI Token
mt_•••••••••••••
Connected · Free + Pro routes verified
Connected clients
Common entitlement outcomes
| Status | Meaning | Agent behavior |
|---|---|---|
| Startup failure | The MCP process could not verify a signed-in Pro account. | Stop and ask the user to sign in with Pro or configure the hosted Pro session securely. |
| 200 | The route accepted the request. | Continue to operation or readback verification. |
| 401 | Local API auth or hosted session is missing or invalid. | Stop and ask the user to sign in or configure credentials. |
| 402 | The verified account lacks the route entitlement. | Do not retry until the account or entitlement changes. |
| 503 | Hosted entitlement verification is temporarily unavailable. | Retry later or ask the user to check hosted connectivity. |
USE CASES · AGENT TRANSCRIPTS PRO
Three real things you can ask your agent to do.
Find duplicates in 4K library
metatana_api · GET /api/v1/duplicates
PRO
You
Find any duplicates in my 4K collection and tell me which copy to keep.→ tool · metatana_api
GET /api/v1/duplicates?filter=resolution:2160p← response
{ "duplicates": 3, "items": [ { "title": "Argon 9", "copies": [{"q":"4K HDR · 38.4 GB"}, {"q":"1080p · 8.2 GB"}] }, ... ] }Claude
Found 3 duplicates in your 4K collection.
Argon 9 — Keep the 4K HDR (38.4 GB). The 1080p copy is missing Atmos and HDR metadata. Frees 8.2 GB.
Vesper Line— Keep both. Director's cut adds 23 min and is the canonical version.
Harbinger — Two identical 4K copies. Already resolved via AI.
Argon 9 — Keep the 4K HDR (38.4 GB). The 1080p copy is missing Atmos and HDR metadata. Frees 8.2 GB.
Vesper Line— Keep both. Director's cut adds 23 min and is the canonical version.
Harbinger — Two identical 4K copies. Already resolved via AI.
Build a director collection
metatana_workflows · collection-suggestion
PRO
You
Build me a director set for Christopher Nolan.→ tool · metatana_workflows
{ action: "collection-suggestion", director: "Christopher Nolan" }← response
{ "name": "Christopher Nolan", "titles": 11, "matches": [...] }Claude
I found 11 matching titles in your library across 1998–2023. Want me to create the "Christopher Nolan" collection and add all 11 to it? You can adjust the cover art and ordering afterward.
Audit library health
metatana_api · GET /api/v1/health
PRO
You
Audit my library health and summarize what is broken.→ tool · metatana_api
GET /api/v1/health← response
{ "artwork_coverage": 0.984, "nfo_complete": true, "unmatched": 2, "broken_hardlinks": 0, "drift": "none" }Claude
Health summary:
NFO sidecars — 247/247 complete.
Artwork coverage — 98.4%.
Unmatched titles — 2 files need review.
Broken hardlinks — 0.
Want me to triage the 2 unmatched files?
NFO sidecars — 247/247 complete.
Artwork coverage — 98.4%.
Unmatched titles — 2 files need review.
Broken hardlinks — 0.
Want me to triage the 2 unmatched files?
Ready to hand your library to your agent?
MetaTana ships a Pro MCP server with every Pro account. Includes monthly AI Vision credits so your agent can second-pass hard files without a per-call charge.
PROMCP server requires Pro · See /pricing for tier breakdown