mcp-data-platform-v1.58.1

This is a hotfix release that reverts a regression introduced in v1.58.0. If you were unable to upgrade to v1.58.0 because of invalid_scope errors on your gateway connections, upgrade to v1.58.1.

TL;DR

	v1.58.0 (broken for some IdPs)	v1.58.1 (this release)
oauth_scope handling for authorization_code connections	Platform unconditionally appended offline_access to the operator-supplied scope and used openid profile email offline_access as the default when scope was empty.	Platform uses oauth_scope verbatim. Operator input is the source of truth. No programmatic injection.
IdPs without offline_access in their assignable scope set	Connection failed with upstream returned invalid_scope: Invalid scopes: openid profile email offline_access	Connection works (whatever scope the operator configured is sent as-is).
Refresh-token longevity guidance	Solved automatically (but broke connections that couldn't grant offline_access).	Solved by operator configuration — see the README and docs/auth/oauth-gateway.md "Refresh token longevity" sections for IdP-specific guidance.

No operator action is required for upgrade beyond bumping the image tag. Connections that worked before v1.58.0 keep working. Connections that broke under v1.58.0 start working again.

---

Why the revert

The premise behind v1.58.0's auto-augmentation was real: authorization_code refresh tokens issued without offline_access (or the IdP's equivalent) are tied to the interactive SSO session and die when that session goes idle, forcing a manual Reconnect after every platform restart longer than the IdP's session-idle window.

The fix in v1.58.0 was wrong, however, because it assumed every IdP would happily issue offline_access. That's not true:

• Keycloak requires offline_access to be assigned to the gateway client as a client scope (Default or Optional). If it isn't, the token endpoint returns invalid_scope for every request.
• IdPs that name the offline-token scope differently (e.g., Salesforce uses refresh_token) reject offline_access as unknown.
• Custom OAuth servers may not support offline-token issuance at all.

Auto-augmentation took control away from the operator and broke deployments where the IdP wasn't pre-configured to grant the injected scope — observed in production with the verbatim error upstream returned invalid_scope: Invalid scopes: openid profile email offline_access.

The correct contract is the one this release restores: the operator-supplied oauth_scope is the source of truth. If you want long-lived refresh tokens, configure the IdP to grant the offline-token scope and explicitly request that scope in your connection.

---

What this release changes vs v1.58.0

Reverted

• OAuthConfig.OriginalScope and OAuthConfig.ScopeAugmented fields — removed. Operator input is no longer "pre-augmentation" because there is no augmentation.
• OfflineAccessScope exported constant, ensureOfflineAccessScope, defaultAuthCodeScope, scopeContains, and statusScopeForHint helpers — removed.
• The legacy un-customized "Reconnect to pick up the augmented scope" status hint — removed (no augmentation means no upgrade path that requires it).

Simplified

• formatStatusError now emits a generic IdP-agnostic refresh-rejected hint when the upstream rejects a refresh grant. The hint points operators at their IdP's offline-token configuration without prescribing a specific scope name (Keycloak/Auth0/Okta use offline_access; Salesforce uses refresh_token; custom servers vary).
• Tests updated to assert the verbatim-scope contract:
  • TestParseConfig_ScopeVerbatim — empty scope stays empty, operator scope passes through unchanged, client_credentials is unaffected.
  • TestFormatStatusError and TestStatus_RefreshRevoked_HintReaches — cover the simplified generic-hint behavior.

Documentation rewritten

The "Refresh token longevity" sections of README.md, docs/auth/oauth-gateway.md, docs/llms.txt, and docs/llms-full.txt are rewritten as operator-controlled recommendations:

• Explain the SSO-session-idle problem.
• List IdP-specific scope names (Keycloak/Auth0/Okta: offline_access; Salesforce: refresh_token).
• Document the Keycloak prerequisite: the offline_access client scope must be assignable on the gateway client. Hitting invalid_scope means the IdP isn't configured to grant it.

Retained from v1.58.0

The unrelated tools/list_changed live propagation fix (Bug B from v1.58.0) and the repo-wide lint cleanup are not affected by this hotfix. Both remain in v1.58.1.

---

Upgrade matrix

Your situation	Upgrade behavior
Running v1.57.x or earlier	Direct upgrade to v1.58.1 is safe. Skip v1.58.0.
Running v1.58.0 with no connection errors	Upgrade to v1.58.1. No behavior change for you (your IdP must have already been granting offline_access).
Running v1.58.0 and seeing invalid_scope errors	Upgrade to v1.58.1 immediately — the error goes away once the platform stops injecting the scope. If you want long-lived refresh tokens, set oauth_scope explicitly and configure the IdP to grant it.
Want long-lived refresh tokens after upgrade	In the connection config, set oauth_scope to include your IdP's offline-token scope name (e.g., openid profile email offline_access for Keycloak). Verify the IdP grants it. Click Reconnect to issue a refresh token under the new scope.

---

Changelog

Bug Fixes

• fix(gateway): revert auto-augmentation of oauth_scope (regression in v1.58.0) (#361) — restores verbatim-scope semantics; oauth_scope is sent to the IdP exactly as configured, with no programmatic injection of offline_access.

---

Installation

Homebrew (macOS)

brew install txn2/tap/mcp-data-platform

Claude Code CLI

claude mcp add mcp-data-platform -- mcp-data-platform

Docker

docker pull ghcr.io/txn2/mcp-data-platform:v1.58.1

Verification

All release artifacts are signed with Cosign. Verify with:

cosign verify-blob --bundle mcp-data-platform_1.58.1_linux_amd64.tar.gz.sigstore.json \
  mcp-data-platform_1.58.1_linux_amd64.tar.gz