reload_credentials
Re-sources the dotenv-style file nominated by the --env.file flag into the server's process environment, then reports credential resolution status for each provider. This solves the fixed-at-spawn environment problem: credentials written or rotated on disk mid-session reach the running server without a restart.
The env file overlays the process environment rather than replacing it: credential resolution always reads the live process environment at request time, so variables already present at spawn (from the shell or the client's env block) keep working with or without --env.file. On reload, only keys present in the file with non-empty values are written and nothing is ever unset, so a failed or partial reload preserves previously working credentials.
Secret values are never returned, logged, or audited - the tool reports variable names and statuses only. Without --env.file configured the tool degrades to a pure status probe. When a query fails on credential resolution, the MCP error carries a hint directing the agent to call reload_credentials and retry, so agentic clients self-heal.
Available in StackQL releases after v0.10.542.
See also:
[ MCP overview ] [ Credential (re)sourcing ] [ server_info ] [ Claude Desktop ]
Inputs​
| Argument | Required | Description |
|---|---|---|
provider | No | Scopes the status report to one provider. When omitted, every provider is reported. |
Output​
| Renderer | Shape |
|---|---|
| Table | Env-file sourcing result plus one row per provider with credential resolution status |
The structured payload contains:
| Field | Description |
|---|---|
env_file | The configured --env.file path (empty when none is configured). |
env_file_sourced | true when the file was found and sourced on this call. |
sourced_vars | Names of the environment variables set from the file - names only, never values. |
providers | One row per provider (see below). |
Each providers row has:
| Column | Description |
|---|---|
provider | Provider name. |
auth_type | Authentication type configured for the provider. |
sourced_from | Where the credential resolved from, e.g. env:OKTA_SECRET_KEY, file:/path/key.json, inline, or none. |
status | ok, unresolved, or not_checked. |
detail | Error text when unresolved. |
Auth types that authenticate outside the credential-bytes path (interactive gcloud, azure CLI, oauth2 client credentials, assume-role chains, OCI signing, null) report not_checked.
Gating​
Allowed in every server mode, including read_only - the tool mutates nothing beyond the server's own process environment.
Not supported in reverse_proxy backend mode: queries execute in the remote stackql server process, so the tool returns an error directing the user to reload credentials on the backing server.
Example​
Try this prompt with any MCP client with the StackQL MCP server registered (started with --env.file):
My okta query failed with a credential error - I've just written the key
to the credentials file. Reload credentials and retry the query.