AI And Agents (Pro)#

MetaTana can be driven through its local API and local MCP bridge. API-key access and MCP are Pro features: both require a signed-in Pro account, and both keep the app's normal permissions and checks in force.

Where you control it#

The running app publishes its API contract at:

• /api/v1/docs for the interactive reference
• /api/v1/openapi for the raw OpenAPI document

For MCP-capable clients, the installed desktop app runs the stdio bridge itself. MCP itself is stdio, so there is no MCP HTTP URL.

The MetaTana app must already be running. The bridge finds the app's current local address on its own, so the configuration never pins a port. Set METATANA_MCP_BASE_URL only to point the bridge at a different running app.

The desktop app encrypts its saved local API key with your system keychain. The bridge started by the installed app can open it. A client that runs the bridge some other way needs METATANA_API_KEY in its env (copy the key from Settings › Maintenance › Advanced › API key); without it, metatana_status says the key was found but is locked. If you move the app data folder to another computer, the app makes a new local API key there; copy the new key into any client that sets METATANA_API_KEY.

MCP Client Setup#

Copy the client configuration from Settings › Maintenance › Advanced › MCP › Set up. It uses your install's exact executable path and data folder. On macOS it looks like this:

{
  "mcpServers": {
    "metatana": {
      "command": "/Applications/MetaTana.app/Contents/MacOS/MetaTana",
      "args": ["--mcp-stdio"],
      "env": {
        "METATANA_DATA_DIR": "/Users/you/Library/Application Support/MetaTana/data"
      }
    }
  }
}

Windows and Linux use the same shape with their own paths. No npm, source checkout or separate Node install is needed.

• Windows: the bridge's replies and errors reach the MCP client the same way as on macOS.
• Linux: the copied command adds --no-sandbox --ozone-platform=headless before --mcp-stdio, so it starts as root and with no display (for example over SSH). A Linux configuration without these two switches won't start that way; copy it again from Settings or add them by hand.
• Linux AppImage: the copied command is the path of the .AppImage file itself, not the temporary folder it runs from while open.

In Claude Code:

claude mcp add metatana \
  -e METATANA_DATA_DIR="$HOME/Library/Application Support/MetaTana/data" \
  -- /Applications/MetaTana.app/Contents/MacOS/MetaTana --mcp-stdio

Headless clients also need a hosted Pro session supplied through a secure secret or environment mechanism (see Credential Discovery).

MCP Tools#

What MCP Can't Change#

An agent reads provider text and NFO plots, which can carry instructions, so the bridge checks every call before it reaches the app. Reads are open. Changes (POST, PATCH, PUT, DELETE) are refused unless the route is library work: scans, scrapes, Arrivals and the Inbox, metadata, NFO and artwork, subtitles, trailers, renames, organize, background work and Undo, duplicates, tags, collections, folders, destinations, media server sync, Trakt sync, backup snapshots, and running a manual tool you already saved.

These are always refused through MCP:

• local and hosted sign-in routes; the agent cannot reveal, rotate, bootstrap, or bypass local authentication
• tools/test and tools/preview, which run a command you didn't save
• creating or editing hooks, webhooks, and manual tools
• every Settings write, including provider keys and AI models
• media server and Trakt sign-ins
• factory and library reset
• backup export and backup restore
• routes that open files in other programs

A refused call fails with a plain message. Make those changes in the MetaTana app.

Credential Discovery#

The bridge reports where credentials were found, never their values.

Local API key lookup order:

1. METATANA_MCP_API_KEY
2. METATANA_LOCAL_API_KEY
3. METATANA_API_KEY
4. the local app setting for api_key (only when the bridge runs through the installed desktop app, or on installs without a system keychain)

Hosted account lookup order:

1. METATANA_MCP_HOSTED_SESSION_TOKEN
2. METATANA_HOSTED_SESSION_TOKEN
3. METATANA_SKYHOOK_SESSION_TOKEN
4. the signed-in desktop hosted-auth store

Each variable above also accepts a _FILE form that names a file holding the value, for example METATANA_HOSTED_SESSION_TOKEN_FILE=/run/secrets/metatana_session or METATANA_API_KEY_FILE. This is the Docker secrets convention. For each name the file wins over the plain variable; a missing or empty file falls back to the plain variable.

Use explicit environment variables for service-style clients and desktop discovery for normal signed-in desktop use. Never place API keys or hosted session tokens in prompts, shared configuration, screenshots, or logs.

AI Credit Limit#

metatana_api sends your hosted session with every call, so an agent stuck in a loop could keep spending AI credits. Each MCP session (one running MCP server) can spend at most 20 AI credits on AI identify and metadata translation.

• Set METATANA_MCP_AI_CREDIT_LIMIT in the MCP client's env block to change the limit. 0 turns AI identify and translation calls off. An invalid value uses the default of 20.
• Cache hits are free. A call that times out or loses its connection counts as spent, because the hosted service may have charged it.
• Once the limit is reached, further AI calls stop with a plain message. Other tools and routes keep working.
• metatana_status shows the limit, what was spent, and what is left for the current session.

Background runs, such as Autopilot, never spend hosted AI credits, so this limit covers only what agents ask for.

Pro And Error Boundaries#

The MCP process verifies Pro before exposing tools. A Free, missing, invalid, or unverifiable account stops startup. After startup, each route still checks that the plan includes it.

Public builds do not honor development auth-bypass variables. Direct API-key callers also need the hosted Pro session described in the API reference.

What Agents Can Do#

Agents can inspect the library, folders, Library health, Activity, background work, and metadata tasks; run scans and scrapes; preview and apply metadata; manage sidecars and artwork; preview rename or organize work; poll background operations; check providers; and create backup snapshots or exports. Pro also covers supported AI, subtitle, and sync workflows, and running manual tools you already saved. Agents cannot create or edit hooks, webhooks, or tools, change Settings or keys, sign in to services, reset MetaTana, or export or restore a backup.

Agents should not:

• call local auth, bootstrap, session, or bypass routes
• expose API keys or hosted sessions
• treat the initial HTTP response as proof that queued file work finished
• retry 402 or startup Pro failures as transient errors
• skip an available preview or dry run before a file-writing action

Recommended Automation Loop#

1. Check status and accountConfirm app reachability, Pro, and that your plan includes the features you need.
2. Read the contractUse metatana_openapi before choosing routes or request shapes.
3. Inspect current stateStart with read-only calls and identify the smallest useful scope.
4. Preview the changeUse the product's preview or dry-run path and respect locked fields.
5. Apply one reviewed changePrefer known title or folder IDs over broad writes.
6. Wait for it to finishPoll the operation URL or Activity when work continues in the background.
7. Verify the resultRead the item again; for sidecars, artwork, or renames, also verify the expected file result.

Troubleshooting#

For full endpoint and command details, see the API reference, CLI reference, and Hosted feature troubleshooting.