hatchdx 0.2.0

The DX-first platform for agentic engineering

HatchDX

The DX-first platform for agentic engineering.

HatchDX (hdx) is a CLI tool and developer platform for scaffolding, testing, validating, and deploying MCP servers and the AI agents that use them. Go from zero to a working, testable MCP server or agent in under 2 minutes.

hdx init          →  hdx server create  →  hdx server test  →  hdx server dev
  workspace          scaffold server       test locally        dev + REPL

hdx agent create  →  hdx agent add-server  →  hdx agent chat  →  hdx agent eval
  scaffold agent     wire MCP servers        interactive chat    quality evals

hdx model pull    →  hdx model list
  HF → Ollama        manage local models

Why?

Building MCP servers and agents today means reading scattered docs, copying boilerplate, no standardized project structure, and no way to test tools locally without a full LLM client. HatchDX fixes all of that.

• Workspace management — hdx init scaffolds a workspace for servers and agents
• No boilerplate — hdx server create generates a complete project with best practices baked in
• Test without Claude — hdx server test runs your tools locally using YAML fixtures
• Fast feedback loop — hdx server dev gives you hot reload and an interactive REPL
• Protocol compliance — hdx server validate catches MCP violations before shipping
• Quality checks — hdx server eval tests tool effectiveness with assertions and golden files
• Sandboxed execution — hdx server sandbox runs tools in containers with security policies
• Agent scaffolding — hdx agent create generates agent configs wired to your servers
• Server wiring — hdx agent add-server connects MCP servers to agents with tool filtering
• Agent chat — hdx agent chat runs interactive sessions with tool-calling agents
• Agent evals — hdx agent eval tests agent behavior with assertions, cost tracking, and regression detection
• Local models — hdx model pull brings Hugging Face models to local Ollama for offline agent development
• Web dashboard — hdx dashboard gives you visual observability for servers and agents (eval history, config, analytics)

Install

# Option 1: Install as a global CLI tool (recommended)
uv tool install hatchdx

# Option 2: Run without installing
uvx hatchdx --help

# Option 3: pip
pip install hatchdx

Requires Python 3.13+ and uv (recommended) or pip.

Agent extras

Agent features (chat, eval) require a model provider SDK. Install the extra for your provider:

# Global CLI install with agent support (recommended)
uv tool install "hatchdx[anthropic]"       # Anthropic (Claude)
uv tool install "hatchdx[openai]"          # OpenAI (GPT, o-series)
uv tool install "hatchdx[huggingface]"     # Hugging Face (local models via Ollama)
uv tool install "hatchdx[agent]"           # All providers

# Or with uvx (no install, quotes required)
uvx --from "hatchdx[anthropic]" hdx agent chat my-agent

# Or with pip
pip install "hatchdx[anthropic]"

Note: Quotes around "hatchdx[...]" are required — zsh interprets bare [] as glob patterns.

Server-only users don't need extras — hdx stays lightweight by default.

Quick Start

# 1. Create a workspace
hdx init my-project
cd my-project

# 2. Create an MCP server
hdx server create --name weather-mcp --language python --transport stdio --template minimal

# 3. Install and test it
cd servers/weather-mcp
pip install -e .
hdx server test

# 4. Start the dev server with interactive REPL
hdx server dev

Or run hdx server create without flags for an interactive experience.

Agent Quick Start

# 1. Create an agent (from workspace root)
hdx agent create --name assistant --provider anthropic

# 2. Wire your MCP server to it
hdx agent add-server assistant --server servers/weather-mcp

# 3. Chat with the agent
hdx agent chat assistant

Commands

hdx init

Scaffold a new HatchDX workspace with servers/ and agents/ directories.

hdx init my-project

hdx server create

Create a new MCP server project.

# Interactive mode
hdx server create

# Non-interactive mode
hdx server create \
  --name weather-mcp \
  --language python \
  --transport stdio \
  --template api-wrapper \
  --description "Weather data via OpenWeather API"

hdx server list

List all MCP servers in the workspace.

hdx server list                    # Table output
hdx server list --json             # JSON output

hdx server test

Run YAML test fixtures against your MCP server. No LLM client needed.

