Stackless MCP

stackless-mcp is a local stdio MCP server for Claude Code, Codex, and other terminal agents. It exposes Stackless app capabilities as MCP tools by calling a deployed Stackless instance over /api/v1.

The MCP process is intentionally thin. It does not import middleware-service, does not need Snowflake or dbt credentials, and does not read local app data. Stackless remains the source of truth for auth, RBAC, ownership, and mutations.

Use this guide when connecting a terminal agent to your own Stackless instance from the published stackless-mcp package. Development from a monorepo checkout is covered separately at the end.

Prerequisite

Install uv. The agent configuration uses uvx, which is included with uv and fetches the pinned stackless-mcp package on first run.

Install

Pin the beta version exactly in your agent configuration: stackless-mcp==<version>. The MCP server also needs the base URL for your Stackless instance.

Codex

Add this block to ~/.codex/config.toml:

[mcp_servers.stackless]
command = "uvx"
args = [
  "stackless-mcp==<version>",
  "--base-url",
  "https://your-stackless-instance.example.com",
]

Claude Code

Add this block to .mcp.json:

{
  "mcpServers": {
    "stackless": {
      "command": "uvx",
      "args": [
        "stackless-mcp==<version>",
        "--base-url",
        "https://your-stackless-instance.example.com"
      ]
    }
  }
}

Login

Run login once before starting Codex or Claude Code:

uvx stackless-mcp==<version> login \
  --base-url https://your-stackless-instance.example.com

login opens the Stackless browser auth flow, receives a local callback from the authenticated browser session, exchanges it for a scoped slmcp_ MCP session, and stores that session locally. The server-side session defaults to a 30-day TTL. Your Stackless instance can lower that lifetime with MCP_SESSION_TTL_SECONDS.

Credentials are stored in the OS keyring by default. If keyring support is not available, use file storage:

uvx stackless-mcp==<version> login \
  --base-url https://your-stackless-instance.example.com \
  --auth-storage file

With --auth-storage file, credentials are stored as a 0600 credentials.json file in the platform user config directory for stackless-mcp. If you use file storage for login, add "--auth-storage", "file" to the agent configuration too.

Verify

uvx stackless-mcp==<version> --version
uvx stackless-mcp==<version> doctor \
  --base-url https://your-stackless-instance.example.com

Run doctor first when setup does not work. It checks local configuration, stored auth, Stackless API connectivity, and server capability discovery.

Example successful output:

{
  "auth": {
    "credential_present": true,
    "expires_at": "2026-07-10T12:00:00Z",
    "expiry_status": "unexpired",
    "mode": "stored_token",
    "storage_backend": "keyring",
    "token_present": true,
    "user_id": "user_123"
  },
  "auth_storage": "keyring",
  "base_url": "https://your-stackless-instance.example.com",
  "capabilities": {
    "checked": true,
    "client_known_unsupported_by_server": [],
    "error": null,
    "ok": true,
    "server_supported_unknown_to_client": [],
    "server_version": "2026.06.10"
  },
  "client_version": "<version>",
  "connectivity": {
    "checked": true,
    "ok": true
  },
  "errors": [],
  "ok": true,
  "toolsets": [
    "all"
  ]
}

doctor exits 0 when required checks pass and exits 1 for local configuration, auth, or connectivity failures. Missing command arguments and invalid CLI options exit 2.

Troubleshooting

• Missing base URL: pass --base-url https://... in the agent config and login command, or set STACKLESS_BASE_URL.
• Expired or missing token: run uvx stackless-mcp==<version> login --base-url https://your-stackless-instance.example.com again.
• Server capability delta: doctor reports tools known by the client but not supported by the server under client_known_unsupported_by_server. Upgrade the Stackless instance when you need those tools; otherwise the client simply advertises the supported subset.
• Connectivity failure: confirm the base URL is reachable from your machine, uses the correct scheme, and includes no /api/v1 suffix.
• Keyring failure: rerun login and your agent command with --auth-storage file.

For a one-shot connectivity check without starting MCP stdio, run:

uvx stackless-mcp==<version> \
  --base-url https://your-stackless-instance.example.com \
  --check

--check uses the stored MCP session when present and exits. Expired sessions prompt a fresh stackless-mcp login instead of failing with an opaque MCP startup error.

Upgrade

Upgrade by changing the pinned package version in your Codex or Claude Code configuration, then restart the agent. Pre-release versions follow PEP 440: beta releases must be pinned exactly. For example, change stackless-mcp==<old-version> to stackless-mcp==<new-version> when the new beta is published.

Revoke or Reset Auth

uvx stackless-mcp==<version> logout \
  --base-url https://your-stackless-instance.example.com
uvx stackless-mcp==<version> reset-auth \
  --base-url https://your-stackless-instance.example.com

