mcpheroctl

CLI tool for interacting with the MCPHero platform — create, manage, and deploy MCP servers via the wizard pipeline.

Designed for both human use and AI agent workflows, following agent-first CLI principles:

Structured JSON output to stdout; human-readable messages to stderr
Documented, meaningful exit codes
--json flag on every command for scripting / pipeline integration
Noun-verb command grammar (mcpheroctl <noun> <verb>)

Requirements

Python ≥ 3.12
uv or Homebrew

Installation

via Homebrew (macOS/Linux)

brew install arterialist/mcpheroctl/mcpheroctl

via uv tool (Cross-platform)

uv tool install mcpheroctl

Authentication

mcpheroctl uses an organization API token stored at ~/.config/mcpheroctl/config.json.

mcpheroctl auth login --token <YOUR_ORG_TOKEN>

Obtain your token from the MCPHero Dashboard.

Getting a Token

Log in to the MCPHero Dashboard.
Go to Settings → Organization → Developers.
Click Create API key.
Copy the generated token for use with mcpheroctl auth login.

Most commands also accept an optional --customer-id / CUSTOMER_ID argument; when using an org API key, customer context is inferred automatically — passing a customer ID is only required when working with an admin key across multiple customers.

Auth commands

Command	Description
`mcpheroctl auth login --token TOKEN`	Save API token (optionally `--base-url URL`)
`mcpheroctl auth status`	Show current auth state and token preview
`mcpheroctl auth logout`	Remove stored credentials

Configuration

Config is stored at ~/.config/mcpheroctl/config.json:

{
  "api_token": "your-token-here",
  "base_url": "https://api.mcphero.app/api"
}

Override the API endpoint at login time:

mcpheroctl auth login --token TOKEN --base-url https://staging.mcphero.app/api

Server Commands

Manage deployed MCP servers.

mcpheroctl server <command>

Command	Description
`list [CUSTOMER_ID]`	List all MCP servers (customer optional with org key)
`get SERVER_ID`	Get full server details
`update SERVER_ID`	Update server `--name` and/or `--description`
`delete SERVER_ID --yes`	Delete a server and all resources
`api-key SERVER_ID`	Retrieve the server's API key

Examples

# List servers for your org
mcpheroctl server list

# List for a specific customer (admin key)
mcpheroctl server list 550e8400-e29b-41d4-a716-446655440000

# Get details as JSON (for scripting)
mcpheroctl server get SERVER_ID --json

# Update
mcpheroctl server update SERVER_ID --name "My Weather API" --description "Provides weather data"

# Delete (non-interactive)
mcpheroctl server delete SERVER_ID --yes

# Get API key
mcpheroctl server api-key SERVER_ID --json

Wizard Commands

The wizard pipeline guides you through creating a new MCP server end-to-end. Each step corresponds to a backend operation — background steps should be polled with wizard state.

mcpheroctl wizard <command>

Pipeline Overview

  create-session
    → conversation (iterate until is_ready)
    → start
    → list-tools / refine-tools (iterate)
    → submit-tools
    → [suggest-env-vars]
    → list-env-vars / refine-env-vars (iterate)
    → submit-env-vars
    → set-auth
    → generate-code / regenerate-tool-code (iterate)
    → deploy

Poll wizard state SERVER_ID between async steps to check when the server is ready for the next command.

Step 0a: Create Session

# Create a new session (returns server_id)
mcpheroctl wizard create-session

# With explicit customer (admin key)
mcpheroctl wizard create-session --customer-id CUSTOMER_UUID

# JSON output (returns { "server_id": "..." })
mcpheroctl wizard create-session --json

Creates a new wizard session and returns a server_id. Use this before conversation to begin requirements gathering.

Step 0b: Conversation

# Chat with the AI to describe your server
mcpheroctl wizard conversation SERVER_ID -m "I want a GitHub integration server"

# Continue refining requirements
mcpheroctl wizard conversation SERVER_ID -m "Add webhook support and remove the delete endpoint"

# JSON output (includes is_ready flag)
mcpheroctl wizard conversation SERVER_ID --message "looks good" --json

Iteratively describe your MCP server to the AI. The response includes an is_ready field — when true, the AI has gathered enough information and you can proceed with wizard start if the requirements are complete.

Step 1: Start

# Transition to tool suggestion (after conversation is_ready)
mcpheroctl wizard start SERVER_ID

# Optionally override the description with a spec file
mcpheroctl wizard start SERVER_ID --spec spec.md

# With additional technical detail files
mcpheroctl wizard start SERVER_ID -d openapi.md -d schema.md

# JSON output
mcpheroctl wizard start SERVER_ID --json

Transitions the server from requirements gathering to tool suggestion. The server must have completed the conversation step (is_ready=true). Technical detail files (-d) can contain API schemas, endpoint docs, etc.

Step 2: Tools

# View generated tool suggestions
mcpheroctl wizard list-tools SERVER_ID

# Refine all tools with feedback
mcpheroctl wizard refine-tools SERVER_ID --feedback "Add a search tool and remove the delete tool"

