How-To: Use MCP Tools
v1.0.111 · docs-public.v0Drive 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.
This page is verified against the generated MCP tool reference and AI-context docs. Tool availability and schemas are generated from server code.
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, and currently lists 185 tools. Always read 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:
<!-- example:verbatim source=docs/creator/mcp/quickstart.md -->
{
"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.
The MCP credential is validated once, at the resource-server boundary. Gessa derives an internal principal and calls canonical services with it — your MCP bearer token is never forwarded to downstream APIs. Never embed the MCP token in a tool argument, a script, or a request body in the hope of reaching another service; that is not how authority flows here, and it will not work. The token authenticates you to the MCP surface and nothing else.
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.
- Find the workspace. Call
workspace_listto enumerate workspaces, thenproject_list_games(orproject_list_recent_games) to find the game you intend to edit. - Get a compact context packet. Call
agent_get_project_contextfor a small native-agent packet with stable handles and selectors for the current Project Graph. This is the canonical way to orient — do not paste a full project snapshot into context. - Discover the operations and schemas. Use the
engine_*discovery tools to learn the contract surface before writing:engine_list_component_typesandengine_get_component_schemafor ECS components,engine_list_script_nodes/engine_get_script_nodeandengine_list_script_patternsfor behavior, andengine_get_capability_graphfor what the engine exposes. These aremcp:readand cheap. - Mutate through canonical tools. Only now issue mutating calls:
project_set_componentto author a component value,project_apply_script_semantic_patchto author behavior,project_create_entity/project_create_prefabto build structure. Each routes through the same canonical actions the workbench uses. - Re-read to confirm. Call
project_get_entity,project_get_graph_snapshot, oragent_get_project_contextagain. The response you render is a projection of authoritative state — trust the receipt, not your local model of what you sent.
Why discovery-first matters
Call agent_get_project_context (compact, stable handles) instead of dumping a full project snapshot into the model. Use the engine_* read tools to confirm component and node contracts before mutating. Choose the semantic tool that exists for the edit — project_set_component, project_apply_script_semantic_patch — rather than reaching for the low-level transaction path.
The read tools are deliberately cheap (agent_get_project_context is sync <1s, token cost low) 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_set_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.graph.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.
project_apply_transaction is a privileged Project Graph escape hatch, not the normal write path. For component, script, prefab, or entity authoring, use the semantic tool — project_set_component, project_apply_script_semantic_patch, project_apply_smart_asset_package. Choosing the raw path bypasses the typed authoring contract and is the wrong default.
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.