hdx server test                    # Run all fixtures
hdx server test -v                 # Verbose
hdx server test -f "hello*"        # Filter by test name

hdx server dev

Start your server with hot reload and an interactive REPL.

hdx server dev                     # Hot reload + REPL
hdx server dev --no-repl           # Watch and restart only

hdx server validate

Run protocol compliance checks against your MCP server.

hdx server validate                        # Run all checks
hdx server validate --json-output          # Machine-readable JSON
hdx server validate --severity error       # Only errors

hdx server eval

Test tool effectiveness with assertions and golden files.

hdx server eval                            # Run all suites
hdx server eval --suite "core quality"     # Filter by suite
hdx server eval --compare                  # Regression detection

hdx server sandbox

Run MCP tools inside containers with configurable security policies.

hdx server sandbox run get_weather '{"city": "London"}'
hdx server sandbox shell
hdx server sandbox build

hdx agent create

Create a new AI agent project.

# Interactive mode
hdx agent create

# Non-interactive mode
hdx agent create --name assistant --template single-agent --provider anthropic

Templates: single-agent, researcher, custom Providers: anthropic, openai, local, huggingface

hdx agent add-server

Wire an MCP server to an agent with optional tool filtering.

# Local server (auto-detects name and command)
hdx agent add-server assistant --server ../servers/weather-mcp

# Remote HTTP server
hdx agent add-server assistant --url https://api.example.com/mcp

# Direct command
hdx agent add-server assistant --command "python -m weather_mcp.server"

# With tool filtering
hdx agent add-server assistant --server ../servers/weather-mcp \
  --include-tools get_weather --include-tools get_forecast

# With environment variables
hdx agent add-server assistant --server ../servers/weather-mcp \
  --env API_KEY=abc123 --env BASE_URL=https://api.example.com

hdx agent list

List all agents in the project.

hdx agent list                     # Table output
hdx agent list --json              # JSON output

hdx agent inspect

Show detailed information about an agent (config, servers, system prompt).

hdx agent inspect assistant        # Full details
hdx agent inspect assistant --tools  # Only show tools
hdx agent inspect assistant --json   # JSON output

hdx agent chat

Start an interactive chat session with an agent.

hdx agent chat assistant
hdx agent chat assistant -m "What's the weather?"  # Single message

hdx agent eval

Run eval suites against an agent.

hdx agent eval assistant --suite basic

hdx dashboard

Start the web dashboard for observability across servers and agents.

hdx dashboard                          # Start and open browser (default: http://localhost:4320)
hdx dashboard --port 8080              # Custom port
hdx dashboard --no-open                # Don't auto-open the browser

The dashboard includes:

• Overview — project summary, server health, recent eval runs
• Agents — browse all agents, view config (model, servers, tool filters, system prompt), eval history with pass rates/cost/tokens
• Eval Dashboard — unified eval runs for both servers and agents, with source filter toggle (All / Servers / Agents)
• Tool Playground — invoke tools from the browser via auto-generated forms
• Analytics — invocation counts, latency percentiles, error rates
• Compliance — protocol validation results with fix suggestions

hdx model pull

Pull a Hugging Face model to local Ollama for offline agent development.

hdx model pull mistralai/Mistral-7B-Instruct-v0.3
hdx model pull mistralai/Mistral-7B-Instruct-v0.3 --alias mistral-7b

hdx model list

List locally pulled models.

hdx model list                     # Table output
hdx model list --json              # JSON output

hdx model remove

Remove a locally pulled model.

hdx model remove mistral-7b
hdx model remove mistral-7b --yes  # Skip confirmation

Configuration

HatchDX reads config from pyproject.toml or hdx.toml (generated automatically by hdx server create).

pyproject.toml (Python projects):

[tool.hdx]
server_command = "python -m weather_mcp.server"
fixtures_dir = "tests/fixtures"

hdx.toml (TypeScript/other projects):

[server]
name = "weather-mcp"
command = "node dist/server.js"

[testing]
fixtures_dir = "tests/fixtures"

Development

# Clone and install
git clone https://github.com/ceasarb/hatchdx.git
cd hatchdx
uv sync

# Run tests
pytest tests/ -v

# Lint
ruff check src/
ruff format src/

License

MIT