Skip to main content

Authentication & Configuration

The SDK and CLI authenticate with an MCP token and an API base URL. You can supply them interactively, via environment variables, or per-command.

Interactive setup​

substratecloud config init

This prompts for your MCP token, API base URL, an optional default region, and an optional default SSH key (chosen from the keys registered to your org). It writes a TOML profile to:

~/.config/substratecloud/config.toml

(or $XDG_CONFIG_HOME/substratecloud/config.toml).

note

When prompted for the API base URL, enter https://io.substrate.ai/functions/v1/ondemand-mcp-manager. Some alpha builds still show an older …supabase.co… example next to the prompt — ignore it and use the io.substrate.ai URL.

Secure by default

The config file is created with 0600 permissions and its directory with 0700, so the token is never world-readable on a shared machine. config show always redacts the token.

Profiles​

Profiles let you switch between orgs or environments:

substratecloud config init --profile staging   # create/replace a profile
substratecloud config use staging              # set the active profile
substratecloud config ls                       # list profiles
substratecloud config show staging             # show settings (token redacted)

A profile stores: token, base_url, default_region, default_ssh_key_id, and default_tags.

Environment variables​

You can skip the config file entirely:

export SUBSTRATECLOUD_MCP_TOKEN=mcp_...
export SUBSTRATECLOUD_API_BASE_URL=https://io.substrate.ai/functions/v1/ondemand-mcp-manager
export SUBSTRATECLOUD_PROFILE=staging   # selects which file profile to use

Resolution order​

For each setting, the first source that provides a value wins:

  1. Per-command flags — --profile (CLI). The Python client additionally accepts token=, base_url=, and profile= as constructor arguments (the CLI has no --token / --base-url flags — use env vars or a profile).
  2. Environment variables — SUBSTRATECLOUD_MCP_TOKEN, SUBSTRATECLOUD_API_BASE_URL, SUBSTRATECLOUD_PROFILE
  3. The selected profile in the config file
  4. Built-in defaults

Verify your credentials​

substratecloud check

check validates the configured token and base URL against the API and reports how many instances it can see. If it fails with an auth error, re-run config init or double-check the token (it should start with mcp_).

In Python​

The same resolution order applies when you construct a client:

from substratecloud import SubstrateCloud

client = SubstrateCloud()                                  # env or active profile
client = SubstrateCloud(token="mcp_...", base_url="https://...")  # explicit
client = SubstrateCloud(profile="staging")                 # named file profile