MCP Server

MCP Server

GG Scale has an MCP (Model Context Protocol) endpoint at POST /mcp. A coding agent such as Claude Code, Cursor, or Codex can use it to set up a Game Project and to find why online play fails.

The agent connects with an MCP token. A token works for one Game Project. It can always use the read tools, and each group of write tools needs a scope that you select when you make the token.

The endpoint is off by default. An operator turns it on with FEATURE_MCP_ENABLED=true. See Turn on the endpoint.

Make a token

Only an owner or admin of the Account Tenant, or a platform admin, can make a token.

1. In the control panel, open the Game Project, then Game Project settings.
2. In the MCP tokens card, select Manage MCP tokens. The card shows only when the endpoint is on.
3. Type a label of up to 64 characters and the number of days until the token expires. The default is 30 days.
4. Under Access, select one option:
   • Read only gives no write scopes.
   • Read and write gives all the write scopes that you have permission for.
   • Custom gives only the scopes that you check.
5. Select Create token.
6. Copy the token (ggm_...). The page shows it one time.

Connect an agent

Claude Code:

claude mcp add --transport http ggscale https://<host>/mcp \
  --header "Authorization: Bearer ggm_..."

For another agent, add a streamable HTTP server with the URL https://<host>/mcp and the header Authorization: Bearer ggm_....

Then give the agent a task, for example: "Use project_health_check and tell me why matchmaking does not work."

Read tools

Every token can use these tools.

Tool	What it does
project_health_check	Finds setup problems: API keys and their scopes, feature grants, server feature switches, relay, CORS origins, Steam sign-in, remote config size, and quota state.
matchmaking_ticket_trace	Shows one ticket by ticket ID, or the queued ticket of a player. GG Scale keeps finished tickets for 24 hours.
get_remote_config	Returns the remote config and its revision number.
list_leaderboards, get_leaderboard	Return leaderboard settings, with no scores. Use include_deleted to also list deleted leaderboards.
list_api_keys	Lists the active keys that work for the Game Project, without the key values. The list includes keys that are not pinned to a Game Project.
list_revisions	Lists the newest 3 revisions of the remote config or of one leaderboard.

Write scopes

Scope	Tools	Undo
config:write	set_remote_config, rollback_remote_config	rollback_remote_config
leaderboards:write	create_leaderboard, update_leaderboard, rollback_leaderboard, delete_leaderboard, restore_leaderboard	rollback_leaderboard or restore_leaderboard
keys:create	create_api_key	Revoke the key in the control panel.
origins:write	set_allowed_origins	Call it again with the old list from its result.

The token page offers only the scopes that you have permission for.

These rules apply to the write tools:

• set_remote_config, update_leaderboard, and the rollback tools need expected_revision, the newest revision number from a read tool. The server refuses a stale number, so an agent cannot overwrite a change that it did not see.
• GG Scale keeps the newest 3 revisions of the remote config and of each leaderboard. A leaderboard rollback restores the settings. Scores do not change.
• update_leaderboard replaces all the settings. It removes an optional setting that the call does not send.
• delete_leaderboard keeps the scores. restore_leaderboard fails if a live leaderboard in the Game Project has the same name.
• set_remote_config and the leaderboard metadata_json take the JSON object as a string, so large numbers stay exact.
• create_api_key makes publishable (ggp_) keys only. The call fails when MCP_MAX_PROJECT_API_KEYS active keys are pinned to the Game Project.
• No tool can make a secret key, revoke a key, or delete a Game Project.

The audit log records each tool write as mcp_token:<id>, with the person who made the token.

What a token can see

No tool returns a secret, a player email, a display name, an IP address, or storage content.

A game client can put any text in a matchmaking ticket, so matchmaking_ticket_trace shows that text only when it is a short identifier: letters, digits, _, -, or ., up to 64 bytes. The tool replaces other text with a marker that gives the length of the text. This stops a player from writing instructions to your agent. The tool never shows the attributes blob, only its size.

Token lifetime

A token never has more rights than the person who made it. The server checks that person on each request. If that person leaves the Account Tenant or becomes a member, the token stops working and the token list shows it as inactive. If that person is disabled, the token also stops working, but the list can still show it without the inactive label.

To stop a token, select Revoke in the token list. You need the same role as for making a token. If you did not make the token, you also need permission to manage secret API keys. An expired token stays in the list for 30 days. To replace it, make a new token.

Common errors

The server sends these errors as plain text before any tool runs.

Status	Meaning	Action
401 unauthorized	The token is missing, unknown, or revoked.	Check the header, or make a new token.
401 token expired	The token expired.	Make a new token.
403 forbidden origin	The request has an Origin header for a different host. Coding agents send no Origin header.	Do not call /mcp from a web page.
403 forbidden	The Account Tenant or the person who made the token is disabled, or the Game Project is deleted.	Find which case applies and correct it. If only the person is disabled, you can also make a new token as a different person.
403 with can no longer manage this Game Project	The person who made the token lost that permission.	Make a new token as a person with that permission.
429 rate limit exceeded	The token went over its request rate. The message gives the wait in seconds.	Wait, then try again.
429 too many failed authentication attempts	This source IP sent too many bad tokens.	Fix the token, then wait.

A tool call with a missing scope returns a tool error that names the scope. tools/list shows only the tools that the token's scopes permit.

Turn on the endpoint

This section is for operators. Set FEATURE_MCP_ENABLED=true and start the server again. The server mounts /mcp and adds the token page to each Game Project. Configuration Reference lists the limits and their defaults. The platform admin Server settings page shows the current token limits.

• /mcp is public, because coding agents connect to it.
• Each server process counts the per-token rate on its own. With two app hosts, the limit for a token can be two times the value that you set.
• Failed authentications use a separate limit for each source IP. Valid tokens do not use it, so they keep working from an IP that sent bad tokens. Behind a load balancer, set TRUSTED_PROXY_HEADER and TRUSTED_PROXY_CIDRS so that the server sees the client IP.
• CORS_MAX_PROJECT_ORIGINS limits the origins for each Game Project, for both set_allowed_origins and the control panel form.