MCPCTL CLI Reference

Global Options

--help, -h       # Show help information
--version, -v    # Show version information
--debug          # Enable debug mode
--quiet          # Suppress output

Commands

Server Management

Start Server

mcpctl server start -f <spec.json> [--profile <name>]

Stop Server

mcpctl server stop <server-name>

Restart Server

mcpctl server restart <server-name>

Server Status

mcpctl server status <server-name>

List Servers

mcpctl server list

Remove Server

mcpctl server remove <server-name>

Secret Management

Add Secret

mcpctl secret add <name> --value <value> [--source <vault|keychain|env>]

List Secrets

mcpctl secret list [--source <vault|keychain|env>]

Get Secret

mcpctl secret get <name> [--source <vault|keychain|env>]

Remove Secret

mcpctl secret remove <name> [--source <vault|keychain|env>]

Profile Management

Create Profile

mcpctl profile create <name> [--description <text>] [--copy-from <name>]

Delete Profile

mcpctl profile delete <name>

List Profiles

mcpctl profile list

Use Profile

mcpctl profile use <name>

Read Profile

mcpctl profile read <name>

Profile Env Management

  • Set:
mcpctl profile env set <key> <value> [--profile <name>]
  • Get:
mcpctl profile env get <key> [--profile <name>]
  • List:
mcpctl profile env list [--profile <name>]
  • Delete:
mcpctl profile env delete <key> [--profile <name>]

Control Plane Management

Start Control Plane

mcpctl control-plane start

Stop Control Plane

mcpctl control-plane stop

Restart Control Plane

mcpctl control-plane restart

Control Plane Status

mcpctl control-plane status

Control Plane Logs

mcpctl control-plane logs

Log Management

Server Logs

mcpctl log server <server-name> [--limit <number>]

Control Plane Logs

mcpctl log control-plane [--limit <number>]

Example: serverRunSpec JSON

Below is a sample serverRunSpec file for running a Slack server. This file defines all required and optional fields. You can use this as a template for your own server specifications.

{
  "name": "server-slack",
  "resourceType": "remote",
  "transport": {
    "type": "stdio"
  },
  "command": "npx -y @modelcontextprotocol/server-slack",
  "env": {
    "SLACK_TEAM_ID": "T00000000"
  },
  "secrets": {
    "SLACK_BOT_TOKEN": {
      "source": "keychain",
      "key": "slack-bot-token"
    }
  }
}

Field Descriptions:

  • name (string, required): Unique name for the server instance.
  • resourceType (string, required): Resource type, e.g. local or remote.
  • transport (object or string, required): Transport type for server communication. Example: { "type": "stdio" } or a string like "sse".
  • command (string or array, required): Command to launch the server. Can be a string or an array of command/args.
  • env (object, optional): Environment variables to inject into the server process.
  • secrets (object, optional): Secrets to inject. Each key can specify a value or a reference (with source and key).

Tip: For more examples, see the examples/runspec/ directory in this repository.