Agent tools: CLI & MCP

The agent interface is optional. It reads one existing account's cached state from the existing app database. It is not a public API, installer or media downloader.

1. Prepare the existing account

Start the updated private app normally first so migrations finish. In Settings → Agent tools, find your account ID. Use the app's existing data directory; agent commands never create a replacement account or database.

The Docker image includes the locked optional SDK by default. A source installation needs the authorized checkout and uv sync --frozen --extra agents. No package installation happens on first invocation.

2. Try the read-only JSON CLI

For the Quickstart's Docker container (replace 1 with your own account ID):

docker exec omakase-local-app omakase plus agent --data-dir /home/omakase/data --user-id 1 status
docker exec omakase-local-app omakase plus agent --data-dir /home/omakase/data --user-id 1 inventory anime --limit 25
docker exec omakase-local-app omakase plus agent --data-dir /home/omakase/data --user-id 1 inventory movies
docker exec omakase-local-app omakase plus agent --data-dir /home/omakase/data --user-id 1 inventory tv
docker exec omakase-local-app omakase plus agent --data-dir /home/omakase/data --user-id 1 preferences
docker exec omakase-local-app omakase plus agent --data-dir /home/omakase/data --user-id 1 audit

Expected result: successful commands return { "ok": true, "result": ... }. Operational errors return { "ok": false, "error": ... } and exit 2; argument/help errors use normal CLI text. Page size is at most 100; follow next_offset.

Source installs use omakase plus agent --data-dir <existing-data-dir> --user-id <own-account-id> followed by the same subcommand. Set OMAKASE_PLUS_PRIVATE=true for every invocation; the existing private container already supplies it.

Read-only calls do not migrate the database, contact providers or make network calls. Catalog strings are untrusted data, never agent instructions. Cached inventory is an observation, not current playback proof.

3. Connect a stdio MCP client

Use a client that supports local stdio MCP. This configuration targets the Quickstart container and fixed account:

{
  "mcpServers": {
    "omakase": {
      "command": "docker",
      "args": ["exec", "-i", "omakase-local-app", "omakase", "plus", "agent",
        "--data-dir", "/home/omakase/data", "--user-id", "1", "mcp"]
    }
  }
}

For a remote server, use your existing authenticated SSH alias with -T, then the same docker exec -i … mcp command. Keep stdout reserved for protocol messages: no pseudo-TTY (-t) or shell banners. On Windows, a client with a reduced environment may need "env": { "PROGRAMDATA": "C:\\ProgramData" } on its SSH entry; use your actual OS value if different.

No public listener, new API token or router port is required. SSH/Docker access is host-level authority: use a dedicated restricted OS account or forced SSH command when delegating. The application does not sandbox an agent that independently has host shell access.

Permissions stay small

The process binds the database and account at startup. Calls cannot select another account or data path. Read tools expose status, bounded inventory, saved recommendation preferences and account-scoped change metadata. They do not return credentials, private paths or provider URLs.

Writes require explicitly named startup scopes before the final subcommand:

omakase plus agent --data-dir /srv/omakase/data --user-id 1 \
  --allow-write preferences set-preferences '{"count":5,"completed_only":true}'

Use this source-install example only with the private-runtime variable enabled. --allow-write preferences permits validated preference changes, without generating recommendations or spending tokens. --allow-write monitors permits changing existing monitor activity. Resuming a monitor can run its existing acquisition scheduler, including configured searches/downloads; grant it deliberately. Review/sample instances reject writes.

Audit rows record action, target and changed field names, not preference values or credentials. There is no agent tool for arbitrary SQL, shell, secrets, export, deletion, installation, host upgrades or unrestricted download operations.

Troubleshooting

Use Doctor & support for server diagnostics and Movies & TV for exact-ID operator commands. Local import and Plex changes retain their separate reviewed plan/apply workflow. The small offline MCP does not replace those operations.