API Keys & MCP

Rust-Srec supports long-lived API keys for programmatic access and includes an MCP (Model Context Protocol) server. Its tools let AI assistants such as Claude and Cursor query recordings, analyze danmu, and manage configuration.

API Keys

API keys are an alternative credential to the short-lived JWT session tokens. They belong to the user who creates them and act with that user's permissions, limited by a per-key access level:

Access level	REST API	MCP tools
read_only	Approved non-sensitive queries only	Sessions/danmu, aggregate stats, notification events, and health diagnostics
full	All requests	All tools, including configuration changes

Keys look like srec_<64 hex characters>. Only a SHA-256 hash is stored server-side; the raw key is shown exactly once at creation and cannot be recovered.

Managing Keys

In the web UI, open Settings → API Keys to create, inspect, and revoke keys, and to copy a ready-made MCP client configuration.

Via the REST API (these three endpoints require a JWT session; an API key cannot manage API keys):

# Create (returns the raw key exactly once)
curl -X POST http://localhost:12555/api/auth/api-keys \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ai assistant","access_level":"read_only","expires_at":null}'

# List (metadata only, never the raw key)
curl http://localhost:12555/api/auth/api-keys \
  -H "Authorization: Bearer <access-token>"

# Revoke
curl -X DELETE http://localhost:12555/api/auth/api-keys/<key-id> \
  -H "Authorization: Bearer <access-token>"

expires_at is an optional Unix epoch timestamp in milliseconds; null means the key never expires. Revocation takes effect immediately.

Using a Key

Send the key as a Bearer token:

curl http://localhost:12555/api/sessions \
  -H "Authorization: Bearer srec_..."

Restrictions that always apply, regardless of access level:

• API keys cannot call the key-management endpoints above, POST /api/auth/change-password, or POST /api/auth/logout-all.
• Read-only keys cannot retrieve configuration, streamer overrides, saved proxies, job records, presets, engines, notification channels, backups, or other responses that can contain stored credentials or operational secrets.
• Read-only keys may read authenticated health details and recorded media. Download/log WebSockets, stream proxy requests, and logging configuration or archive routes require full access.
• Keys of a disabled user, or of a user in the forced-password-change state, are rejected.

Media, stream proxy, and download/log WebSocket routes accept a session JWT or an API key with the required access level. Authorization: Bearer <credential> takes precedence. ?token=<credential> is a fallback only when that header is absent; an invalid or malformed header never falls back to a query token. Prefer headers because URLs can appear in browser history and proxy access logs.

Download/log WebSockets revalidate credentials every five seconds with a three-second lookup deadline. Log archive grants retain the issuing session or key identity and revalidate it on their one permitted use. Revoking a browser session does not revoke independently managed API keys; revoke those separately.

MCP Server

The backend serves the MCP streamable HTTP transport at:

http://<host>:<port>/api/mcp

Authentication uses the same header as the REST API (Authorization: Bearer srec_...). A read_only key can inspect recording sessions and danmu, aggregate pipeline stats, notification events, and system health. Mutating tools, outbound URL parsing, and tools that expose stored configuration require full access.

Client Configuration

Most MCP clients accept a JSON entry like this:

{
  "mcpServers": {
    "rust-srec": {
      "url": "http://localhost:12555/api/mcp",
      "headers": {
        "Authorization": "Bearer srec_YOUR_API_KEY"
      }
    }
  }
}

• Claude Code: claude mcp add --transport http rust-srec http://localhost:12555/api/mcp --header "Authorization: Bearer srec_..."
• Cursor: add the JSON above to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).
• Any other client that speaks MCP streamable HTTP works the same way.

Tool Groups

Tools mirror the REST API and run in-process against the same services, so validation and configuration hot-reload behave identically:

Group	Examples	Purpose
config_*, template_*, engine_*	config_get_global, config_update_global, template_create	Read and change the global → platform → template → streamer configuration hierarchy
proxy_list	proxy_list	List saved proxies with their address, username and usage, to find the ID a proxy_route names; passwords are never shown. Proxies are created and edited in the web interface or REST API.
streamer_*, filter_*	streamer_list, streamer_create, filter_create	Manage monitored streamers and recording filters
session_*	session_list, session_danmu_statistics, session_read_danmu	Inspect recording sessions, segments, danmu statistics, and raw danmu XML (byte-paginated)
pipeline_*, job_preset_*	pipeline_stats, pipeline_retry_job, pipeline_list_dags	Observe and operate the post-processing pipeline
notification_*	notification_list_channels, notification_test_channel	Manage notification channels and subscriptions
system_*, parse_url	system_health, parse_url	Diagnostics and live-URL extraction

For danmu analysis, prefer session_danmu_statistics (aggregated totals, rate time series, top talkers, word frequency) over reading raw XML; use session_list_danmu_files + session_read_danmu when the assistant needs actual chat text.

session_read_danmu returns complete UTF-8 characters within the requested byte limit (default 65,536; maximum 262,144). Continue with the returned next_offset; XML nodes may span pages. Use a limit of at least four bytes so any character can fit. Zero limits, offsets inside a character, insufficient space for the next character, and invalid or incomplete UTF-8 in the requested window return errors. Historical corrupt files are not repaired; a file still being written may require a later retry.

Configuration-bearing tool groups (config_*, template_*, engine_*, proxy_list, streamer_*, filter_*, pipeline/job preset and execution-detail tools, notification channel/subscription tools, and parse_url) require a full key even for reads. This prevents a read-only assistant from retrieving platform cookies, processor configuration, notification credentials, stream access data, or other stored secrets.

Security Notes

• Treat API keys like passwords: store them in secret managers, never in shared configs or source control.
• Prefer read_only keys unless the assistant needs configuration or operational details, and set an expiry for keys used in experiments.
• Revoke keys immediately when a tool or machine is decommissioned; once revocation completes, stale cache fills cannot authorize later requests.
• When AUTH_DISABLED=true (loopback-only development mode), /api/mcp is unauthenticated like the rest of the API.