Happier MCP (external)

Run Happier as an external stdio MCP server so editors and agents can start/manage sessions and execute Happier actions.

Happier can run its own external MCP server so other MCP hosts (editors, agents, automations) can control Happier:

list and inspect sessions
start/stop/archive sessions
send messages to sessions
change a session’s title / permission mode / model
start execution runs (review / plan / delegate / voice agent)
execute any enabled Happier action (using the action spec as source of truth)

This is separate from MCP servers you manage inside Happier (Playwright, GitHub, etc). Those are documented under MCP servers.

Run the server

The external MCP server is a stdio MCP server (meant to be spawned by an MCP host):

happier mcp serve

happier mcp start is accepted as a compatibility alias.

If you are wiring up a new host, keep serve as the canonical command name in your config so the intent is obvious to the next person who reads it.

Optionally set a default session context for tools that can infer “current session”:

happier mcp serve --session <session-id>

Configure an MCP host

Most MCP hosts let you configure a server by specifying a command and args.

Example shape:

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

Notes:

Ensure happier is on PATH (or use an absolute path to the binary).
The MCP host must run on a machine that is already authenticated to Happier, or the server will fail with not_authenticated.
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 flags in args (see below) or switch the active server profile in the CLI home directory.

Target a specific server

If your MCP host supports it, include the normal CLI server selection flags in the configured args:

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

Or use ad-hoc URLs:

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

Deep reference (host setup and security): MCP host setup.

Quick smoke test

If you want to verify the server is wired correctly, point any MCP host or inspector at:

command: happier
args: ["mcp", "serve"]

Then try the session-control tools first:

session_list
session_message_send
change_title
session_title_set
session_permission_mode_set

If those work, try the generic path next:

action_spec_search
action_spec_get
action_execute

That gives you a quick end-to-end check that the server, account auth, action catalog, and approval routing are all connected.

Tool call examples

The exact JSON shape depends on your MCP host, but tool calls generally pass an args object that matches the tool’s input schema.

If you’re unsure about a tool’s fields, use the discovery tools first:

action_spec_get (to see inputSchema, inputHints, and examples)
action_options_resolve (to resolve valid options for a field)

List sessions

Call session_list with no args:

{}

Send a message (and wait for idle)

Call session_message_send:

{
  "sessionId": "sess_123",
  "message": "ping",
  "wait": true,
  "timeoutSeconds": 60
}

Optional overrides (when supported by the backend):

permissionModeOverride
modelOverride (use null to clear an override when applicable)

Wait for a session to become idle (no message send)

Call session_wait_idle:

{
  "sessionId": "sess_123",
  "timeoutSeconds": 60
}

Rename a session

Rename the current/default session context:

Call change_title:

{
  "title": "Fix flaky tests"
}

Rename a specific session by id/prefix:

Call session_title_set:

{
  "sessionId": "sess_123",
  "title": "Fix flaky tests"
}

Change the permission mode for a session

Call session_permission_mode_set:

{
  "sessionId": "sess_123",
  "permissionMode": "read_only"
}

Start an execution run (plan/review/delegate/voice agent)

Call execution_run_start to start a structured run in a session. It requires an intent plus a backend target.

Example:

{
  "sessionId": "sess_123",
  "intent": "plan",
  "backendTarget": { "kind": "builtInAgent", "agentId": "claude" },
  "instructions": "Plan a safe refactor and list risks."
}

What tools you get

The external MCP surface is a blend of:

Happier action tools (generated from the action spec catalog)
a few manual convenience tools (for common control-plane behaviors)

Common session control tool examples:

session_list
session_status_get
session_message_send
session_stop
session_archive / session_unarchive
change_title (rename the current/default session)
session_title_set
session_permission_mode_set
session_model_set
session_wait_idle

Action discovery tools:

action_spec_search
action_spec_get
action_options_resolve

Generic executor tool:

action_execute (execute any enabled action by actionId with structured input)

Execution run tool:

execution_run_start

The exact set depends on what your account has enabled (and on which surfaces). See “Approvals and enablement”.

Session context and tool variants

Some tools operate on a specific session, and some operate on the current/default session.

Default session (`--session`) vs explicit `sessionId`

Many session control tools accept an explicit sessionId argument.
If a tool supports inferring the session and you do not pass sessionId, Happier uses:
1. the --session <session-id> value passed at happier mcp serve startup (if any), otherwise
2. a global “no session selected” context (some tools will fail with session_not_selected in that case).

For deterministic automations, prefer passing an explicit sessionId.

Session ids and prefixes

When a tool accepts sessionId, it generally accepts either:

a full session id, or
an unambiguous prefix.

If the prefix matches multiple sessions, the tool call fails and includes candidates. For saved MCP host configs (long-lived), prefer full ids.

Changing titles: `change_title` vs `session_title_set`

There are two common ways to rename a session:

change_title: a convenience tool that takes only { "title": "..." } and renames the current/default session context.
session_title_set: the action-backed tool for session.title.set that supports passing a sessionId when you want to rename a specific session.

Both routes go through the same action catalog and the same per-surface policy (enablement + approvals).

Generic action execution

The external MCP server also exposes a generic tool:

action_execute

Use it when:

you already know the exact actionId
you want to call an action that does not have a dedicated named tool
you want to manage approval artifacts programmatically

Shape:

{
  "actionId": "session.title.set",
  "input": {
    "sessionId": "sess_123",
    "title": "Fix flaky tests"
  }
}

Notes:

actionId is the canonical dotted id (example: session.title.set).
Tool names are typically snake_case (example: session_title_set) and map to the same underlying action.

This is also the path to advanced approval actions such as:

approval.request.create
approval.request.decide

Those approval actions are available through the action catalog, but they are not advertised as separate named MCP tools. Use action_execute when you need them.

Approvals and enablement

Happier treats actions as a single catalog that can be enabled/disabled per “surface”, including:

session agents (in-session tools)
voice
CLI
external MCP

In the app, configure this under:

Settings → Actions

For each action + surface, you can:

enable/disable the action
optionally require approval (approval-gated execution)

If a tool is approval-gated, the MCP tool call returns an approval_request_created payload (with an artifactId). This applies both to generic action_execute calls and to built-in aliases such as session_title_set, because they share the same action + surface policy. Use the app's Inbox to approve/deny and view the final result:

Programmatic approval decisions

If you want an MCP host to manage approvals directly, call action_execute with approval.request.decide.

Example:

{
  "actionId": "approval.request.decide",
  "input": {
    "artifactId": "2765bc88-69ea-4316-9085-290ce5b3a3b6",
    "decision": "approve"
  }
}

That executes the same approval object you can review in the app Inbox. The same generic approval model works regardless of whether the request came from the CLI, an external MCP host, a session agent, or another Happier surface.

Troubleshooting

`not_authenticated`

Authenticate the CLI first:

happier auth login

If you’re targeting a self-hosted server, ensure the MCP host launches Happier with the right server profile (or server URL flags). See CLI → Server profiles.

`No daemon running` / session create fails

Starting and managing local provider processes (creating sessions, sending messages, attaching, etc.) generally requires a running Happier daemon on that machine.

If a tool call fails with an error like No daemon running (or similar), run:

happier daemon start

For a smoother always-on setup (recommended), install it as a user service:

happier daemon install

A tool is missing

Tool visibility is driven by the action spec catalog and your account settings. Check:

Settings → Actions (surface enablement + approvals)
Settings → MCP servers (if you expected a custom MCP server tool, not a Happier action tool)

Happier MCP (external)

On this page