MCP host setup

This page is about MCP hosts (Cursor, Claude Desktop, custom agents, automations) that spawn happier mcp serve.

Use it when you want an external editor or agent to act on Happier sessions through the same authenticated account and action catalog as the app and CLI.

Start here for the conceptual overview: Happier MCP (external).

Security model (important)

happier mcp serve runs with the same local privileges as the MCP host process and uses the CLI’s authenticated credentials.

Treat an MCP host’s server configuration as privileged:

• It can execute enabled Happier actions.
• It can request approvals (and execute immediately if approvals are not required for that surface).
• It can access whatever sessions your account allows.

Minimal configuration

Most hosts let you configure a server with:

• a command
• an args array

Example shape:

{
  "mcpServers": {
    "happier": {
      "command": "happier",
      "args": ["mcp", "serve"]
    }
  }
}

If your host does not run in the same shell environment as your terminal, use an absolute command path.

CLI lanes (happier vs hprev vs hdev)

If you installed a preview or dev lane, your command may be:

• happier (stable)
• hprev (preview)
• hdev (dev)

Prefer configuring your MCP host to run the same lane you use in the terminal.

If you want a fully explicit config, use an absolute path:

which happier

Then paste that path as the command in your host config.

Server selection

For security, happier mcp serve does not honor server-selection environment variables (like HAPPIER_SERVER_URL).

To target a non-default server, pass the CLI server selection flags as args:

{
  "mcpServers": {
    "happier": {
      "command": "happier",
      "args": ["--server", "company", "mcp", "serve"]
    }
  }
}

Or target ad-hoc URLs:

{
  "mcpServers": {
    "happier": {
      "command": "happier",
      "args": ["--server-url", "https://api.company.example", "--webapp-url", "https://app.company.example", "mcp", "serve"]
    }
  }
}

Session scoping

You can set a default session context at server start:

{
  "mcpServers": {
    "happier": {
      "command": "happier",
      "args": ["mcp", "serve", "--session", "<session-id>"]
    }
  }
}

Many tools also accept an explicit sessionId argument; prefer passing sessionId when building deterministic automations.

Notes:

• Prefer a full session id in --session for saved host configs.
• Unambiguous prefixes are often accepted, but an ambiguous prefix will fail and return candidates.

Renaming the current session

If your MCP host wants to rename the current/default session without tracking ids, use:

• change_title (input: { "title": "..." })

Use session_title_set when you want to rename a specific session by id/prefix.

Daemon requirement (local session control)

Most “control plane” reads (like session_list) only require valid CLI authentication. But anything that needs to start/drive a local provider process (create sessions, send messages, attach, etc.) generally requires the Happier daemon to be running on that machine.

If your MCP host gets an error like No daemon running, start it:

happier daemon start

Recommended workflow for “any action”

When you don’t know the action id or the valid option values:

1. Discover:
   • action_spec_search
   • action_spec_get
2. Resolve options when needed:
   • action_options_resolve
3. Execute:
   • action_execute

This keeps clients resilient even as Happier evolves the action catalog.

Approvals

Approvals are configured per action + surface in the app:

• Settings → Actions

When an MCP tool call is approval-gated, the tool returns an approval_request_created payload with an artifactId. Approve/deny in the Inbox:

• Inbox and approvals