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 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 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 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.

• Starting the server without --allow-write keeps mutation tools unavailable.
• Starting with --allow-write only unlocks write-capable tools for that session.
• Write-capable sessions still depend on the permissions granted to the underlying login or token.

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-enabled MCP session (--allow-write).

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

Note

Trigger tools accept the trigger’s parameter schema plus two reserved control keys: _idempotency_key and _wait_timeout_seconds.

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 shape, response-slot result envelopes, and proxy capture behavior, see Triggers.

Tip

Use Configure & Connect for launch commands and troubleshooting, and Examples & Workflows for tool-driven sequences.

Continue with Security & Access for the permission model and observability options.