Connect an MCP client

Subtitles supports the Model Context Protocol (MCP) through host STDIO and an HTTPS/OAuth connection. Open Settings → AI agent connections for the exact commands, Owner selection, and resource URL for your installation.

Choose the access model

For source Compose, an MCP client can launch this command with the app directory as its working directory:

docker compose exec -T kinosail kinosail mcp-stdio

Use Podman when appropriate. Follow the Server’s displayed command when multiple Owners require explicit selection. Removing a host STDIO entry does not revoke the underlying Docker/SSH authority; manage that access separately. Host operations are recorded as Host MCP.

For HTTPS, copy the Server’s resource URL, configure it in a client that supports Streamable HTTP and OAuth, and complete the approval flow. Use trusted HTTPS on a private administration connection. Bearer tokens belong in the Authorization header, never in URLs or prompts.

Built-in OAuth approval lasts up to 30 days. Refresh tokens rotate after each use. Reusing an old refresh token revokes that connection.

Kinosail limits /mcp to 120 requests per minute per network address. Tool calls share a limit of 120 per minute per Profile across HTTPS and host STDIO. If a limit is reached, wait one minute and retry.

Subtitle tools and grants

• read_api with kinosail.read can read the allowlisted /api/v1/subtitle-library inventory. The subtitle endpoint also requires an Owner Profile.
• manage_api with kinosail.manage and an Owner Profile can invoke the allowlisted fetch, wanted-batch, maintenance, provider-test, inspect, draft, preview, apply, replacement, and restore operations.
• kinosail.write covers personal library state; it does not substitute for the management grant needed to change subtitle files.

Generic configuration changes require the browser settings. MCP blocks these mutations to protect identity settings and credentials.

Only approved relative /api/v1 paths are accepted. Discover the Server’s tool schemas before calling them. Responses are bounded JSON. Subtitle export bytes, credentials, sessions, API-key management, and unrestricted filesystem paths are blocked from MCP.

An Owner management connection can call manage_api with {"method":"GET","path":"/api/v1/diagnostics"}. The response includes up to 50 recent failed requests with safe operation names, request IDs, status, level, and duration. It excludes raw log lines, URLs, media titles, credentials, and error text. The private activity journal is not available through MCP.

Begin with inventory and a single explicitly requested operation. Confirm the item, language, and intended replacement before approving a mutation. Provider quotas, input validation, Owner policy, and sidecar protection apply just as they do to HTTP and web requests.

See the HTTP API reference for routes and payloads. Source of truth: internal/server/mcp_route_policy.go and the connection details returned by your installed Server.

Subscribe to updates

Clients that support MCP Events can discover and manage signed webhook subscriptions. The Server advertises events/list, events/subscribe, and events/unsubscribe.

Use a public HTTPS callback and a whsec_ signing secret. The Server verifies the callback before saving a subscription. Notices contain the affected relative API resource path. An optional resource argument filters to one exact path.

Subscriptions last at most 24 hours, with a one-minute minimum. Refresh before refreshBefore to continue delivery. Built-in connection revocation and Profile access changes stop delivery. External OAuth must return client_id; subscriptions expire with its access token. Provider revocation is detected on the next authenticated request.

Cursors are null. Updates missed during downtime cannot be replayed. A refresh reports skipped notices with truncated: true and resumes suspended delivery. Use the ChatGPT Events guide to configure plugin monitoring. Adding an ordinary tool connection does not start monitoring.