npm package: @happyrobot-ai/mcp
Description: HappyRobot MCP Server - Manage workflows via Claude Desktop, Claude Code, or any MCP client
Author: HappyRobot
Latest version: 0.1.9

# @happyrobot-ai/mcp

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for managing HappyRobot workflows. Works with Claude Desktop, Claude Code, or any MCP-compatible client.

## Quick Start

### Claude Code

```bash
claude mcp add -s user happyrobot -- npx @happyrobot-ai/mcp
```

Or with the API key pre-configured:

```bash
claude mcp add -s user happyrobot -e HAPPYROBOT_API_KEY=sk_live_xxx -- npx @happyrobot-ai/mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "happyrobot": {
      "command": "npx",
      "args": ["@happyrobot-ai/mcp"],
      "env": {
        "HAPPYROBOT_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

### `.mcp.json` (project-level)

```json
{
  "mcpServers": {
    "happyrobot": {
      "command": "npx",
      "args": ["@happyrobot-ai/mcp"],
      "env": {
        "HAPPYROBOT_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

## Configuration

| Variable | Description | Default |
|---|---|---|
| `HAPPYROBOT_API_KEY` | Your API key (`sk_live_*` or `sk_test_*`) | _(none, required)_ |
| `HAPPYROBOT_CLUSTER` | Cluster to connect to: `us` or `eu` | `us` |
| `HAPPYROBOT_API_BASE_URL` | Override the API base URL (takes precedence over `HAPPYROBOT_CLUSTER`) | `https://platform.happyrobot.ai/api/v2` |

### Clusters

| Cluster | URL |
|---|---|
| `us` (default) | `https://platform.happyrobot.ai/api/v2` |
| `eu` | `https://platform.eu.happyrobot.ai/api/v2` |

For EU users:

```bash
claude mcp add -s user happyrobot -e HAPPYROBOT_API_KEY=sk_live_xxx -e HAPPYROBOT_CLUSTER=eu -- npx @happyrobot-ai/mcp
```

If the API key is not set via environment variable, the `setup` tool will prompt for the API key and cluster at runtime.

## Available Tools

| Tool | Description |
|---|---|
| `setup` | Configure your API key at runtime |
| `create_workflow` | Create a workflow from scratch, template, or inline nodes |
| `fix_broken_vars` | Diagnose and fix broken variable references |
| `list_workflows` | Search and list workflows with pagination |
| `get_workflow_details` | Inspect workflow config, versions, and nodes |
| `update_workflow_nodes` | Add, update, or delete nodes in a version |
| `manage_versions` | Fork, publish, unpublish, lock, unlock versions |
| `trigger_run` | Trigger a workflow run with payload |
| `monitor_runs` | List runs, view sessions, recordings, manage annotations |
| `manage_variables` | CRUD workflow-scoped environment variables |
| `manage_phone_numbers` | List, purchase, update, and delete phone numbers |
| `list_integrations` | Search integrations, events, and fetch integration resources (Slack channels, Google Sheets, etc.) |
| `get_available_variables` | Get upstream variables available to a node |
| `get_node_config_schema` | Get the configuration schema for a node's event |
| `manage_workflow` | Cancel runs, update metadata/settings, delete, duplicate |
| `manage_sip_trunks` | List, create, update, and delete SIP trunks |
| `browse_workflows` | Browse workflow folders and explore folder hierarchy |
| `test_workflow` | Test workflow versions — run all node tests or test a single node |
| `manage_mcp_servers` | List, create, and refresh MCP server connections |
| `manage_credentials` | List and create credentials for integrations |
| `fix_prompt_issues` | Fetch prompt quality issues and get LLM guidance on fixing them |
| `manage_northstars` | Manage northstar success criteria for evaluating prompt nodes |
| `manage_custom_evals` | Manage custom eval tests (expected responses, tool calls) for prompt nodes |
| `manage_adversarial_tests` | Manage adversarial (red-team) tests for agent nodes |
| `manage_adversarial_suites` | Manage batched adversarial test suites for agent nodes |
| `get_node_details` | Fetch full configuration details of a single workflow node |

## Knowledge Base Prompts

The server also ships five wiki-style prompts that inject domain knowledge into the LLM context. Invoke them in Claude Code with `/mcp__happyrobot__<name>`:

| Prompt | Invocation | What it covers |
|---|---|---|
| Variable reference guide | `/mcp__happyrobot__variable-guide` | Syntax rules (`{{index.field}}` vs `{{persistent_id.field}}`), output path patterns per node type, common mistakes (AI Extract `response.` prefix, loop `iteration_element`), condition value format, diagnosing broken refs |
| Node types reference | `/mcp__happyrobot__node-types` | What each node type does, key config fields, outputs, and common pitfalls |
| Workflow tool patterns | `/mcp__happyrobot__workflow-patterns` | Tool sequencing, when to use `get_node_details` vs `get_workflow_details`, how `fix_broken_vars` and `fix_prompt_issues` differ, version management patterns |
| Evaluation tools guide | `/mcp__happyrobot__eval-guide` | How northstars, custom evals, adversarial tests, and suites layer; when to use each; extracting evals from production runs |
| Platform setup reference | `/mcp__happyrobot__platform-setup` | Integration/credential discovery, phone numbers, SIP trunks, MCP server connections, workflow variables |

## API Documentation (Optional)

For full API docs access, add the HappyRobot docs MCP alongside this server. This lets Claude search and read the API reference when building workflows:

```bash
claude mcp add happyrobot-docs -- npx @mintlify/mcp --docs https://docs.happyrobot.ai
```

## Development

```bash
# Install dependencies
npm install

# Run in development mode
HAPPYROBOT_API_KEY=sk_test_xxx npm run dev

# Build for production
npm run build
```

## License

MIT