Happy Server

You can run a local MCP server to manage Happy AI sessions, enabling you to list, start, message, and archive sessions across connected machines. This server acts as a bridge between your Happy AI workspace and programmatic controls, so you can automate workflows and integrate AI sessions into your tooling.

How to use

Install and run the MCP server locally, then connect your MCP client to manage Happy AI sessions. You can list sessions, list machines, view recent working directories, read and send messages, start new sessions, archive finished ones, and wait for processing to complete.

How to install

Prerequisites you need before starting:

1. Make sure you have Node.js installed on your system.

2. You must be authenticated with Happy CLI. Run happy auth. This creates credentials at ~/.happy/access.key that the MCP server uses.

Configuration and usage with clients

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

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

Environment variables

You can override the server URL with an environment variable when needed.

Tools and endpoints you can access

The MCP server exposes a set of endpoints to manage Happy AI sessions. Typical actions include listing sessions, listing machines, reading and sending messages, starting sessions, archiving, and waiting for idle state. Use the configured clients to call these actions programmatically.

Common workflows

Start a session on an online machine, choose a working directory from recent paths, and optionally wait for the initial task to complete.

Notes on security

Ensure you keep your Happy CLI credentials secure. The MCP server relies on those credentials to authenticate actions against your Happy workspace.

Troubleshooting

If you encounter connection issues, verify that your Happy CLI is authenticated and that the MCP server is reachable at the configured endpoints. Check that the HAPPY_SERVER_URL (when used) points to the correct server and that your client is configured to use the same MCP server as defined in your connector settings.

Examples of common commands

See the code blocks above for setup and client configuration examples you can copy and adapt.

Available tools

happy_list_sessions

List all Happy AI sessions with IDs, titles, paths, machines, and activity status. Supports a limit parameter to cap results.

happy_list_machines

List all registered machines with their IDs, hostnames, platforms, and activity status.

happy_list_recent_paths

List recently used working directories for a specific machine, with an optional limit.

happy_read_messages

Read recent messages from a specific session to review conversation history.

happy_send_message

Send a message to a session to trigger work, with an optional wait for processing to finish.

happy_start_session

Start a new session on a chosen machine and directory, with optional initial message and agent type.

happy_archive_session

Archive (stop) a session and mark it inactive.

happy_wait_for_idle

Wait for a session to become idle after processing is finished.