Skip to content

MCP Lightcast 0.4.0

Version 0.4.0 adds pluggable credential providers, optional HTTP credential headers, and account isolation for shared deployments. Existing local environment/stdio configurations continue to work. Python 3.14 or newer is required, and all 37 MCP tools retain their signatures.

Credential providers

  • CredentialProvider is an asynchronous interface that returns immutable LightcastCredentials for the current caller.
  • Environment credentials remain the default: LIGHTCAST_CLIENT_ID and LIGHTCAST_CLIENT_SECRET continue to work with .env, --env-file, and local stdio clients.
  • create_server(credential_provider=..., auth=...) lets deployments combine a credential provider with FastMCP authentication. A custom provider can map a verified caller to an authorized credential in a secret store.
  • Credentials resolve lazily once per request that uses Lightcast, including every API call within a composed workflow. The next request resolves again to pick up authorization changes or secret rotation. No process environment variables are changed to switch callers.

The credential-provider guide includes local configuration, an HTTP client example, a secret-store adapter, and deployment requirements. A production identity provider and secret store remain deployment integrations; this release supplies the extension points.

Optional HTTP credentials

Set LIGHTCAST_CREDENTIAL_MODE=headers to accept X-Lightcast-Client-Id and X-Lightcast-Client-Secret on HTTP requests. No server-side Lightcast credential pair is required in this mode.

  • Missing, blank, duplicate, oversized, or malformed headers fail. Incorrect credentials fail at Lightcast. Header mode never falls back to environment credentials, even if the server has a valid account configured.
  • Header mode requires the HTTP transport and rejects local --validate-config. Environment mode ignores incoming Lightcast credential headers.
  • Discovery, tool listings, lightcast://server/info, and HTTP /health do not require Lightcast credentials. The lightcast://server/health resource verifies the current caller's default-scope OAuth credentials.
  • Incoming MCP bearer tokens are not forwarded to Lightcast. API requests use separately obtained Lightcast tokens.

Header credentials do not replace inbound MCP authentication. Shared deployments still need an authenticated gateway or FastMCP auth provider, HTTPS, protected backend access, and credential redaction in logs and traces. See the reverse proxy guide.

Account isolation

Tokens and refresh locks are isolated by OAuth endpoint, client ID, client secret, and scope. Cache keys use process-keyed HMACs rather than raw credentials. A changed or incorrect secret cannot reuse another credential pair's cached token; a 401 affects only the relevant token and cannot invalidate a newer refresh.

Metadata caches also include credential identity and API root. Rate spacing is separate for each account/service and stays shared across rotations of the same account's secret. Request contexts reset after success, errors, and cancellation. Token and metadata caches are bounded, and idle rate state is reclaimed.

Limits are local to each process/event loop; deployments with multiple replicas need aggregate rate enforcement. Secret rotation creates a new cache identity but does not revoke already-issued upstream tokens or interrupt calls already in progress.

Compatibility and validation

No MCP tool arguments changed. Existing environment-mode installations can upgrade without changing their configuration. Python integrations calling the low-level LightcastAuth.invalidate method must now supply the affected credentials= explicitly.

  • 130 offline tests passed, with 21 opt-in tests skipped in the ordinary suite.
  • 13 nginx/TLS integration tests passed, covering environment and header modes with distinct synthetic account results, no environment fallback, credential-free liveness, and log redaction.
  • Both 2026-07-28 and legacy 2025-11-25 MCP clients are covered, including credential changes between requests on the same client connection.
  • Tests cover concurrent workflows and resources, credential rotation, rejected headers, isolated 401/403/429 handling, verified caller identity, cache bounds, and cancellation cleanup.
  • Python 3.14 and 3.15 CI, lint, formatting, type checks, strict documentation builds, package checks, and workflow checks passed.

All isolation and proxy tests use synthetic OAuth/API responses and consume no live Lightcast quota. They do not certify a deployment's external identity provider, secret store, or live API entitlements. See the testing guide.

Install

For a local MCP client with credentials in .env:

uvx --python 3.14 mcp-lightcast@0.4.0 --env-file .env

For an HTTP deployment supplying credentials per request:

LIGHTCAST_CREDENTIAL_MODE=headers uvx --python 3.14 mcp-lightcast@0.4.0 \
  --transport streamable-http --host 127.0.0.1 --port 3000

Or run the published Linux amd64 container in the default environment mode:

docker run --rm -i --platform linux/amd64 --env-file .env \
  ghcr.io/lawwu/mcp-lightcast:0.4.0

Docker also publishes the moving 0.4 and latest tags. The 0.3 tag remains on the previous release series.