horizOn

horizOn MCP Server

MCP server for horizOn Backend-as-a-Service

Gives AI coding assistants documentation, live API tools, and workflow prompts for game and app development.

Quick Install

Add to your MCP client configuration (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "horizOn": {
      "command": "npx",
      "args": ["-y", "horizon-mcp"],
      "env": {
        "HORIZON_API_KEY": "your-api-key-here"
      }
    }
  }
}

Features

The server exposes 29 documentation resources, 120 player tools and 4 workflow prompts. An Account Key enables additional scoped admin tools. These counts come from the registered MCP resources, tools and prompts.

Resources

Documentation resources are served directly from the MCP server. No API key required.

Player tools

Live API tools that call the horizOn backend. Requires a valid API key.

horizon_submit_score, horizon_save_cloud_data, horizon_load_cloud_data, horizon_prepare_gift_code, horizon_redeem_gift_code, horizon_get_profile, horizon_set_profile, horizon_start_run, horizon_submit_validated, horizon_get_state and horizon_upload_evidence also need the player's session: sign in first and pass the returned accessToken as sessionToken.

The four player-value tools also require the same player session. Never generate another operation ID automatically after an uncertain result.

Every tool declares MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so clients can tell reads from writes. Examples of destructive tools include horizon_save_cloud_data (replaces the save), horizon_set_profile (replaces the whole profile), horizon_submit_validated (consumes the ticket, can spend balances) and horizon_cancel_email, plus horizon_purchase_player_value_offer and horizon_adjust_player_value (debit or credit exactly once per persisted operation ID). Many read tools that return an object also declare an outputSchema and return structuredContent next to the JSON text. Each description names when to use the tool, which sibling to use instead, what it returns and how to recover from its errors.

Prompts (4 prompts)

Workflow prompts that guide AI assistants through common horizOn tasks.

Configuration

Resources (documentation) work without an API key. Only the live API tools require authentication. Session-bound tools also require the matching player session and declare userId and sessionToken in their input schemas.

Feature availability follows the selected backend and project configuration. Realtime, chat, Validated Actions and ranked match validation require hosted horizOn. The self-hosted simpleServer supports a subset of the REST APIs. MCP tools make explicit HTTP calls and do not create a background WebSocket connection, polling loop or automatic trading/retry process.

Admin Tools (v1.2+)

With an Account Key (creatable in your horizOn Dashboard -> API Keys -> Create -> Account Key), the MCP server exposes additional tools that let Claude manage your dashboard -- projects, remote config, news, email templates, gift codes, users, leaderboards, cloud-save data, crash reports, feedback, user logs, SMTP, and Validated Actions (rules, runs, player values and the evidence review).

How to get your Account Key

1. Log in to your horizOn Dashboard
2. Navigate to API Keys in the sidebar
3. Click Create API Key
4. Select Account Key as the key type
5. Choose whether the key can access the entire account, a single Project API Key, or selected feature groups
6. Click Create -- your key will be shown once. Copy it immediately.
7. Add the key to your MCP configuration (see Setup below)

Setup

Add both keys to your MCP client configuration:

{
  "mcpServers": {
    "horizOn": {
      "command": "npx",
      "args": ["-y", "horizon-mcp"],
      "env": {
        "HORIZON_API_KEY": "your-project-key (for player-facing tools)",
        "HORIZON_ACCOUNT_API_KEY": "your-account-key (for dashboard tools)"
      }
    }
  }
}

Both can be set together or individually. Admin tools only register when the account key is set -- otherwise the server exposes only the original player-facing tools.

Scope

Account Keys inherit your account's tier (FREE/BASIC/PLUS/PRO/ENTERPRISE) -- they grant no extra privileges. A key can be full-account, limited to a single Project API Key, limited to selected feature groups, or both. Platform-admin-only endpoints (Blog, Banner, System-Config) are automatically unreachable. A handful of ultra-sensitive endpoints (account deletion, credentials change, key management itself, subscription cancel) require a dashboard session and cannot be called via an Account Key.

When a key is project-scoped, the backend enforces that scope on direct HTTP calls too. Account-wide endpoints or ID-only endpoints that cannot prove project context are rejected for project-scoped keys.

Tool Groups

Admin tools carry the same annotations as the player tools: list, get and statistics tools are read only, update and delete tools are marked destructive.

What is horizOn?

horizOn is a multi-tenant Backend-as-a-Service platform built for game and app developers. It provides a managed backend so developers can focus on building their game or app instead of server infrastructure.

Core features:

• Authentication (Anonymous, Email, Google, Apple)
• Leaderboards
• Cloud Save
• Remote Config
• Localization
• News and Announcements
• Gift Codes
• Player Profile (avatar, frame, badges)
• Player Values (atomic configured purchases, safe adjustments, minimal public replay guards)
• Statistics, inbox rewards and achievements
• Friends, blocklists and groups
• Item catalogs, unique inventory and marketplace escrow/trades
• Shared objects with scoped permissions and asynchronous matches
• Hosted chat, with realtime managers provided by the native SDKs
• Validated Actions (server-checked runs, validated only leaderboards, server-owned currency)
• User Feedback
• User Logs
• Crash Reporting
• Email Sending

Learn more at horizon.pm. Install this MCP server via npm.

Supported Engines

• Godot 4.5+ -- GDScript SDK
• Unity 6 -- C# SDK
• Unreal Engine 5.5+ -- C++ and Blueprint SDK