logout calls /mcp/auth/revoke and then deletes the local credential. reset-auth only deletes the local credential, which is useful for stale or corrupt local state; the server-side session remains valid until it is revoked or expires.

To rotate a file-backed credential, run logout with --auth-storage file, then run login --auth-storage file again. Delete any copied backups of the old file credential as part of rotation.

Advanced: Toolsets

This is not part of basic setup. By default, the full supported tool set loads and the agent decides which tool to call at runtime. Tool selection is automatic and is not a setup choice.

Use --toolsets only when you intentionally want to reduce the loaded tool-schema surface and agent context:

[mcp_servers.stackless]
command = "uvx"
args = [
  "stackless-mcp==<version>",
  "--base-url",
  "https://your-stackless-instance.example.com",
  "--toolsets",
  "catalog,runs",
]

Valid toolsets are all, core, catalog, runs, transformations, semantic, dashboards, lifecycle, fivetran, support, and monitors. all is the default. Core tools for auth checks and operation status are always registered; selecting core registers only those tools. Toolsets are a runtime ergonomics feature, not a security boundary. Stackless backend RBAC and tool permissions still enforce access.

Development

Use this path only when developing stackless-mcp from a monorepo checkout:

cd stackless-mcp
poetry install --with dev
poetry run stackless-mcp login \
  --base-url https://your-stackless-instance.example.com
poetry run stackless-mcp \
  --base-url https://your-stackless-instance.example.com

Manual token/cookie setup remains for development and compatibility only:

export STACKLESS_BASE_URL=https://your-stackless-instance.example.com
export STACKLESS_TOKEN='<valid Stackless/Cognito JWT or slmcp token>'
# or, for browser-cookie development auth:
# export STACKLESS_COOKIE='AWSALB=...; AWSELBAuthSessionCookie-0=...'
poetry run stackless-mcp

Tool Surface

Prefer these workflow-style tools for new agents:

get_stackless_connector_status reads the Stackless catalog snapshot. The fivetran toolset calls live Fivetran operational APIs through middleware workflow handlers and keeps secret config values redacted.

For dashboard edits, start with get_stackless_dashboard for a compact summary bounded below 20 KB with the current spec_revision. It includes widget IDs, sections, layout, filter summaries, and query members when they fit. Larger summaries explicitly list omitted details in summary_omitted_fields; null structure fields mean omitted, not empty. Follow next_summary_offset by passing summary_offset until it is null to discover every widget ID. Summary pages are not writable specs. Use widget_ids or section_id to fetch complete definitions for the widgets you will edit. widget_offset and widget_limit page through full widget definitions (widget_offset is nonnegative and widget_limit is 1 through 10); next_offset=null marks the last page. Choose only one of widget IDs, section ID, or widget paging; summary paging cannot be combined with these selectors or full reads. view="full" without selection returns the complete replacement spec. Partial reads return spec=null and spec_complete=false so they cannot be mistaken for replacement specs. returned_size is the response size in UTF-8 bytes. The permission-filtered workflow remains available on every read; its detailed authoring_guidance appears with full reads. Fork published dashboards before editing, preserve unrelated content, and obtain approval before publishing. Guidance is advisory, not an access grant or a guarantee of model compliance.

Complete dashboard spec readbacks and save responses use redaction without size cuts. spec_complete, truncated_fields, and redacted_fields identify the completeness state; a spec with secret-looking keys or values that were replaced by [redacted] is not complete. Use granular edits that do not resubmit redacted fields. upsert_stackless_dashboard_widget replaces the entire widget and requires complete, unredacted widget content. Both widget upserts and update_stackless_dashboard_draft reject truncation and [redacted] markers. Whole-spec replacement also refuses to remove stored widgets unless the caller passes their exact IDs as remove_widget_ids or sets allow_widget_removal=true. Hosted MCP errors preserve the complete removed-ID and marker-path lists. After these explicit refusals, correct the payload and retry with a new idempotency key. Preview and hydration responses report each returned widget's real row_count and truncated flag, plus truncated_fields and total/returned widget counts.

validate_dashboard_draft(dashboard_ref=..., spec=...) validates the supplied candidate through the same member, layout, and query checks used by dashboard writes, without saving it. Use this for read-only access or candidates you do not want persisted; otherwise save directly because write tools run the same checks and never persist an invalid spec. For a candidate, use the dashboard_ref of the private draft or fork you will save to. Published refs use live models only and cannot validate private draft members. Omitting spec validates the stored spec; omitting dashboard_ref validates the candidate as the caller's own new draft, so the caller's private draft models count. One call reports every violation: validation.valid is false only when validation.errors is non-empty, and each error or warning carries code, widget_id (null for dashboard-wide issues) and message. Errors block a save; warnings (for example a KPI that mixes models) do not. Validation can execute Cube queries but does not persist dashboard changes. Hydration always reads the stored spec and rejects authoring fields inside its runtime request.

