hatchdx 0.1.1

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 chat     →  hdx agent eval
  scaffold agent     interactive chat      quality evals

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
• 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
• 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[agent]"           # Both 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.

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 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.

hdx agent create --name assistant --template single-agent --provider anthropic

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

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