Generic Kubernetes MCP servers see an Agones cluster as opaque custom resources. They don't know that an Allocated GameServer has a live match with real players on it, that Fleets scale down by reaping Ready servers first, or that a FleetAutoscaler at its ceiling means players are about to queue. This server speaks Agones natively, so an AI assistant can investigate incidents, answer capacity questions, and operate fleets safely.
Example prompts
Agones MCP server - an AI assistant conducts your Kubernetes game server fleets, safely
2026-10-28
Estrelas
1
Ferramentas
—
Disponibilidade
—
"Why can't EU players get into matches?"
"Which fleets are close to their autoscaler ceiling?"
"Show me every Unhealthy server and what happened to it"
"Scale the practice fleet down to 10 without touching live matches"
"Allocate me a server from the ranked fleet"
A real example, "How full is the ranked fleet?", calling fleet_capacity:
→ "The ranked fleet is at 60% utilization: 3 matches in progress, 2 servers free, autoscaler can grow up to 6 before it's out of room."
Tools
Tool
Type
Description
list_fleets
read
Fleets with desired/ready/allocated/reserved counts
list_gameservers
read
GameServers, filterable by state or fleet
get_gameserver
read
Full detail for one GameServer: labels, annotations, counters/lists, node, image, termination status
gameserver_events
read
Kubernetes events for a GameServer (diagnose failures)
fleet_events
read
Events for a Fleet and its GameServerSets: answers "why did the fleet scale down?"
autoscaler_events
read
Events for a FleetAutoscaler: when and why it scaled
gameserver_logs
read
Container logs for a GameServer (verified to be one first; this is not a general pod log reader). Defaults to the game container, container overrides; previous=true for a crashed instance
list_autoscalers
read
FleetAutoscalers with policy, bounds, scaling-limited status
fleet_capacity
read
Cross-fleet utilization report computed from live GameServer state, not the aggregated Fleet status, which lags a few seconds behind real allocation events. Utilization is allocated / (allocated + ready): the share of playable servers in use
create_fleet
write
Create a Fleet with a single-container GameServer template: port policy and protocol (UDP/TCP/TCPUDP), resources, scheduling, initial Counters/Lists
delete_fleet
write
Delete a Fleet and its GameServers; refuses if any are Allocated unless force=true
scale_fleet
write
Set fleet replicas; scale-down never disrupts live matches
allocate_gameserver
write
Allocate a server for a match; filter and update Counters/Lists at allocation time, stamp match labels/annotations onto the server, or set preferReuse to pack players onto running matches with room first
delete_gameserver
write
Delete a server; refuses Allocated servers unless force=true
update_fleet_image
write
Update a Fleet's container image, triggering Agones's own allocation-aware rolling update
update_fleet_resources
write
Update a Fleet container's CPU/memory requests and limits, triggering the same rolling update
update_fleet_health
write
Update a Fleet's health-check settings (disabled, periodSeconds, failureThreshold, initialDelaySeconds), triggering the same rolling update
update_fleet_env
write
Set or remove environment variables on a Fleet's container, triggering the same rolling update
rollout_status
read
Rolling-update progress: current vs previous GameServerSets, percent complete, and a warning when old-version servers still have live matches blocking completion
create_autoscaler
write
Create a FleetAutoscaler: Buffer policy (keep N Ready servers) or Counter/List policy (scale on aggregate capacity, e.g. total free player slots), with a configurable sync interval
update_autoscaler
write
Update a FleetAutoscaler's buffer size, replica bounds, or sync interval
delete_autoscaler
write
Delete a FleetAutoscaler; the Fleet and its GameServers are unaffected
agones_health
read
Is Agones itself healthy? Controller/allocator/extensions/ping pod readiness and restarts
list_clusters
read
List configured clusters and which one is the default (only meaningful in multi-cluster mode)
open_match_create_ticket
write
Enter a player/party into Open Match matchmaking, returns a ticket ID
open_match_ticket_status
read
Check a ticket: still searching, or matched with a connection assignment
open_match_cancel_ticket
write
Withdraw a ticket from matchmaking
Every tool above except list_clusters also accepts an optional cluster argument (see Multi-cluster). Every write tool except allocate_gameserver accepts dryRun: true for a server-side validation pass that persists nothing, so an agent can show its work before the real call. The three open_match_* tools additionally require Open Match connectivity to be configured (see Open Match) and return a clear error if it isn't.
All 27 tools are exercised against a live Agones cluster (kind + Agones 1.57), not just unit-tested against fakes - and not on the honor system: the same 45-check suite runs in public CI on every push (test/e2e/mcp_e2e.py, e2e.yml), driving the real binary over MCP stdio as a least-privilege ServiceAccount against a fresh kind cluster. Highlights of what it covers, plus one-off deep verifications done during development:
delete_gameserver's safety gate: refusal without force, success with it, and a race test proving the refusal still holds if a server is allocated between the check and the delete.
scale_fleet scale-down/up leaving live allocations untouched, including under a simulated concurrent write (the FleetAutoscaler writes Fleet.Spec.Replicas too).
A real update_fleet_image rollout that rollout_status correctly reported as stalled at 50% while two old-version servers still had live matches.
A full create_fleet → create_autoscaler → update_autoscaler → delete_autoscaler → delete_fleet round trip, including a call deliberately shaped to violate Agones's own admission-webhook rule (minReplicas must be 0 or >= bufferSize) to confirm it's rejected client-side with a clear message instead of a raw webhook error.
update_fleet_resources and update_fleet_health, each called twice in sequence to confirm a partial update (setting only one field) leaves the fields set by the first call untouched - checked against raw kubectl get fleet -o jsonpath, not just the tool's own reported output.
Counters/Lists end to end on a real fleet: create_fleet declaring an initial Counter and List, list_gameservers showing that initial state on both Ready servers, allocate_gameserver applying a Counter increment and a List append at allocation time, then a second allocate_gameserver call with a Counter selector correctly skipping the now-lower-capacity server and picking the other one.
Multi-cluster routing (both the happy path and the unknown-cluster error) against a live server started with AGONES_MCP_CLUSTERS set, including the loud failure on a typo'd AGONES_MCP_CONTEXT.
A full Open Match round trip against a live Open Match deployment: open_match_create_ticket created real tickets, a deployed match function and director matched and assigned them, open_match_ticket_status observed the resulting connection assignment, and open_match_cancel_ticket removed an unmatched ticket (confirmed by a subsequent NotFound on status).
Every read and write tool re-run end to end over MCP stdio under deploy/rbac.yaml exactly as committed, bound to a fresh, otherwise-empty ServiceAccount: the full fleet lifecycle, gameserver_logs included, plus the negative paths (invalid state filter rejected, empty image rejected, log reads of non-GameServer pods refused). Nothing failed for lack of permission, and a matrix check confirmed every verb the role does NOT grant is denied.
Safety model
Every destructive operation is a separate, explicitly-named tool, and the dangerous ones fail closed.
delete_gameserver refuses to delete an Allocated server (live players) unless force=true is passed, and reports the disconnection consequence when forced. Its refusal survives races: a ResourceVersion precondition catches a server that becomes Allocated between the check and the delete.
delete_fleet applies the same live-match refusal, with one honest caveat: the check spans multiple objects, so no single precondition can close its race window completely. An allocation landing in the same instant as the delete can still be disrupted.
scale_fleet relies on Agones scheduling semantics: scale-down removes Ready servers first and never disrupts Allocated ones.
Tool outputs are compact summaries, not raw Kubernetes objects, so agents reason over signal instead of managedFields noise.
namespace is optional (omit for all namespaces) on tools that list multiple resources (list_fleets, list_gameservers, list_autoscalers, fleet_capacity). It's required everywhere else, because every other tool targets one specific named resource. "All namespaces" isn't a meaningful answer to "which Fleet do you mean."
deploy/rbac.yaml grants exactly the verbs the tools use, nothing more. See Permissions.
Counter/List changes only happen through allocate_gameserver's counterActions/listActions, the same allocation-time mechanism Agones's own aggregated allocation API exposes externally. There's deliberately no "set a counter on any running GameServer" tool: a live GameServer's SDK sidecar holds its own in-memory copy of that state and periodically syncs it to Status, so an external patch outside of allocation would race that sync and could be silently overwritten a moment later.
gameserver_logs and gameserver_events return raw text from inside the cluster (container logs, event messages), which an agent reads as part of its context. Attacker-influenced content there could try to steer the agent toward a write call, and no server can reliably tell real log output from injected instructions. What this one does: caps log and event content independently of what was asked for, marks both outputs as untrusted data before returning them, and refuses to read logs of anything that isn't a GameServer. The real boundary is architectural: your MCP host should require approval on every write-tool call (Claude Code does this by default). That approval gate, not this server, is what stops injected content from causing a write.
Requirements
Kubernetes cluster with Agones installed (supported Kubernetes: 1.33-1.35)
kubeconfig with access to Agones resources
Go 1.25+ to install or build
Open Match (optional, only for the open_match_* tools) with a match function and director deployed
go install github.com/nicklesimba/agones-conductor-mcp@latest
The binary lands in $(go env GOPATH)/bin (add it to your PATH if it isn't already). Or build from source:
git clone https://github.com/nicklesimba/agones-conductor-mcp
cd agones-conductor-mcp
go build -o agones-conductor-mcp .
On Windows, build with -o agones-conductor-mcp.exe, and use the full path with escaped backslashes in JSON configs (e.g. "C:\\tools\\agones-conductor-mcp.exe").
Configure
The server authenticates using your kubeconfig (the file kubectl already uses to talk to your cluster(s), normally ~/.kube/config), or in-cluster credentials automatically when deployed inside a cluster. A kubeconfig can define multiple contexts (named cluster+user+namespace combinations); if yours has more than one and kubectl config current-context isn't the right one, set AGONES_MCP_CONTEXT to the context name you want.
Claude Code:
claude mcp add agones -- /path/to/agones-conductor-mcp
Running headless (claude -p, CI, scripts): the client prompts for per-tool approval on first use, and a non-interactive session has no TTY to answer that prompt, so it just hangs. Pass --allowedTools with the specific mcp__agones__* tool names you need.
Multi-cluster
By default the server targets a single cluster (in-cluster config, or the kubeconfig context named by AGONES_MCP_CONTEXT), and tool calls never need a cluster argument. To manage several clusters from one server, set AGONES_MCP_CLUSTERS to a comma-separated list of kubeconfig context names:
The first name listed is the default (override with AGONES_MCP_CONTEXT). Every tool then accepts an optional cluster argument naming one of these contexts; omitting it targets the default, so single-cluster prompts keep working unchanged. Use list_clusters to see what's configured.
Open Match
Skip this section unless you already run Open Match. It's a separate matchmaking system, not something Agones needs. The open_match_* tools are off by default; without configuration they just return a clear "not configured" error.
If you do run it, these tools connect to its Frontend service over gRPC without TLS. The connection is plaintext, matching Open Match's own default in-cluster deployment, so keep the Frontend unexposed to untrusted networks: use in-cluster DNS or a kubectl port-forward rather than exposing it publicly. AGONES_MCP_OPEN_MATCH_FRONTEND needs a host:port this server can actually reach. Concretely, one of:
In-cluster DNS name (e.g. open-match-frontend.open-match.svc.cluster.local:50504) - works if agones-conductor-mcp itself runs as a Pod in the same cluster.
NodePort or LoadBalancer - a Kubernetes Service type that exposes something inside the cluster to the outside; use this if agones-conductor-mcp runs outside the cluster.
A kubectl port-forward you've started yourself, forwarding a local port to the Frontend service - the quickest option for local testing.
Set AGONES_MCP_OPEN_MATCH_FRONTEND to whichever of these applies:
In multi-cluster mode, use AGONES_MCP_OPEN_MATCH_FRONTENDS instead: a comma-separated clusterName=host:port list, matching the names in AGONES_MCP_CLUSTERS. Clusters without an entry simply have Open Match tools disabled for them.
This server doesn't do any matchmaking itself. Open Match's own architecture needs two other pieces to actually turn tickets into matches: a match function (your matchmaking logic - which players belong together) and a director (polls Open Match for proposed matches and finalizes them). Those are things you write and deploy separately, following Open Match's own docs. agones-conductor-mcp only creates, checks, and cancels tickets against whatever pipeline you've already got running - allocate_gameserver has the identical relationship to Agones's own allocator, calling it rather than deciding server placement itself.
Permissions
Don't run this server with broad cluster-admin-style access. RBAC (Role-Based Access Control) is how Kubernetes scopes what an identity is allowed to do, and deploy/rbac.yaml defines the minimal set this server actually needs (see that file's own comments for the exact list). A ClusterRole by itself grants nothing: it's a named bundle of permissions that only takes effect once bound to an identity via a ClusterRoleBinding. If this server runs inside the cluster as a Pod, bind it to that Pod's ServiceAccount; if it runs externally via kubeconfig, apply an equivalent grant to whichever identity that kubeconfig authenticates as.
Concretely, for a ServiceAccount named agones-conductor-mcp in namespace default:
Every tool has been re-run against a real cluster under this exact role, bound to a fresh ServiceAccount with no other access. Nothing needs more than what's granted here, and a permission matrix confirmed the excess verbs (pod reads, secret access, gameserver writes, and more) are denied.
Development
scripts/simulate-churn.sh [fleet] allocates and tears down GameServers on a timer, simulating matches starting and ending, so there's live state to observe while testing tools interactively. Defaults to context kind-agones-dev, namespace default, fleet simple-fleet; override with AGONES_CONTEXT/AGONES_NAMESPACE env vars or a fleet name argument.
Contributing
Issues and PRs welcome. This project aims to be useful to anyone running Agones, regardless of scale or game genre. If a tool here makes an assumption that doesn't fit your setup, that's a bug worth filing.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Agones Conductor?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Agones Conductor precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Agones Conductor usa?
Agones Conductor roda localmente via stdio.
Quando Agones Conductor foi verificado pela última vez?
Última verificação: 2026-10-28. Agones MCP server - an AI assistant conducts your Kubernetes game server fleets, safely