Development

# Clone the repository
git clone https://github.com/ProjectMakersDE/horizOn-mcp.git
cd horizOn-mcp

# Install dependencies
npm install

# Start the server (development mode)
npm run dev

# Build for production
npm run build

# Run tests
npm test

License

MIT

Statistics tools

horizon_get_statistics, horizon_get_statistics_definitions and horizon_update_statistics expose explicit session counters. Persist the original timestamp:UUID and immutable batch before posting; after a timeout reuse that intent, never generate a replacement ID automatically. Read horizon://docs/statistics or use integrate-feature with feature=statistics for engine guidance. Four Account Key tools inspect/replace definitions with If-Match, inspect one owned player and read tier limits (horizon_admin_statistics_*). Statistics are separate from player values.

Inbox tools

Four player tools read, mark read, claim and remove inbox entries with the active session. Four horizon_admin_inbox_* tools manage immutable broadcasts or inspect an owned player with an INBOX-scoped Account Key. Read horizon://docs/inbox before publishing: persist the exact intent, use serverTime for new timestamps, and retain the original ID after an uncertain response. Protected rewards never silently expire or disappear.

Achievements

horizon_get_achievements, horizon_unlock_achievement and horizon_deliver_achievement_rewards expose permanent completion and immediate atomic Player Values rewards. The compatibility delivery tool only reads legacy status. Four horizon_admin_achievements_* tools manage the versioned catalog and inspect owned players with ACHIEVEMENTS scope. Read horizon://docs/achievements for hidden-definition caching, original-key replay and verified cold settlement of legacy originals. New unlocks create no personal Inbox reward/history copy. Engine prompts accept feature=achievements.

Friends

horizon_get_friends, horizon_find_player and seven explicit social-action tools preserve reviewed revisions and pending request IDs. Two read-only horizon_admin_friends_* tools inspect owned state and current limits. Read horizon://docs/friends; both engine prompts accept feature=friends. After an uncertain response, read and reconcile the snapshot before any new player-confirmed action.

Groups

Twenty player tools cover group snapshots, bounded member pages, pending entries, creation, metadata and fourteen explicit membership/role actions. Six read-only horizon_admin_groups_* tools inspect owned projects. All writes preserve reviewed revisions and pending IDs. Read horizon://docs/groups; both engine prompts accept feature=groups. Uncertain writes are never retried automatically.

Items

Five player tools read inventory/catalog and explicitly adjust, equip or discard an instance. Four horizon_admin_items_* tools inspect owned state, page the catalog, edit one template using If-Match and read tier limits. Player-value offers accept bounded itemRewards and grant them atomically with the debit. Read horizon://docs/items; both engine prompts accept feature=items.

Shared Objects

Seven player tools expose bounded opaque shared objects, typed queries and exact-revision writes. Ten horizon_admin_shared_* tools manage owned collections and explicit cleanup. A separate horizon_admin_inbox_send_ordinary tool uses INBOX scope for a trusted backend's durable notice intent. Read horizon://docs/shared-objects; both engine prompts accept feature=shared-objects. Native SDK/PHP/deployment readiness must be checked against the installed version.

Configured policies and technical frames

The new feature tools forward higher/lower current System Config policies rather than treating tier defaults as maxima. Groups expose eleven policies; explicit pages may exceed50 and the default page1 remains usable after lowering. PV supports256 lifetime identities, configured offer counts above1000 and up to256 correction keys. Achievement catalogs can exceed the former 500-key default within current active/lifetime policies and their1 MiB frame. Retained responses are passed through completely after reductions; MCP never truncates a result to a current quota.

Technical bounds stay separate: Shared has a1 MiB decoded object/query envelope and1402200-byte write frame; Matches accepts up to14999552 decoded state bytes (14648KiB) within its20003500-byte create/turn frame. Groups use the complete16 MiB BSON envelope and100663296-byte create/update HTTP frame, with configured name/description/data/depth policies. Fixed item property/template/ delta/grant formats, three Shared search fields and current Chat text/window bounds remain. Validation adds no limits fetch, pagination, retry or database request. These are representation bounds, not a throughput, memory-use or cluster-admission guarantee.

Asynchronous Matches

Fourteen player tools and seven scoped admin tools cover bounded lobbies, opaque turns, immutable result reports and original match-bound ranked-run recovery. Writes keep exact revisions and make one HTTP attempt. Consensus does not award automatic rewards. simpleServer supports ordinary REST and explicitly excludes ranked validation/realtime. Read horizon://docs/matches; engine prompts accept feature=matches.

Hosted Chat (TASK-1014)

Six app tools cover capabilities, deterministic channel open, incremental sync, original send, receipt reconciliation and reporting. Twelve CHAT-scoped admin tools expose word filters, metadata/messages, report moderation, mute/ban and bounded cleanup. Read horizon://docs/chat; engine prompts accept feature=chat. simpleServer explicitly returns 501 NOT_SUPPORTED for chat. These HTTP tools do not create a background WebSocket connection or polling loop. Use the existing native realtime managers for interactive feeds.

Marketplace

The ten player and fourteen scoped operator tools preserve original-item escrow, atomic currency settlement, exact original intent and lossless Inbox returns. Read horizon://docs/marketplace for routes, original revisions, five-tier limits and recovery. Engine prompts accept feature=marketplace. No automatic trading, price polling or retries.