How-To: Use MCP Tools

Drive a Gessa world from an MCP-capable client (a coding agent, an MCP-aware desktop app, or a remote MCP client). The MCP tools are the agent-facing projection over the same backend authority the workbench uses. They are not a side door around it: every mutation routes through the same canonical actions and mutation-authority model as the editor, so an agent that respects this contract produces the same authoritative state a human would.

This page describes the canonical flow for using the tools: connect, discover, mutate through typed authoring tools, then read back receipts. A capability claim is only as strong as the proof or generated reference it links to.

Media placeholder: add a capture of Claude Code or Codex discovering component schemas, applying a semantic script patch, and reading back the authoritative result.

The canonical tool list is generated

The authoritative MCP tool catalog is Tier-2 generated from server/src/modules/mcp/server.ts by scripts/gen-mcp-docs.ts; it declares the tool count and pins it at the top of the file. Always read the count, names, descriptions, and input schemas from the generated reference, never trust a copy, and never infer a tool's shape from an endpoint:

• Generated reference: docs/creator/mcp/tool-reference.md
• Connection quickstart: docs/creator/mcp/quickstart.md
• Security and scopes: docs/creator/mcp/security.md
• Thin pointer page: Reference: MCP Tools

Connect a client

The remote transport is Streamable HTTP at /mcp/rpc; local subprocess clients use @gessa/mcp-server, a thin stdio proxy to that endpoint. The full client configuration lives in the generated quickstart; the shape is:

{
  "mcpServers": {
    "gessa": {
      "command": "npx",
      "args": ["-y", "@gessa/mcp-server"],
      "env": {
        "GESSA_API_KEY": "mcpkey_xxx",
        "GESSA_API_URL": "https://api.gessa.ai"
      }
    }
  }
}

Create the API key in the workspace Settings → MCP panel. Remote clients use https://api.gessa.ai/mcp/rpc and complete the OAuth 2.1 (PKCE S256) authorization flow instead of a stdio key.

Scopes

MCP credentials are scoped. Request the narrowest scope that covers your task:

• mcp:read: read-only tools (discovery, context, inspection).
• mcp:write: mutating creator tools (entities, components, scripts, prefabs).
• mcp:admin: destructive and live-ops tools (deployments, room control, bans).
• mcp:platform: platform-staff operations.

A read-only agent should hold only mcp:read so it physically cannot mutate. See security.

Discovery-first: read before you write

The defining discipline of MCP authoring is read-only discovery first. Establish a small, accurate picture of the world and the available operations before issuing a single mutation. This keeps token cost low, avoids guessing at handles, and means every write is grounded in current authoritative state.

Why discovery-first matters

The targeted read tools are deliberately cheap precisely so an agent can stay grounded between writes. Skipping discovery means guessing at entity handles and component shapes, which produces invalid mutations the authority layer rejects.

Mutating tools route through canonical actions

A mutating MCP tool is a typed front door onto a canonical action. For example, authoring a component value through project_add_component lowers to the action project.entity.component.set; applying a script change through project_apply_script_semantic_patch lowers to project.script.patch.apply. The MCP layer adds strict schemas, stable handles, and idempotency on top of the same authority the editor uses, see Explanation: Backend Authority and the Action Catalog.

There is a privileged low-level escape hatch (project_apply_transaction (action project.transaction.apply)) but it requires a privileged_authoring_reason and exists for import/test paths, not normal authoring. If a semantic tool exists for your edit, use it.

Related

• Reference: MCP Tools: the thin pointer into the generated catalog.
• How-To: Edit Components: the component-authoring recipe these tools serve.
• How-To: Write GessaScript: authoring behavior via the semantic patch.
• Explanation: Backend Authority: why MCP is a projection of one authority, not a bypass.
• Gessa AI Context (v1) and MCP tool-use guidance: operational guidance for agents.

Status: this page documents the canonical MCP authoring flow for v1. The generated tool reference is authoritative for tool names, schemas, and scopes.