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
- Use
happy_list_machinesto find an online machine - Use
happy_list_recent_pathsto find a good working directory - Use
happy_start_sessionwithwait=trueto start and wait for the initial task
Monitor an existing session
- Use
happy_list_sessionsto find active sessions - Use
happy_read_messagesto see what the AI is working on - Use
happy_send_messageto give it new instructions
Clean up old sessions
- Use
happy_list_sessionsto see all sessions - Use
happy_archive_sessionto stop sessions you no longer need
Environment Variables
HAPPY_SERVER_URL: Override the Happy server URL (default:https://happy.engineering)
License
MIT