Gameye

Gameye MCP Server

A Model Context Protocol server for the Gameye game server orchestration API. It lets an AI agent (Claude Code, Claude Desktop, Cursor, or any MCP client) launch and inspect game server sessions, check image tags and regions, and fetch logs and artifacts. You talk to it in plain language, and you don't have to leave your editor.

Status: beta (0.x). Tools, inputs and outputs may change between releases, and there may be bugs. The server says so to every client that connects, on startup, and in gameye_context. It is published on npm as gameye-mcp, as a container image at ghcr.io/gameye/gameye-mcp, and in the MCP Registry as io.github.Gameye/gameye-mcp; see the changelog for what changed in each release.

Quick start

GAMEYE_API_TOKEN=<your-token> npx -y gameye-mcp

It needs Node.js 22 or newer. The server speaks MCP over stdio. Normally your MCP client starts it for you (see Install), so you rarely need to run it by hand.

Environments

Gameye has two public API hosts. The server targets sandbox by default.

The environment is a property of the server process. No tool takes an environment argument, so an agent can't switch to production partway through a conversation. If you need both, configure two named server entries (for example gameye-sandbox and gameye-production), each with its own token.

Environment variables

Install

Claude Code

claude mcp add gameye --env GAMEYE_API_TOKEN=<your-token> -- npx -y gameye-mcp

For production, add --env GAMEYE_ENV=production and use a production token.

Other MCP clients

Most clients (Claude Desktop, Cursor, Windsurf and others) accept an mcpServers block:

{

"mcpServers": { "gameye": { "command": "npx", "args": ["-y", "gameye-mcp"], "env": { "GAMEYE_API_TOKEN": " ", "GAMEYE_ENV": "sandbox" } } } }

Restart the client after you change its configuration.

npx -y gameye-mcp runs the latest release. To stay on one version, name it: npx -y gameye-mcp@0.4.0 (or "args": ["-y", "gameye-mcp@0.4.0"]).

Windows

The server runs on Windows with Node.js 22 or newer. We've tested it on Windows 11, through Claude Code and over plain stdio. If something breaks on Windows, please open an issue.

• Many Windows MCP clients can't start npx directly, because it's a .cmd script. Start it through cmd /c instead:

  "command": "cmd",

"args": ["/c", "npx", "-y", "gameye-mcp"]

With Claude Code: claude mcp add gameye --env GAMEYE_API_TOKEN= -- cmd /c npx -y gameye-mcp. Claude Code 2.1.296 and later also start plain npx.

• In PowerShell, type npx.cmd instead of npx when you run the server by hand. A new Windows install blocks the npx PowerShell script with "running scripts is disabled on this system".
• The first start downloads the package and can take 10 to 40 seconds. Later starts take about a second.
• gameye_update_skills reports outdated skills on Windows but doesn't run the update. It prints the commands for you to run.
• gameye_create_token writes the token file with owner-only permissions on macOS and Linux. On Windows those permissions don't apply, and the file gets the access rules of its folder. Write it inside your user profile.

Docker

No Node.js on the machine? Run the published image instead. It works on amd64 and arm64:

{

"mcpServers": { "gameye": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "GAMEYE_API_TOKEN", "-e", "GAMEYE_ENV", "ghcr.io/gameye/gameye-mcp"], "env": { "GAMEYE_API_TOKEN": " ", "GAMEYE_ENV": "sandbox" } } } }

With Claude Code: claude mcp add gameye --env GAMEYE_API_TOKEN= -- docker run -i --rm -e GAMEYE_API_TOKEN ghcr.io/gameye/gameye-mcp.

• Pass each variable with -e NAME (no value), so Docker copies it from the client's environment and the token never appears in the command line.
• Keep -i and never add -t: a terminal mangles the JSON-RPC messages on stdout.
• To stay on one version, use a version tag such as ghcr.io/gameye/gameye-mcp:0.4.0.
• Files the server writes stay inside the container, and --rm deletes them:
• gameye_get_artifacts saves its download under the temp directory. To keep it, mount a directory and point the temp directory at it: -v /absolute/dir:/out -e TMPDIR=/out. The path the tool reports is the container path; the file is in /absolute/dir on the host.
• gameye_create_token writes to the outputPath you give it. Mount a directory the same way and pass an outputPath under /out.
• The server runs as uid 1000, so on Linux the mounted directory must be writable by that user.

Token scopes

Give the server a token with only the scopes it needs.

Never pass your Gameye API token into a game server's environment. A game server doesn't need it, and anything inside the container can read it.

Available tools

Every tool result starts with the environment and host it used, for example [sandbox · api.sandbox-gameye.gameye.net].

Every tool carries MCP annotations: read tools set readOnlyHint, gameye_stop_session and gameye_edit_application set destructiveHint, and every tool that calls the Gameye API sets openWorldHint.

The tool set covers every operation in the Gameye client API. tests/parity.test.ts checks this against the vendored spec in spec/.

Guardrails

These behave the same on sandbox and production, because sandbox runs live matches for self-serve customers.

• Dry run. gameye_launch_session, gameye_stop_session, gameye_enable_tag and the application and token tools accept dryRun: true. The tool returns the exact request (method, host, path and body) with the API token masked, and sends nothing.
• Bounded sessions. A launch without ttl gets a 30m TTL, and the result says the default was applied. Every launch sends the label launched-by: gameye-mcp, replacing any launched-by value the caller passes, so agent-launched sessions can be found with gameye_list_sessions and filter: { "launched-by": "gameye-mcp" }. When a warm pool serves the image and region, the Gameye API ignores request labels (and env and args), so warm-pool sessions do not carry this label.
• No token in game servers. A launch is refused, with nothing sent, if any env value or name, arg, or label key or value contains this server's Gameye API token. Env values are never shown in results.
• No token in results. Every tool result, including errors, has this server's API token replaced with ***, in case log output, labels or an error message echo it.
• Explicit stops. gameye_stop_session stops exactly one session by its exact ID. There is no bulk stop, and empty, wildcard or list IDs are refused. With GAMEYE_STOP_OWN_ONLY=1 it also refuses any session this server did not launch.
• Session limits. The Gameye API has no per-token budget, so the server enforces one before it sends a launch. By default an agent can have at most 5 sessions it launched running at once (GAMEYE_MAX_SESSIONS), each with a TTL of at most 4h (GAMEYE_MAX_TTL)