MCP Overview

The Model Context Protocol (MCP) is the protocol that lets assistants call structured tools instead of guessing. In LyftData, MCP support is provided by a client-hosted MCP server started with lyftdata mcp-server.

The important architectural detail is where it runs: the MCP server is part of the LyftData client experience, not an always-on server-side component. Your assistant connects to the local MCP process, and that process connects to the LyftData server using the same API and auth path used by the CLI.

Setup and authentication

Most MCP sessions authenticate by reusing a successful CLI login. The MCP server looks for cached login state for the same target URL and profile you start it with.

The MCP server does not run an interactive login flow. If cached login state is missing or expired, re-run lyftdata auth login … with the same --url and --profile you plan to use for MCP (see CLI).

Recommended first-time setup:

export LYFTDATA_URL=https://server-host:3000/
lyftdata auth login admin
lyftdata mcp-server --stdio

If you use profiles, the profile must match at login time and at MCP startup time:

lyftdata --profile prod --url https://prod.example login admin
lyftdata --profile prod --url https://prod.example mcp-server --stdio

Common “looks logged out” causes:

The URL is different (LYFTDATA_URL / --url mismatch).
The profile is different (LYFTDATA_PROFILE / --profile mismatch).
The token in the cached login expired (re-run lyftdata auth login …).

For managed or headless runs, you can provide credentials explicitly:

--jwt "$JWT" uses a bearer token directly.
--api-key "$API_KEY" mints short-lived JWTs on demand (use --ttl to set desired token lifetime).

Transport options

Stdio (--stdio) is the default and recommended transport for desktop assistants and local launchers.
HTTP (--http 127.0.0.1:8765) is an advanced option for environments where the assistant cannot spawn a local stdio process. Treat it as a privileged network surface and keep it bound to loopback or a tightly controlled proxy.

Safety model

LyftData’s MCP surface is designed to be read-first.

The default --max-tool-tier read_only inventory excludes mutation tools.
--max-tool-tier write exposes bounded tests and mutation tools for that process.
--max-tool-tier destructive is a separate ceiling for reviewed destructive work.
Every tier still depends on the permissions granted to the underlying login or token.

--allow-write is a deprecated beta.5 alias for --max-tool-tier write.

That split is deliberate. It lets teams adopt AI-assisted inspection and troubleshooting before they decide whether any session should be allowed to change live state.

What you can do with MCP

The MCP surface is designed for practical operator and authoring workflows:

Inspect jobs, workers, deployments, versions, and runtime signals.
Pull recent notifications and logs for troubleshooting.
Author, lint, and review job changes before you decide to stage or apply them.
Perform controlled operational changes when you intentionally enable writes.

Trigger workflows with Triggers (dynamic tools)

LyftData also supports a Trigger registry: curated, named “run this” actions with schema-validated parameters. When a trigger is published for MCP, it appears as an additional tool in the MCP tool list. Tool names are derived from the trigger slug, for example trigger_invoke__smoke_trigger.

Calling a trigger tool dispatches a message to its target job. These tools are dynamic and per-identity: they show up in the tool list only when MCP publication is enabled and the authenticated identity is allowed to invoke them. Because this is a real runtime action, trigger tools require a write-tier MCP session (--max-tool-tier write).

To track completion, call trigger_invocation_get with the invocation_id returned by the trigger tool.

Refreshing dynamic tools

Most MCP clients cache the tool list per session. If you publish/revise Triggers (or change MCP publication/policy) and do not see updated trigger_invoke__* tools, refresh the tool list by reconnecting the MCP client. If your MCP client does not expose a refresh action, restart the lyftdata mcp-server process.

Reserved key mapping

Reserved MCP arguments map directly to the invoke API fields:

MCP tool arg	Invoke request field	Purpose
`_idempotency_key`	`idempotency_key`	Dedupe retries into one invocation record.
`_wait_timeout_seconds`	`wait_timeout_seconds`	Bound how long the invoke call waits before returning the latest invocation state.

For the dispatch payload, dispatch-only result boundary, and the separate typed synchronous-response contract, see Triggers.

Continue with Security and Tool Tiers for the permission model and observability options.