Multiplayer Agent

Mint a new game (publishable key) under your studio (secret key). Returns its publishableKey + wsEndpoint. Point a client at the new key, or scope this MCP to it by passing the x-mp-game header.

{
  "type": "object",
  "properties": {
    "label": {
      "description": "A human label for the game, e.g. 'N0RT arena'.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the games (publishable keys) under your studio, with labels and per-game settings. Marks which game is `primary` (the one unnamed calls fall back to) and which one this connection is currently pointed at.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Set a human-readable name for a game (the `game` argument, else the x-mp-game header, else your only game). The name shows in your dashboard: call this when you start building so the game isn't unnamed. Refuses to guess when the studio has several games and none was named.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Display name, e.g. 'N0RT Arena'."
    },
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create or replace the spec for a room (validation/types/defaults). Returns connection info. Omit fields entirely for a fully schemaless room.

{
  "type": "object",
  "properties": {
    "roomName": {
      "type": "string",
      "description": "Unique room name under your key, e.g. 'dots-arena'."
    },
    "spec": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "maxClients": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "entities": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "object",
            "properties": {
              "keyedBy": {
                "type": "string",
                "const": "sessionId"
              },
              "fields": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "anyOf": [
                    {
                      "type": "string",
                      "enum": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "string",
                            "number",
                            "boolean"
                          ]
                        },
                        "default": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "number"
                            },
                            {
                              "type": "boolean"
                            }
                          ]
                        }
                      },
                      "required": [
                        "type"
                      ]
                    }
                  ]
                }
              }
            },
            "required": [
              "fields"
            ]
          }
        },
        "shared": {
          "type": "object",
          "properties": {
            "fields": {
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "string",
                      "number",
                      "boolean"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "string",
                          "number",
                          "boolean"
                        ]
                      },
                      "default": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          },
                          {
                            "type": "boolean"
                          }
                        ]
                      }
                    },
                    "required": [
                      "type"
                    ]
                  }
                ]
              }
            }
          },
          "required": [
            "fields"
          ]
        }
      },
      "required": [
        "name"
      ],
      "description": "The room schema: name, optional maxClients, entities.players.fields, shared.fields."
    },
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "required": [
    "roomName",
    "spec"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns { wsEndpoint, roomName, publishableKey, adsPublisherId } for wiring a client. adsPublisherId is your BYO Google Ads id (embed it if set). Check the returned `target` names the game you meant before shipping the key.

{
  "type": "object",
  "properties": {
    "roomName": {
      "type": "string",
      "description": "The room name."
    },
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "required": [
    "roomName"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns a complete single-file HTML game wired to this room: realtime movement plus an anonymous (claimable) player, a saved color (datastore), and a click leaderboard. Write it to disk and open it. The game it is wired to is stamped in a comment at the top of the file.

{
  "type": "object",
  "properties": {
    "roomName": {
      "type": "string",
      "description": "The room name."
    },
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "required": [
    "roomName"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read a game's live ops: `now` (what players see right now: the merged config plus active and upcoming events), the base config, every scheduled event with its status (active / upcoming / ended), the highlight webhook (masked) and the 20 latest highlights with how each was delivered. Pass `at` to preview another instant (e.g. the middle of a weekend event) and `room` to see one room's view. Use it to verify every change you make.

{
  "type": "object",
  "properties": {
    "at": {
      "description": "ISO-8601 instant to preview (default now).",
      "type": "string"
    },
    "room": {
      "description": "Resolve for this room (events limited to other rooms drop out). Default: game-wide.",
      "type": "string"
    },
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Set the game's live config: any JSON the game reads at runtime (drop rates, prices, difficulty, a banner, feature switches). It reaches rooms that are already running within ~15 seconds, with no redeploy and nobody disconnected; clients read it as mp.live.config, server logic as liveOps().config. Merges by default (a null value deletes a key); replace: true swaps the whole object. Active events' overrides apply on top. Max 8KB.

{
  "type": "object",
  "properties": {
    "config": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "JSON object to merge (or, with replace, to store)."
    },
    "replace": {
      "description": "Replace the whole config instead of merging (default false).",
      "type": "boolean"
    },
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "required": [
    "config"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Schedule (or, with an existing id, edit) a timed event: a window, optionally repeating daily or weekly, optionally limited to some rooms, carrying config overrides that apply only while it runs. It starts and ends on time in rooms that are already running, as data: nobody is kicked and nothing is redeployed. Clients see it in mp.live (active / upcoming / config) and mp.onLive(cb); server logic reads liveOps() and gets onLiveOps(live, change) when it starts or ends. Up to 50 events per game; check the result with get_live_ops (pass `at` to preview).

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Player-facing name, e.g. 'Double XP Weekend'."
    },
    "id": {
      "description": "Stable id (a-z, 0-9, - _). Defaults to a slug of the title. Scheduling an existing id EDITS that event.",
      "type": "string",
      "maxLength": 48
    },
    "description": {
      "description": "Player-facing blurb for an events window.",
      "type": "string",
      "maxLength": 500
    },
    "startsAt": {
      "description": "ISO-8601 start, e.g. \"2026-11-01T18:00:00Z\", or \"now\" (the default).",
      "type": "string"
    },
    "endsAt": {
      "description": "ISO-8601 end. Or give durationMinutes. Neither = open-ended (until cancelled; not for repeating events).",
      "type": "string"
    },
    "durationMinutes": {
      "description": "Length of each occurrence, instead of endsAt.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "repeat": {
      "description": "Repeat the same window every day or week from startsAt (default none).",
      "type": "string",
      "enum": [
        "none",
        "daily",
        "weekly"
      ]
    },
    "repeatUntil": {
      "description": "ISO-8601: no occurrence starts at or after this. Omit = repeats forever.",
      "type": "string"
    },
    "rooms": {
      "description": "Only these room names. Omit = every room of the game.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "config": {
      "description": "Overrides deep-merged over the live config while the event runs (null deletes a key), e.g. { xpMultiplier: 2, rules: { lives: 1 } }.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "required": [
    "title"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete a scheduled event. If it is running, it ends in running rooms within ~15 seconds (its config overrides drop away; server logic gets onLiveOps with it in change.ended). To end it early but keep it listed, schedule the same id again with endsAt set to the current time.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The event id (see get_live_ops)."
    },
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the full SDK reference (markdown) wired to ONE game's key/endpoints: realtime rooms, player identity (anonymous + claim/login), the datastore (saves/stats/inventory), leaderboards, player-created content (level sharing / UGC), durable shared MATCHES for asynchronous turn-based play, and live ops (live config, scheduled events, highlights). Read this before writing client code that uses logins, saved progress, leaderboards, shared player-made content, or any game a player closes and comes back to. Pass `game` when the studio has more than one: every snippet carries that game's publishable key inline, and shipping the wrong one silently pools your players into another game.

{
  "type": "object",
  "properties": {
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Host the game's files at a public share link, https://<slug>.play.multiplayeragent.com/ (the game's own origin; the slug comes from the game's name and never changes). Send every file the game needs: an index.html at the root plus any JS/CSS/assets, paths relative to it. Text goes as utf8 content; images, audio and other binaries as base64 with encoding: "base64". The files must use THIS game's publishable key (it is how the server knows the build belongs to this game; a client wired to another game is refused). Re-run after every change: it replaces the hosted files and the link stays the same. Limits: 100 files, 5 MB in total. Give the user the url: anyone who opens it joins the same rooms. Nothing is listed publicly; only people with the link find it.

{
  "type": "object",
  "properties": {
    "files": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path relative to the game root, e.g. 'index.html' or 'assets/ship.png'."
          },
          "content": {
            "type": "string",
            "description": "The file's content: the text itself, or base64 when encoding is 'base64'."
          },
          "encoding": {
            "description": "'utf8' (default) for text files; 'base64' for binaries.",
            "type": "string",
            "enum": [
              "utf8",
              "base64"
            ]
          }
        },
        "required": [
          "path",
          "content"
        ]
      },
      "description": "Every file of the game, including index.html."
    },
    "game": {
      "description": "Which game to act on: its publishable key (pk_…) or its exact name. Defaults to the x-mp-game header, then your primary game.",
      "type": "string"
    }
  },
  "required": [
    "files"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the starter games: ready-made multiplayer games (many built in Multiplayer Agent's videos) to begin from with remix_game. Each shows its slug, title, summary, the video it came from, whether it's premium, and whether THIS studio has it unlocked (free starters: everyone; premium: a paid plan).

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Start from a starter game (see list_starters): makes a NEW game in this studio (or, with `game`, reuses one of yours) and returns a link to the starter's source as a ZIP, valid for 5 minutes, plus the steps to unpack it, rewire it to the new game's publishable key, and publish it. Premium starters need a paid plan; a locked one returns the upgrade link instead, and nothing is created.

{
  "type": "object",
  "properties": {
    "starter": {
      "type": "string",
      "description": "The starter's slug, from list_starters, e.g. 'slither-arena'."
    },
    "label": {
      "description": "A name for the new game. Defaults to the starter's title.",
      "type": "string",
      "maxLength": 100
    },
    "game": {
      "description": "Reuse one of your games instead of making a new one (its pk_ or exact name): e.g. to fetch a fresh link after one expired.",
      "type": "string"
    }
  },
  "required": [
    "starter"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Connect this keyless session to the user's own account, the way `gh auth login` works. Ask for their email first and pass it (it prefills the page). Returns a one-time url and a code: open the url in their browser yourself and tell them the code. They sign up or log in ON THE PAGE (never ask for a password in chat), check the code matches, and press Connect. From then on this session acts as their account and the games built so far move in. The link lasts 10 minutes.

{
  "type": "object",
  "properties": {
    "email": {
      "description": "The user's email, to prefill the sign-in page.",
      "type": "string",
      "maxLength": 254
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

This connection has no account: it builds into an unclaimed studio. Returns the claim link to give the user (a free sign-up or log-in that moves the studio's games into their own account), when the studio expires, and whether it has been claimed already. connect_account is the better way to keep the games when the user is here (this session then keeps working as their account); the claim link is for later, or for someone else.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}