Give an AI agent its own hero in Pixel Underworld. It can explore visible terrain, fight enemies, complete quests, manage gear, and save progress through five bounded tools.
The game runs each action through the same rules human players use. Your agent chooses goals; the server handles movement and combat frames.
Recommended for an agent running on your computer. Setup creates a guest hero and saves credentials locally with restricted file permissions. The adapter refreshes a short-lived agent credential and keeps the hero connected while your model thinks.
Set up local MCP →Point a client that supports custom Authorization headers to https://pixel-underworld.com/mcp. Exchange a game session for a one-hour agent credential, then send it as a Bearer token. Renew it before expiry.
Call POST /api/agent/{tool} from any programming language. The same authentication, capacity, and action rules apply. Use the machine-readable API description to build a client.
Node.js 22 or later is required. The adapter currently ships from the source repository.
git clone https://github.com/cheng-ying/pixel-underworld-hd2d.git
cd pixel-underworld-hd2d
npm ci
node tools/agent-cli.mjs setupConfigure your MCP client to run node /absolute/path/pixel-underworld-hd2d/tools/agent-cli.mjs stdio. The setup command prints the hero name and credential file path, never the credential. Keep that file private.
POST /api/auth/guest, then create a hero with POST /api/characters. Keep the returned game session private.POST /api/auth/agent-token with Authorization: Bearer <game session>. The response contains an agent token and its expiry time.Authorization: Bearer <agent token> to POST /mcp or a REST game tool. The game session itself is rejected by those endpoints. Renew the agent token before its one-hour expiry.POST /api/auth/agent-token/revoke with the game session to disable the current agent token.Use HTTPS for remote clients. The hosted MCP endpoint uses stateless Streamable HTTP and supports clients that let you set a Bearer header. It does not currently provide OAuth discovery for clients that require OAuth.
| Tool | Purpose |
|---|---|
game_session | List heroes, open one, check status, or close it. |
game_observe | Read a compact observation and wait for an action to finish. |
game_inspect | Read a paged map, dialogue, quest, shop, skill, item, or entity. |
game_act | Choose one bounded movement, combat, interaction, or inventory action. |
game_cancel | Stop the current action using its exact ID and version. |
Open one hero per account. A hero session expires after 15 seconds without an agent request, or 2 minutes while dialogue is open. Clients should check session status every 5 seconds. Maximum action horizon is 30 seconds; wait time per call is at most 10 seconds. Responses have a per-account rate limit.
Start with a dedicated guest hero so your bot does not control a personal character. Use a fresh request_id for each action, pass the returned expected_control_version, and repeat an identical request ID only to retrieve its receipt. Read the current observation before choosing the next action.
See the full protocol guide and OpenAPI description. Current service capacity is limited; status reports whether agent access is enabled.
Start a hero, follow the first quest, and share a run with the community.
Explore the world