# Refine specific tools only
mcpheroctl wizard refine-tools SERVER_ID -f "Simplify parameters" --tool-id UUID1 --tool-id UUID2

# Submit selected tools to finalize (moves to env vars step)
mcpheroctl wizard submit-tools SERVER_ID --tool-id UUID1 --tool-id UUID2

Step 3: Environment Variables

# Trigger LLM suggestion of required env vars
mcpheroctl wizard suggest-env-vars SERVER_ID

# View suggestions
mcpheroctl wizard list-env-vars SERVER_ID

# Refine with feedback
mcpheroctl wizard refine-env-vars SERVER_ID --feedback "Combine DB vars into DATABASE_URL"

# Submit values for each variable (UUID=VALUE format)
mcpheroctl wizard submit-env-vars SERVER_ID \
  --var "API_KEY_UUID=sk-abc123" \
  --var "BASE_URL_UUID=https://api.example.com"

Step 4: Authentication

# Generate bearer token for the server
mcpheroctl wizard set-auth SERVER_ID --json

Step 5: Code Generation

# Generate code for all tools (async — poll wizard state)
mcpheroctl wizard generate-code SERVER_ID

# Regenerate a single tool (synchronous — returns immediately)
mcpheroctl wizard regenerate-tool-code SERVER_ID TOOL_ID --json

Step 6: Deploy

mcpheroctl wizard deploy SERVER_ID

# JSON response contains the live server endpoint URL
mcpheroctl wizard deploy SERVER_ID --json

State Polling

Poll state to wait for background operations to complete:

mcpheroctl wizard state SERVER_ID --json

Useful states: pending, generating_tools, tools_ready, generating_code, code_ready, deploying, deployed, error.

Scripting & Agent Usage

All commands support --json for structured output. Combine with jq or any JSON tooling:

# Create a session and get the server ID
SERVER_ID=$(mcpheroctl wizard create-session --json | jq -r '.server_id')

# Chat until the AI is ready and the requirements are complete
while true; do
  RESP=$(mcpheroctl wizard conversation "$SERVER_ID" -m "I want a weather API server" --json)
  echo "$RESP" | jq -r '.content'
  IS_READY=$(echo "$RESP" | jq -r '.is_ready')
  [ "$IS_READY" = "true" ] && break
done

# Transition to tool suggestion
mcpheroctl wizard start "$SERVER_ID" --json

# List tool IDs
TOOL_IDS=$(mcpheroctl wizard list-tools "$SERVER_ID" --json | jq -r '.[].id')

# Submit all suggested tools
mcpheroctl wizard submit-tools "$SERVER_ID" \
  $(echo "$TOOL_IDS" | xargs -I{} echo "--tool-id {}")

# Poll until state is ready
while true; do
  STATE=$(mcpheroctl wizard state "$SERVER_ID" --json | jq -r '.status')
  echo "State: $STATE"
  [ "$STATE" = "tools_ready" ] && break
  sleep 3
done

Exit Codes

Code	Meaning
`0`	Success
`1`	General failure
`2`	Usage error (bad arguments)
`3`	Resource not found
`4`	Permission denied / not authenticated
`5`	Conflict (resource already exists)
`6`	Not implemented

Error Output

When --json is passed, errors are emitted as structured JSON to stdout:

{
  "error": "not_found",
  "message": "Server not found",
  "status_code": 404
}

Without --json, errors are printed to stderr with a ✖ prefix.

Project Structure

src/mcpheroctl/
├── cli.py               # Main entrypoint — registers auth/server/wizard
├── commands/
│   ├── auth.py          # login, status, logout
│   ├── server.py        # list, get, update, delete, api-key
│   └── wizard.py        # Full wizard pipeline + conversation stub
└── core/
    ├── config.py        # Config storage (~/.config/mcpheroctl/config.json)
    ├── output.py        # JSON/stderr output helpers, exit codes
    └── client.py        # httpx HTTP client with tenacity retries

Development

# Install in editable mode
uv sync

# Run CLI directly
uv run mcpheroctl --help

# Format / lint
uv run ruff format .
uv run ruff check .

# Type check
uv run basedpyright

Dependencies

Package	Purpose
`typer`	CLI framework
`httpx`	Async-capable HTTP client
`pydantic`	Config validation
`tenacity`	Retry logic on transient/5xx errors
`rich`	Colored stderr output

License

Apache 2.0 — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
scripts		scripts
spec		spec
src/mcpheroctl		src/mcpheroctl
.gitignore		.gitignore
.python-version		.python-version
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

mcpheroctl

Requirements

Installation

via Homebrew (macOS/Linux)

via uv tool (Cross-platform)

Authentication

Getting a Token

Auth commands

Configuration

Server Commands

Examples

Wizard Commands

Pipeline Overview

Step 0a: Create Session

Step 0b: Conversation

Step 1: Start

Step 2: Tools

Step 3: Environment Variables

Step 4: Authentication

Step 5: Code Generation

Step 6: Deploy

State Polling

Scripting & Agent Usage

Exit Codes

Error Output

Project Structure

Development

Dependencies

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages