MCP security and permissions

Enabling Agent access lets a connected client read media, including originals and subtitles. The organization/import switch controls changes to the library; it does not limit access to previews only.

Choose who can connect

Agent access is off by default. In Settings → AI Agent, choose:

Listening scope	Use it when…
This computer only	The assistant runs on the same computer. This is the default.
Computer and LAN	A trusted device on the same private network needs access. Use the displayed LAN URL and the same token.

Keep ClipSeek running while connected. Turning off Agent access or quitting ClipSeek stops the service. Public internet access and external reverse proxies are unsupported; do not forward the port to the internet.

Keep the access token private

The token acts as the connection password. Anyone who can reach the service and has the token can use the enabled tools.

• Paste it only into the trusted client's authentication settings.
• Hide it in screenshots; do not put it in shared chats, public issues, or repositories.
• If it may have been exposed, select Rotate token in ClipSeek and update your client. The old token and existing download links stop working.

For Codex configuration files, reference a local environment variable with bearer_token_env_var; see Connect Codex.

Allow changes when needed

Allow organization and imports is separate and off by default. It permits creating folders, changing tags and folder assignments, and importing files. Imports copy accepted local files into the library. Folder assignments do not move source files on disk.

ClipSeek checks this permission, but does not ask for confirmation on each tool call. Configure approvals in your AI client and ask the assistant to show the planned changes first. You can turn the permission off when finished.

MCP has no tools for deleting or restoring assets, remote uploads, cross-library moves, or creating, deleting, migrating, or merging libraries.

Treat downloads as private links

Originals and generated files use temporary download links, normally valid for 10 minutes. Anyone who can reach the service and has a valid link can download that file. Do not publish, forward, or save the full link as a permanent address.

Previews use registered library resources; the client cannot supply an arbitrary file path to read. Content passed to an AI client is subject to that client's data handling settings, so review those settings before connecting private material.

Technical limits and local audit records

• Each MCP request requires Authorization: Bearer <token>. Authentication failure returns HTTP 401.
• The token is a random 256-bit value stored separately; on Unix it uses owner-only file permissions. ClipSeek does not place it in MCP URLs or application logs.
• MCP: up to 240 authenticated requests per source IP per minute.
• Downloads: up to 120 requests per source IP per minute and four concurrent streams across the service.
• Up to two image/video derivative tasks run at once. Temporary cache capacity is 2 GiB; startup cleanup removes abandoned files older than 24 hours.
• Successful organization actions, download grants, and derivative results are appended to the local mcp-audit.jsonl. It omits tokens, download credentials, complete download URLs, and absolute local paths.

See the MCP reference for request limits and error codes.