Configure and Connect

This page is the operator runbook for starting a LyftData MCP session.

Preflight checklist

1. Verify the target URL and auth path with the normal CLI first (and run lyftdata login … if you intend to use cached login; MCP will not prompt interactively).
2. Confirm the target server license enables mcp-server.
3. Decide whether the session will use cached login, --jwt, or --api-key.
4. Decide whether the session must stay read-only or use --allow-write.
5. Use --stdio unless you have a specific operational reason to expose HTTP transport.

Common launch patterns

Read-only stdio with cached login

--stdio is the default if no other transport is selected, but keeping it explicit makes launcher configuration easier to audit.

lyftdata --url https://your-lyftdata.example \
  mcp-server --stdio

Read-only stdio with a named profile

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

Headless stdio with an explicit JWT

lyftdata --url https://your-lyftdata.example \
  mcp-server --stdio --jwt "$JWT"

Headless stdio with API-key-based JWT minting

lyftdata --url https://your-lyftdata.example \
  mcp-server --stdio --api-key "$API_KEY" --ttl 3600

Use this mode when the session will run long enough that in-process JWT refresh is useful.

Write-enabled stdio with activity forwarding

lyftdata --profile ops --url https://prod.example \
  mcp-server --stdio --allow-write \
  --activity-forward \
  --activity-session-label ops-change-window

HTTP transport on loopback

lyftdata --profile staging --url https://staging.example \
  mcp-server --http 127.0.0.1:8765

Use HTTP only when the MCP client cannot spawn a local stdio process. The build must include mcp-http, and the listener should stay on loopback or behind a tightly controlled proxy.

Verify the session

• Ask the MCP client to list tools and confirm the expected read-only or write-capable surface.
• Call mcp_server_metrics and confirm transport, allow_write, and the reported timeout and concurrency settings.
• If you need push notifications, call mcp_notifications_transport_get and confirm that the returned websocket and recent-notification endpoints are reachable from the client.

Troubleshooting

mcp-server exits immediately

Common causes:

• The target server does not enable the mcp-server license feature.
• The client build does not include MCP support.
• --http was requested, but the build does not include HTTP transport support.

The session hits the wrong environment

Check --url and --profile first. Cached logins are tied to the selected environment, so a wrong URL or profile often looks like an auth failure.

Authentication fails

Common causes:

• No cached login for the selected environment.
• Expired or invalid JWT.
• Invalid API key for JWT minting.
• TLS trust mismatch against a private certificate.

For self-signed or private PKI environments, use the same TLS settings you would use with the normal CLI. Prefer fixing trust configuration over weakening TLS checks.

Write tools are missing or rejected

The session was started without --allow-write, or the underlying identity lacks permission for the requested mutation.

Activity feed is empty

Check whether the MCP process was started with --activity-forward. Activity forwarding is opt-in and best-effort.

Push notifications are unavailable

Call mcp_notifications_transport_get first. If the client cannot open the returned websocket endpoint, fall back to job_notifications_recent. Remember that /api/mcp/notifications/* is admin-scoped.