Use the MCP Stack CLI

The mcpstack CLI is the automation surface for MCP Stack. Use it for CI, repeatable operations, debugging, smoke tests, and day-to-day platform work that should not depend on clicking through the dashboard.

npm install -g @mcpstack/cli
mcpstack auth login
mcpstack auth status

Global flags#

Most commands support common flags:

mcpstack servers list --org org_123 --json
mcpstack servers get srv_support --json
mcpstack gateways logs gw_123 --output table

Common flags:

Environment variables#

Use environment variables in CI:

export MCPSTACK_API_URL=https://api.mcpstack.com
export MCPSTACK_ORG_ID=org_123
export MCPSTACK_API_KEY=mcpstack_sk_xxxx
export MCPSTACK_OUTPUT=json

Supported variables include:

• MCPSTACK_API_URL
• MCPSTACK_ORG_ID
• MCPSTACK_ACCESS_TOKEN
• MCPSTACK_API_KEY
• MCPSTACK_DISABLE_KEYCHAIN
• MCPSTACK_OUTPUT
• NO_COLOR

Server workflow#

mcpstack servers list
mcpstack servers get support-api
mcpstack tools list support-api
mcpstack smoke tools-list support-api

Use this workflow to verify a server before attaching it to an agent or external MCP client.

Hosted custom domain workflow#

Use custom domain commands to validate ownership, prepare routing records, finalize, inspect, and remove a customer-owned MCP hostname from a hosted server.

See Set up a custom MCP domain for the full staged workflow, DNS records, status meanings, and troubleshooting.

mcpstack servers custom-domain validate support-api \
  --hostname mcp.example.com \
  --environment prod \
  --json
 
mcpstack servers custom-domain confirm-ownership support-api --environment prod --json
mcpstack servers custom-domain get support-api --environment prod --json
mcpstack servers custom-domain finalize support-api --environment prod --json
mcpstack smoke tools-list support-api --environment prod --json
mcpstack servers custom-domain delete support-api --environment prod --yes

The validate response includes the ownership TXT record to create at your DNS provider. After it resolves, run confirm-ownership; MCP Stack then prepares the routing CNAME and TLS-validation TXT records. Add those records, wait for propagation, then run finalize. The canonical hosted MCP URL remains available while the custom domain is pending.

Gateway workflow#

mcpstack gateways list
mcpstack gateways get gw_support
mcpstack gateways logs gw_support

Gateway commands are useful when OAuth succeeds in the browser but tool calls still fail. Look for missing scopes, invalid audience, expired grants, or runtime errors.

Agent workflow#

mcpstack agents list
mcpstack agents get ag_support
mcpstack agents usage ag_support --json

Use agent commands to audit configuration and embed usage without opening the dashboard.

Manage embedded user budgets from service-account automation or an operator terminal:

mcpstack agents budget defaults ag_support --monthly-usd 10000 --default-user-usd 5 --json
mcpstack agents budget set ag_support --user customer_abc --monthly-usd 5 --json
mcpstack agents budget get ag_support --user customer_abc --json
mcpstack agents budget delete ag_support --user customer_abc --yes

Use the API for production signup and billing hooks. Use the CLI for imports, spot checks, and operational tasks. See Embedded agent budgets for identity mapping, service-account auth, and budget-exhausted runtime behavior.

Account and billing workflow#

mcpstack org list --json
mcpstack members list --json
mcpstack api-keys list --json

Organization billing and AI credits are managed in the dashboard. Use the Billing and AI credits guide for checkout and ledger workflows.

Command index#

For the compact canonical map, see CLI Reference.

CI smoke check#

#!/usr/bin/env bash
set -euo pipefail
 
mcpstack auth service-account login --key "$MCPSTACK_API_KEY"
mcpstack servers get "$MCPSTACK_SERVER_ID" --json
mcpstack smoke tools-list "$MCPSTACK_SERVER_ID" --json

Quick answer#

For interactive use, run auth login. For CI, use service-account auth and JSON output. When debugging, add --verbose and --debug-http, and reduce to the smallest command that reproduces the issue.