Security and Tool Tiers

Applies to LyftData 3.0.0-beta.5

Beta.4 uses an explicit maximum tool tier instead of a write/no-write model. --allow-write is retained only as a deprecated alias.

LyftData MCP has two independent gates. The local process exposes tools only up to its configured tier, and the server applies normal RBAC to every request. The effective authority is the narrower of those gates.

Authentication sources

Source	Flags	Best fit	Boundary
Cached login	none	Human desktop session	Reuses the selected profile and URL; MCP never prompts
Explicit JWT	--jwt "$JWT"	Managed short-lived run	The process receives the bearer token directly
API key	--api-key "$API_KEY" --ttl 3600	Headless process	The process mints and refreshes JWTs within the key’s authority

Cached bearer tokens are stored beneath the per-user state directory in lyftdata/cli/tokens.yml, or lyftdata/cli/profiles/<profile>/tokens.yml for a named profile. On Linux the usual root is ~/.local/state. tokens.yml is a bearer credential, not an OS-keyring reference: keep the directory private, preserve owner-only file permissions, exclude it from backups and source control, and revoke the login if the file may have been copied.

Tool tiers

Maximum tier	Use it for	Examples visible in beta.5
read_only (default)	Inventory, diagnosis, plans, previews, evidence	tool_inventory, workflow_recommend, job_yaml_preview, deployment_plan_preview
write	Bounded tests, saved authoring, publication, apply	job_test_run, job_create, workflow_authoring_upsert, deployment_apply_with_refresh
destructive	Reviewed deletion or irreversible cleanup only	Environment-specific; discover live metadata before use

Start separate processes for production inspection and non-production writes. A process started with --max-tool-tier write can expose both read and write tools, but it cannot elevate the server identity. Conversely, a powerful server identity is still locally constrained in a read-only process.

Caution

Preview and plan tools are designed to avoid persistence, but a transient test is execution: it may read a source or call an output within its configured bounds. Read the selected tool schema and the proposed job before calling it.

Scope every session

Pass --tenant and --environment explicitly in saved client configuration. A single-tenant token can be inferred, but an explicit scope is easier to audit. Multi-tenant credentials require a tenant selection before scoped tools can run.

Operator visibility

--activity-forward sends metadata-only tool activity to the LyftData server. It is best-effort and does not forward full request or response bodies. Add --activity-session-label so operators can associate calls with a workstation or approved change window. This activity is a review aid, not a durable full transcript or proof of an external effect.

--otel-tracing exports process traces; mcp_server_metrics gives the fastest in-band check of transport, tier, failures, and timeouts. Admin-scoped notification endpoints still require admin permission.

Operating rules

• Use least-privilege identities and the smallest local tier.
• Review the live tool schema with tool_get before a mutation.
• Keep preview, persist, publish, deploy, apply, and cleanup as separate confirmations.
• Record immutable workflow, plan, deployment, and run identities.
• Treat runtime success and destination acceptance as separate evidence.
• Never paste bearer tokens, raw credential values, or customer payloads into prompts or evidence packets.

Continue with the MCP quickstart or the job-authoring lifecycle.