MCP Troubleshooting

Start with the narrowest failing boundary. Preserve the process error and identities before changing configuration.

Client cannot start the process

1. Run /absolute/path/to/lyftdata --version in a terminal.
2. Run the exact saved command through mcp-server --stdio.
3. Check that the MCP client uses an absolute path and ordered arguments.
4. Confirm the target binary is 3.0.0-beta.5 for these guides.
5. Check the server’s feature response; Deployments may be unavailable even when MCP itself is available.

An stdio process can wait silently. Use the client’s initialize error or a protocol call as evidence; do not diagnose silence alone as failure.

TLS, URL, profile, or login fails

• The evaluation server defaults to https://localhost:3000 with a self-signed certificate. Use --tls-insecure only for that local evaluation.
• Match the URL string and --profile used by auth login and mcp-server.
• Re-run auth login for expired cached credentials.
• For managed automation, prefer an explicit short-lived JWT or API-key path.
• Treat the selected profile’s tokens.yml as a bearer secret.

Session requires explicit scope

A multi-tenant identity cannot safely guess its tenant. Restart the saved MCP registration with --tenant <id> and --environment <id>, then call mcp_server_metrics and tool_inventory again. Never fix a scope error by changing to a broader credential without review.

Expected tools are missing

Check these gates in order:

1. Binary and server release.
2. Server feature/edition availability.
3. Selected tenant and environment.
4. --max-tool-tier (read_only hides mutation tools in beta.5).
5. Server RBAC for the selected identity.
6. Pack, connector, worker, or deployment readiness.
7. Client tool-list cache.

Use tool_inventory for families and tool_get for a live schema. Restart or refresh the client after a tier, Trigger, Pack, or publication change.

Client rejects a tool schema

Record the client version and exact schema error. Refresh the tool list and inspect the current schema with tool_get. Do not add undocumented arguments or a private proxy. If the same beta.5 schema still fails, treat that client as unverified and use a verified client until compatibility is fixed.

Test run does not finish

List transient runs, record the exact run identity, and cancel that run. Check the configured time/event bound, input blocking behavior, and output latency. Do not start repeated tests while the first remains live.

Deployment apply is interrupted

Do not immediately repeat deployment_apply_with_refresh. Inspect the deployment proposal/status and lifecycle events to determine whether the server accepted the apply, is still converging, rejected it, or needs a fresh plan. Preserve the original proposal and plan identity. Retry only when the current release’s status and recovery path make the action unambiguous.

Worker is online but work is not ready

Heartbeat is only control-plane connectivity. Check assignment reconciliation, authorization, connector capability, credentials, source allowlists, storage visibility, placement, generated job health, and recent logs. Use Worker Recovery and Serviceability.

Runtime succeeded but the destination is empty

Correlate the run and time window, then compare input, valid, quarantine, filtered, output, retry, and duplicate counts. Inspect destination-specific responses and perform destination-side readback. A successful MCP tool result or worker log is not an external receipt.

Cleanup is incomplete

Preview cleanup where supported. Match exact run-recorded identities, then re-list deployments, generated jobs, channels, groups, drafts, and external fixtures. Never delete by broad prefix or age. If a cleanup tool requires a higher tier, open a separately reviewed session; do not leave a general destructive session configured.

For platform-wide issues, continue to Troubleshooting.