heed-mcp 0.1.0

MCP server for Heed — human approval as a native agent tool

Heed MCP Server

Human approval as a native agent tool. Exposes the Heed HITL API over MCP so Claude Code, Cursor, and any MCP-compatible agent can pause for human sign-off before risky actions.

Install

pip install heed-mcp

Or without installing globally:

uvx heed-mcp

Tools

Tool	Purpose
request_approval(action, summary, context?, priority?, mode?, grace_seconds?)	Submit an action for approval. Returns {status: "approved", auto_approved: true} when no policy matches, else {status: "pending"|"grace_pending", poll_url, expires_at}.
check_approval(request_id)	Poll a submitted request until a human decides (or the grace window auto-approves).

Configuration

Env var	Required	Description
HEED_API_KEY	✅	Tenant API key (hd_live_... / hd_test_...) — from https://heed.run/signup
HEED_BASE_URL	☑️	API base URL (default https://heed.run)
HEED_AGENT_ID	☑️	Agent identifier shown in the dashboard (default mcp-agent)

Claude Code setup

pip install heed-mcp
claude mcp add heed \
  -e HEED_API_KEY=hd_live_your_key_here \
  -e HEED_BASE_URL=https://heed.run \
  -- heed-mcp

Or add to .mcp.json in your project:

{
  "mcpServers": {
    "heed": {
      "command": "heed-mcp",
      "env": {
        "HEED_API_KEY": "hd_live_your_key_here",
        "HEED_BASE_URL": "https://heed.run"
      }
    }
  }
}

Development

From the monorepo (install SDK first):

make install
HEED_API_KEY=hd_test_... HEED_BASE_URL=http://localhost:8000 venv/bin/heed-mcp

Install heed-mcp into its own virtualenv (or use uvx). Installing into the API venv can upgrade starlette past what the pinned FastAPI version supports.

Publish

./scripts/publish.sh

Requires build and twine, plus PyPI token in TWINE_PASSWORD.