Mutating tools require an idempotency_key. Publish, refresh, unpublish, cancel, delete, guarded Fivetran operations, and dashboard export schedule mutations also require confirmation={"confirmed": true, "evidence": "..."}. For dashboard drafts, first call diff_stackless_draft("dashboard:<id>"), using its optional request argument for non-default preview filters or table overrides, and pass the returned review object as publish_context={"review": review} to publish_stackless_draft. Stackless rejects stale dashboard fingerprints if the draft changes between review and publish. For Semantic Model drafts, first call diff_stackless_draft("semantic_model:<id>") and pass the returned review object as publish_context={"review": review}. Use the returned confirmation_phrase as confirmation evidence; Stackless rejects stale semantic-model fingerprints if the draft changes between review and publish. For draft_transformation_model, an idempotency_key is required only when a spec is supplied and a draft is created.

Managed Transformation Workflow

For managed Transformation Models, use middleware-backed tools for lifecycle state and catalog-backed tools for discoverability:

1. Create or update a draft with draft_transformation_model.
2. Validate and preview it with validate_transformation_model_draft and preview_transformation_model_draft, polling returned operations with get_stackless_operation.
3. Review the publish diff with diff_stackless_draft, then publish with publish_stackless_draft and explicit confirmation.
4. Verify middleware source-of-truth state with get_stackless_transformation_model. This is the tool for published version, materialization, identity, incremental config, relation metadata, refresh policy, and timestamps.
5. Use explain_stackless_asset after catalog refresh when you need catalog visibility, lineage, columns, or downstream dependency context.
6. Estimate refresh scope first with estimate_stackless_refresh. Use the returned refresh estimate, fingerprint, confirmation requirement, and operation ref before queueing a refresh.
7. Queue the refresh with refresh_stackless_resource, passing the estimate identifiers, explicit confirmation, and an idempotency_key. Poll the returned operation ref and use diagnose_stackless_run for run details.

Safe Transformation Model fix flow:

1. Call get_stackless_transformation_model("transformation_model:<published-id>") or get_transformation_model("transformation_model:<published-id>") and inspect the full spec, published relation, status, version, and ownership metadata.
2. Call fork_transformation_model("transformation_model:<published-id>", idempotency_key="...") and use the returned data.draft.refs.draft_ref.
3. Call update_transformation_model_draft(draft_ref, idempotency_key="...", spec=..., title=..., description=..., refresh_policy=...). Write tools return a compact data.draft: refs, status, version, draft_spec_hash (the value preview and publish review check), the contract, preflight_warnings, and normalized_changes for anything the server defaulted or rewrote. They do not echo the spec; pass include_spec=true to get the normalized spec once.
4. Read back with get_stackless_transformation_model(draft_ref) or get_transformation_model(draft_ref), then run validate_transformation_model_draft(draft_ref) and preview_transformation_model_draft(draft_ref, idempotency_key="...").
5. Call diff_stackless_draft(draft_ref) and pass the reviewed publish context to publish_stackless_draft with explicit confirmation evidence.

Endpoint-shaped compatibility tools are no longer registered. Use the workflow-style tools above for all new MCP agent flows.

Safety annotations

Every registered tool has explicit MCP safety hints from the shared policy. See SAFETY.md for classification rationale, registration checks, and contract-generation instructions. Annotations inform approval; backend authorization and confirmation requirements still apply.

Operation polling details

get_stackless_operation(operation_id) returns compact preview/lifecycle results. Preview results include dbt PASS/WARN/ERROR/SKIP/TOTAL counts, failing node lines, exit code/duration, preview hashes/relation, sample row count, column names, and up to three sample rows. Counts are null when dbt did not emit a summary. When present, they also include the estimate-mode cost_estimate, a bounded union_diagnostics summary, and the scaffolded Semantic Model draft (cube_draft_id/cube_draft_name). Publish results include materialization_status and last_materialization_error, because a publish can succeed while its materialization is queued or failed.

Request include=["sample_rows", "compiled_sql", "logs", "generated_files"] for additional details, each returned once. Sample rows and long details remain bounded; truncated_fields identifies cuts and compiled_sql_truncated includes the MCP SQL limit. Logs omit the project-parse preamble and retain the tail and dbt outcome lines. Model definitions/specs are fetched with get_transformation_model, rather than echoed by operation polling. The webapp preview-events API retains its existing payload.

diff_stackless_draft(include_preview=False) returns transformation preview references, fingerprints, dbt counts/failing nodes, union branch row counts and type/null warnings, and the sample and column counts without sample rows, column names, or raw logs. True includes column names, up to three rows, and a bounded log tail without project-parse warnings. Both modes preserve the identical publish handoff. When the caller started the preview through MCP, a details_request points to operation polling for further details; previews from the webapp, the in-app agent, or another user carry a details_hint instead. For Dashboards the flag controls widget hydration; Semantic Model reviews are unchanged.