CLI Reference
The complete mcpstack CLI, grouped by resource — every command, argument, and flag, with copyable signatures and runnable examples.
The mcpstack CLI manages your organization, MCP servers, gateways, and agents from a terminal. It wraps the same surface as the API, adding auth, output formatting, and confirmation prompts.
Each group below lists every command in that area. Scan the command and description; copy the exact signature; expand a row for a runnable example. Arguments are shown in <angle brackets>; optional ones in [brackets].
npm install -g @mcpstack/cli
mcpstack auth loginThese apply to every command.
| Flag | Description |
|---|---|
--api-url <url> | API base URL. Defaults to https://api.mcpstack.com. |
--org <id> | Target a specific organization (defaults to your primary org, like the dashboard). |
--output <fmt> | Output format: table, json, or yaml. |
--json | Shorthand for --output json. |
--yes | Skip confirmation prompts. |
--wait | Block until a long-running operation finishes (where supported). |
--timeout <seconds> | Cap how long --wait blocks. |
--verbose | Print extra detail. |
--debug-http | Print the HTTP method and URL for each request. |
Set these once in CI so commands run non-interactively.
| Variable | Description |
|---|---|
MCPSTACK_API_URL | API base URL. Same as --api-url. |
MCPSTACK_ORG_ID | Default organization id. Same as --org. |
MCPSTACK_API_KEY | Service-account key (mcpstack_sk_…), sent as a bearer token. |
MCPSTACK_ACCESS_TOKEN | OAuth access token, overrides stored login. |
MCPSTACK_OUTPUT | Default output format: table, json, or yaml. |
MCPSTACK_DISABLE_KEYCHAIN | Set to 1/true to store secrets in a file instead of the OS keychain. |
NO_COLOR | Disable colored output. |
Commands take resource IDs, not names or slugs:
mcp_…, from servers list, servers get, or servers create output.tool_…, from tools list.ag_…, from agents list.gateways get, or pass --url to target a public MCP URL directly.Examples on this page use IDs like mcp_5Qp8wYz and tool_2Ab7nLk.
Sign in as a human with the OAuth device flow, or store a service-account key for automation.
mcpstack auth login [--no-browser]Sign in via the OAuth device flow. --no-browser prints the URL instead of opening it.mcpstack auth logoutDelete the active local login.mcpstack auth statusShow the active login and target API.mcpstack auth whoamiShow the authenticated user or service account.mcpstack auth service-account login --key <key>Store a service-account key for automation.Store a service-account key for automation.export MCPSTACK_API_URL="https://api.mcpstack.com"
export MCPSTACK_API_KEY="mcpstack_sk_..."
export MCPSTACK_OUTPUT="json"
mcpstack auth service-account login --key "$MCPSTACK_API_KEY"
mcpstack auth status
mcpstack servers listmcpstack auth service-account logoutDelete the stored service-account key.mcpstack org listList organizations you can access.mcpstack org get [id]Show an organization. Defaults to your active org.mcpstack org create --name <name> [--slug <slug>]Create an organization.mcpstack org update [id] --name <name>Rename an organization.mcpstack org delete [id] [--yes]Delete an organization.mcpstack members listList active members.mcpstack members invite <email> --role <role>Invite a teammate. Role: admin, developer, or viewer.mcpstack members update-role <principalId> --role <role>Change a member's role.mcpstack members remove <principalId> [--yes]Remove a member.mcpstack members invitations listList pending invitations.mcpstack members invitations resend <invitationId>Resend an invitation email.mcpstack members invitations revoke <invitationId> [--reason <text>]Revoke an invitation.mcpstack api-keys listList service-account keys.mcpstack api-keys rolesList roles available for keys.mcpstack api-keys create --name <name> [--role <role>] [--description <text>] [--expires-at <iso>]Create a key. Role defaults to viewer. The full key prints once.mcpstack api-keys revoke <keyId> [--yes]Revoke a key.The core resource. Create a server from an OpenAPI spec, then inspect, update, verify, and delete it.
mcpstack servers listList MCP servers.mcpstack servers get <serverId>Show a server, including its tools.mcpstack servers create [--name <name>] [--slug <slug>] [--openapi-file <file>] [--openapi-url <url>] [--runtime-type <type>] [--kind <kind>] [--description <text>]Create a server. With --openapi-file, name and slug are inferred from the spec when omitted.Create a server. With --openapi-file, name and slug are inferred from the spec when omitted.Use a local file for private or generated specs — no public URL required. Creating a hosted server publishes to MCP Stack Host automatically.
mcpstack servers create \
--name "Support API" --slug support-api \
--openapi-file ./openapi.yaml \
--runtime-type hosted --json
# Use the server id from the create output for follow-up commands
mcpstack servers checks mcp_5Qp8wYz --environment prod --jsonmcpstack servers update <serverId> [--name] [--description] [--status] [--server-url] [--runtime-type] [--openapi-file] [--openapi-url]Update server settings or replace the spec. Hosted changes publish automatically.mcpstack servers delete <serverId> [--environment <env>] [--yes]Delete a server.mcpstack servers config <serverId>Show the resolved server configuration.mcpstack servers analytics <serverId> [--days <n>]Show usage analytics.mcpstack servers logs <serverId> [--page <n>] [--page-size <n>]Page through request logs.mcpstack tools list <serverId>List a server's tools.mcpstack tools update <serverId> <toolId> [--enabled <bool>] [--display-name <name>] [--description <text>] [--instructions <text>]Edit one tool. toolId comes from tools list.Edit one tool. toolId comes from tools list.mcpstack tools update mcp_5Qp8wYz tool_2Ab7nLk \
--enabled true \
--display-name "Create ticket note" \
--instructions "Use only after the user confirms the ticket id and note body." \
--jsonmcpstack tools bulk-update <serverId> --file <file>Apply tool settings from a JSON file.mcpstack servers discover-tools <serverId>Re-import tools from the current spec.mcpstack servers endpoints get <serverId>Show the enabled endpoint set.mcpstack servers auth-config get <serverId>Show the server's auth configuration.mcpstack servers auth-discovery <serverId>Probe the upstream API's auth requirements.mcpstack servers checks <serverId> [--environment <env>]Run DNS, TLS, routing, runtime, and tools/list checks.mcpstack smoke tools-list <serverId> [--environment <env>]List tools over MCP against the live runtime.mcpstack smoke call <serverId> <toolName> [--args <json>] [--file <file>] [--environment <env>]Invoke a tool over MCP.Invoke a tool over MCP.mcpstack smoke call mcp_5Qp8wYz createTicketNote \
--args '{ "ticketId": "T-123", "body": "Investigating." }' \
--environment prod --jsonmcpstack logs stream <serverId> [--environment <env>] [--tail <n>]Print recent managed-edge logs.mcpstack operations list <serverId> [--environment <env>]List publish/deployment operations.mcpstack operations get <serverId> <operationId>Show one operation's status.Attach a customer-owned hostname to a hosted server. See custom domains for the staged DNS workflow.
mcpstack servers custom-domain validate <serverId> --hostname <host> [--environment <env>]Start validation; returns the ownership TXT record.mcpstack servers custom-domain confirm-ownership <serverId> [--environment <env>]Confirm ownership after the TXT record resolves.mcpstack servers custom-domain finalize <serverId> [--environment <env>]Finalize routing once CNAME/TXT records propagate.mcpstack servers custom-domain get <serverId> [--environment <env>]Show custom-domain status.mcpstack servers custom-domain delete <serverId> [--environment <env>] [--yes]Remove the custom domain.mcpstack servers gateway get <serverId>Show the server's gateway attachment.mcpstack servers gateway attach <serverId> --gateway <gatewayId> [--public-id <id>]Put a gateway in front of the server.mcpstack servers gateway detach <serverId> [--yes]Remove the gateway.mcpstack gateways listList gateways.mcpstack gateways get <gatewayId>Show a gateway.mcpstack gateways create --name <name> --provider <provider> --auth-server-url <url> --client-id <id> --resource <resource> --scopes <list> [--description <text>]Create a gateway.mcpstack gateways update <gatewayId> --file <file>Update a gateway from a JSON file.mcpstack gateways delete <gatewayId> [--yes]Delete a gateway.mcpstack gateways servers <gatewayId>List servers attached to a gateway.mcpstack gateways grants <gatewayId>List OAuth grants issued through a gateway.mcpstack gateways logs <gatewayId>Show gateway request logs.Diagnose a published MCP URL the way an external client sees it.
mcpstack gateway-public metadata <publicId>Show public OAuth/MCP discovery metadata.mcpstack gateway-public doctor [publicId] --client <client> [--url <url>] [--bearer <token>]Validate readiness for chatgpt-web or claude-web.Validate readiness for chatgpt-web or claude-web.Pass a Gateway publicId, or --url to inspect a raw public MCP URL. --bearer validates an authenticated tools/list.
mcpstack gateway-public doctor --url https://your-public-mcp.example.com/mcp --client chatgpt-webmcpstack gateway-public mcp-tools <publicId>List tools through the public endpoint.mcpstack gateway-public mcp-call <publicId> <toolName> [--args <json>] [--file <file>]Call a tool through the public endpoint.mcpstack agents listList agents.mcpstack agents get <agentId>Show an agent.mcpstack agents create --file <file>Create an agent from a JSON definition.mcpstack agents update <agentId> --file <file>Update an agent from a JSON definition.mcpstack agents delete <agentId> [--yes]Delete an agent.mcpstack agents model-optionsList available models.mcpstack agents usage <agentId>Show usage and cost for an agent.mcpstack agents embed-usageShow embedded-agent usage across the org.mcpstack agents chat <agentId> --message <text>Send a one-off message to an agent.Cap spend per agent and per embedded user.
mcpstack agents budget defaults <agentId> [--monthly-usd <amt>] [--default-user-usd <amt>] [--anonymous-usd <amt>] [--currency <cur>] [--disable]Set the agent's default budget policy. --disable removes it.Set the agent's default budget policy. --disable removes it.mcpstack agents budget defaults ag_123 \
--monthly-usd 10000 \
--default-user-usd 5 \
--jsonmcpstack agents budget set <agentId> --user <externalUserId> --monthly-usd <amt>Set one embedded user's monthly cap.mcpstack agents budget get <agentId> --user <externalUserId>Show one embedded user's budget.mcpstack agents budget delete <agentId> --user <externalUserId> [--yes]Remove an embedded user's override.mcpstack agents conversations list <agentId> [--cursor <c>] [--page-size <n>]List an agent's conversations.mcpstack agents conversations get <agentId> <conversationId>Show a conversation.mcpstack agents conversations messages <agentId> <conversationId>Show a conversation's messages.mcpstack dashboard statsShow dashboard summary stats.mcpstack dashboard analytics [--days <n>]Show aggregated analytics.mcpstack hosting usageShow hosted-runtime usage.mcpstack billing checkoutStart a hosting checkout session.mcpstack billing sync <sessionId>Reconcile a checkout session.mcpstack completion <shell>Print shell completion setup for zsh, bash, or fish.