horizOn MCP Server

Official

by ProjectMakersDE

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Get Player State

horizon_get_state

Read-onlyIdempotent

Retrieve a player's server-owned balances, daily earnings, and caps for each value key to display wallets or verify spendable funds before a run. Read-only; requires userId and sessionToken.

Instructions

Returns the player's server-owned values (Validated Actions): balance, today's earnings and daily cap per value key, such as currency or loot counters. Use when: the game shows the wallet or checks whether a spend is possible before starting a run. Not for: changing balances: nothing writes a balance directly, only accepted runs through horizon_submit_validated with earned. Also not for the save game (use horizon_load_cloud_data). Requires: userId and the player's session: sign in with horizon_signin_email or horizon_signin_anonymous and pass its accessToken as sessionToken. Side effects: None (read only). Returns: {userId, day, values: [{key, balance, earnedToday, dailyCap}]}: every value key defined in the API key's rules, sorted by key (balance 0 when never earned); values is empty when the rules define no values. day is the current UTC day, earnedToday the positive credit on that day (0 after midnight UTC), dailyCap null without a daily cap; the other value rules stay hidden. Games may mirror the values into cloud save for offline display but must never send them back. Errors: The error result names the stable code: 401 SESSION_REQUIRED (sign in again), 403 SESSION_FORBIDDEN (pass the userId that signed in), 404 PLAYER_NOT_FOUND, 429 without code (account request limit, wait). Needs HORIZON_API_KEY. Every failure returns an error result (isError) with the HTTP status and body: a 401 that horizon_test_connection also returns means HORIZON_API_KEY is wrong, 429 means the account's per-minute rate limit was reached (wait a minute, then retry).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`userId`	Yes	Player user ID (UUID) from horizon_signup_* or horizon_signin_*
`sessionToken`	Yes	accessToken from horizon_signin_email or horizon_signin_anonymous for this userId; sent as a Bearer session

Output Schema

TableJSON Schema

Name	Required	Description	Default
`day`	No
`userId`	No
`values`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.6.0Oct 2, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial context beyond them: required session token sourcing, the UTC-day reset semantics of earnedToday, the 0-when-never-earned default, the empty-values case, and a full error taxonomy (401/403/404/429) with remediation. This is far richer than the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and organized under clear labels (Use when / Not for / Requires / Side effects / Returns / Errors), which aids scanning. It is on the long side and the Returns section overlaps the output schema, but for a tool with this many auth and error paths the length is largely earned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of session-authenticated reads with specific error codes, the description covers prerequisites, side-effect profile, return shape semantics, and failure handling. Even though an output schema exists, the added day/dailyCap/sorting semantics make it complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so userId and sessionToken are already documented in the schema; the description's 'Requires: userId and the player's session' largely restates that. It adds only the constraint that the session must come from a matching sign-in, which is marginal value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Returns the player's server-owned values (Validated Actions)') and enumerates the concrete payload (balance, today's earnings, daily cap). It explicitly names siblings it is not (horizon_submit_validated, horizon_load_cloud_data), so an agent can separate it from the many horizon_* tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit 'Use when' trigger (wallet display, pre-spend check), an explicit 'Not for' exclusion with the correct alternative named for each case (horizon_submit_validated for writes, horizon_load_cloud_data for saves). Nothing about selection is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server