Happy Server MCP

MCP (Model Context Protocol) server for managing Happy AI sessions. This allows AI agents to interact with Happy sessions programmatically.

Features

• List Sessions: Query all your Happy AI sessions with their titles, working directories, and activity status
• List Machines: See all registered machines and their online/offline status
• List Recent Paths: Get recently used working directories for a machine
• Read Messages: Fetch recent messages from any session to see conversation history
• Send Messages: Trigger a session to work by sending it a message
• Start Sessions: Spawn new AI sessions on any connected machine
• Archive Sessions: Stop and archive sessions when done
• Wait for Idle: Wait for a session to finish processing

Installation

npm install -g @zhigang1992/happy-server-mcp

Prerequisites

You must be authenticated with Happy CLI. Run:

happy auth

This creates credentials at ~/.happy/access.key that the MCP server uses.

Usage with Claude

Add to your Claude configuration:

{
  "mcpServers": {
    "happy-manager": {
      "command": "happy-server-mcp"
    }
  }
}

Or with npx:

{
  "mcpServers": {
    "happy-manager": {
      "command": "npx",
      "args": ["@zhigang1992/happy-server-mcp"]
    }
  }
}

Available Tools

happy_list_sessions

List all Happy AI sessions. Returns session IDs, titles, paths, machines, and activity status.

Parameters:

Name	Type	Required	Default	Description
limit	number	No	50	Maximum number of sessions to return

Example:

Use happy_list_sessions to see all my active sessions

---

happy_list_machines

List all machines registered with Happy. Returns machine IDs, hostnames, platforms, and activity status.

Parameters: None

Example:

Use happy_list_machines to see which machines are online

---

happy_list_recent_paths

List recently used folder paths for a machine. Useful for starting sessions in familiar locations.

Parameters:

Name	Type	Required	Default	Description
machine_id	string	Yes	-	The machine ID to get recent paths for
limit	number	No	20	Maximum number of paths to return

Example:

Use happy_list_recent_paths with machine_id "abc123" to see recent working directories

---

happy_read_messages

Read recent messages from a Happy AI session. Use this to see the conversation history.

Parameters:

Name	Type	Required	Default	Description
session_id	string	Yes	-	The session ID to read messages from
limit	number	No	20	Maximum number of messages to return

Example:

Use happy_read_messages with session_id "xyz789" to see what the AI has been working on

---

happy_send_message

Send a message to a Happy AI session to trigger it to work. The message will be sent with bypass permissions mode.

Parameters:

Name	Type	Required	Default	Description
session_id	string	Yes	-	The session ID to send the message to
message	string	Yes	-	The message text to send
wait	boolean	No	false	If true, wait for AI to finish processing before returning

Example:

Use happy_send_message with session_id "xyz789" and message "Fix the bug in auth.ts" and wait=true

---

happy_start_session

Start a new Happy AI session on a machine. Use happy_list_machines to find available machines first.

Parameters:

Name	Type	Required	Default	Description
machine_id	string	Yes	-	The machine ID to start the session on
directory	string	Yes	-	The directory path to run the session in
message	string	No	-	Optional initial message to send to start the session working
agent	"claude" | "codex"	No	"claude"	Agent type to use
wait	boolean	No	false	If true, wait for AI to finish processing initial message before returning

Example:

Use happy_start_session with machine_id "abc123", directory "/home/user/project",
message "Review the codebase and suggest improvements", and wait=true

---

happy_archive_session

Archive (stop) a Happy AI session. The session will be terminated and marked as inactive.

Parameters:

Name	Type	Required	Default	Description
session_id	string	Yes	-	The session ID to archive

Example:

Use happy_archive_session with session_id "xyz789" to stop the session

---

happy_wait_for_idle

Wait for a Happy AI session to become idle (finish processing). Useful after sending a message to wait for AI to complete its work.

Parameters:

Name	Type	Required	Default	Description
session_id	string	Yes	-	The session ID to wait for
timeout_seconds	number	No	120	Maximum time to wait in seconds

Example:

Use happy_wait_for_idle with session_id "xyz789" to wait for the AI to finish

Common Workflows

Start a session and wait for completion

1. Use happy_list_machines to find an online machine
2. Use happy_list_recent_paths to find a good working directory
3. Use happy_start_session with wait=true to start and wait for the initial task

Monitor an existing session

1. Use happy_list_sessions to find active sessions
2. Use happy_read_messages to see what the AI is working on
3. Use happy_send_message to give it new instructions

Clean up old sessions

1. Use happy_list_sessions to see all sessions
2. Use happy_archive_session to stop sessions you no longer need

Environment Variables

• HAPPY_SERVER_URL: Override the Happy server URL (default: https://happy.engineering)

License

MIT