Claude Code / MCP Integration MCP

Configure Heed as an MCP (Model Context Protocol) server so that Claude Code, Cursor, and other MCP clients can request human approval natively. No custom code required — just a config entry.

Prerequisites

Quick Start

pip install heed-mcp

export HEED_API_KEY="hd_live_your_key_here"

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

curl -X POST https://heed.run/api/v1/hitl/policies \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HEED_API_KEY" \
  -d '{
    "name": "gate-destructive",
    "description": "Require approval for destructive actions",
    "rules": [
      {
        "action": "delete_record",
        "requires_approval": true
      },
      {
        "action": "send_email",
        "requires_approval": true
      }
    ],
    "is_active": true
  }'

Configuration Reference

Claude Code

Edit your MCP settings file. The location depends on your OS:

• macOS: ~/.claude/claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

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

Cursor Cursor

Open Cursor Settings → MCP → Add new server. Use the same config format, or edit .cursor/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"
      }
    }
  }
}

Other MCP Clients Generic

Any MCP-compatible client that supports stdio transport can use Heed. The config format is the same — specify heed-mcp as the command and provide the HEED_API_KEY and HEED_BASE_URL environment variables.

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

Tool Reference

Heed exposes a single MCP tool:

request_approval

Submits an approval request to Heed. If a policy gates the action, the server polls until a human decides. Returns the decision.

Returns: "approved" or "rejected"

Example Session

Here's what it looks like when Claude Code uses Heed to gate a destructive action:

Creating the Policy

Without a policy, all actions auto-approve. To gate actions, create a policy with rules that match:

curl -X POST https://heed.run/api/v1/hitl/policies \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hd_live_your_key" \
  -d '{
    "name": "gate-destructive",
    "description": "Require approval for destructive or external-facing actions",
    "rules": [
      {
        "action": "delete_record",
        "requires_approval": true
      },
      {
        "action": "send_email",
        "requires_approval": true
      },
      {
        "action": "modify_schema",
        "requires_approval": true
      }
    ],
    "is_active": true
  }'

Manage policies from the Policies dashboard or via the API.

System Prompt Tips

Add these instructions to your Claude Code system prompt or CLAUDE.md to ensure it always requests approval:

# Human-in-the-Loop Policy

Before executing any of the following actions, you MUST call the
`request_approval` tool and wait for the result:

- Deleting records from production databases
- Sending emails to external recipients
- Modifying database schema (migrations)
- Deploying to production
- Making payments or refunds

If `request_approval` returns "rejected", do NOT proceed.
Explain to the user that the action was not approved.

Environment Variables

Next Steps

• Full API documentation — all endpoints, authentication, webhook signing
• Swagger UI — interactive API explorer
• More integration guides — LangChain, OpenAI Agents SDK
• MCP overview in docs — general MCP integration details
• Dashboard — review and approve pending requests