Create MCP Servers with MCPHero

MCPHero lets agents build their own tools. Instead of burning tokens on API schemas, SQL queries, and output parsing every run, the agent creates a persistent MCP server once and calls it forever. A 50,000-token integration becomes a 50-token tool call.

This skill covers the mcpheroctl CLI workflow for building servers end-to-end.

Production API base URL: https://api.mcphero.app/api

Prerequisites

Before using this skill, the user must have mcpheroctl installed and authenticated.

Install mcpheroctl

# via Homebrew (macOS/Linux)
brew install arterialist/mcpheroctl/mcpheroctl

# via uv (cross-platform)
uv tool install mcpheroctl

Authenticate

1. Log in to the MCPHero Dashboard.
2. Go to Settings → Organization → Developers.
3. Click Create API key and copy the token.
4. Run:

mcpheroctl auth login --token <YOUR_ORG_TOKEN>

Verify

mcpheroctl auth status

The Wizard Pipeline

The CLI follows this linear flow. After any async step, poll wizard state and check processing_status == "idle" before proceeding.

1. create-session          → Returns server_id (save it, needed everywhere)
2. conversation (loop)     → Gather requirements; stop when is_ready: true
3. start                   → Transition to tool suggestion (async → poll)
4. list-tools              → Review AI-suggested tools
5. refine-tools (optional) → Iterate on tools until satisfied (async → poll)
6. submit-tools            → Confirm selection (deletes unselected tools)
7. (auto env var suggest)  → Triggered automatically after submit-tools (async → poll)
8. list-env-vars           → Review suggested env vars
9. refine-env-vars (opt.)  → Iterate on env vars (async → poll)
10. submit-env-vars        → Provide actual values (call even if list is empty — backend needs it to transition)
11. set-auth               → Generate bearer token for the server
12. generate-code          → Trigger code generation (async → poll)
13. deploy                 → Deploy to MCPHero runtime → returns server_url + bearer_token

Always call submit-env-vars, even when list-env-vars returns []. The backend requires this step to transition to the next state. With no env vars, just call it with no --var flags.

State Machine

The setup_status field in wizard state tells you where you are: