Gessa MCP Tool Use
How to use the Gessa Model Context Protocol (MCP) server safely at engine version v1. Gessa exposes its engine surface as MCP tools from server/src/modules/mcp/server.ts. The source of truth for tool names, input schemas, and usage notes is the generated reference, not this page — see the MCP Tool Reference and the rest of docs/creator/mcp/. For the protocol itself, see modelcontextprotocol.io.
This page gives you the safe operating order, the surface map, and the token rules. It deliberately names only a few illustrative tools; do not treat any list here as complete or canonical — confirm every name against the generated reference before you call it.
The surfaces
The MCP reference groups its tools (185 at the current snapshot) by surface: agent, asset, engine, generation, model, project, qa, runtime, script, simulation, spatial, warehouse, workspace, world. For world-building you mostly touch agent_* and engine_* (discovery), project_* (graph edits and behavior), generation_* and spatial_* (assets), world_build_* (whole-world builds), and qa_* / simulation_* (proof). The project surface is by far the largest; the others are narrow and purpose-specific.
Safe operating order
Read before you write. Every mutating call should be preceded by a read-only discovery of the surface and handle it touches.
- Read-only discovery first. Orient before you mutate. Discovery tools are side-effect-free and let you learn the live v1 contract:
workspace_list— enumerate workspaces you can reach.engine_get_engine_spec,engine_list_component_types,engine_get_capability_graph— the engine contract surface.agent_get_project_context,agent_get_semantic_operation_catalog— project handles and the operation algebra. Preferagent_get_project_contextover dumping a full project snapshot into your context window. These names are illustrative; confirm them against the generated tool reference.
- Preflight, then mutate. Where a preflight is offered (for example
agent_preflight_semantic_operations), run it before applying. Then call the mutating tool for the surface you need —project_*for graph edits,project_apply_script_semantic_patchfor behavior,generation_create_jobfor assets,world_build_compile_semantic_operations/world_build_from_spatial_assetfor prompt-to-world builds. - Prove, don't assume. Use
qa_capture_observer_frame,qa_capture_renderer_viewport, andsimulation_runto produce proof. Backend acceptance and proof receipts are the truth, not local state; missing proof isnot_run, not pass.
Prefer canonical surfaces
project_apply_transaction is a low-level escape hatch, not the normal authoring path, and raw renderer fields (shaderSource, fragmentShader, wgsl, glsl, customPassSource) are rejected by the build contract. Route graph edits through cataloged project.* actions and renderer choices through cataloged capability ids.
- Author behavior through Script Semantic Patch (
project_apply_script_semantic_patch), never by hand-writing full Script IR.project_create_scriptonly creates an empty IR shell. - Make graph changes through cataloged
project.*actions, not raw transactions. - Reference cataloged renderer/material capability ids; never send raw shader/pass source.
- Do not invent tool names. If a tool is not in the MCP Tool Reference, it does not exist at v1.
Token and trust rules
The token authenticates you to the Gessa MCP server only. Never pass it to another tool, server, generated script, or remote service.
- Treat the engine's acceptance as authoritative, not the MCP client UI. The frontend is a non-authoritative projection over backend authority.
- Scope your access. Use the narrowest workspace/project handle the task needs, discovered via read-only tools, before mutating.
- See MCP Security and MCP Quickstart for connection and auth details.
When a tool fails
Read the error, do not retry blindly, and consult Common failures and repairs. For raw-graph rejections, route through the canonical action; for an unauthorized or out-of-scope call, re-discover the correct handle with workspace_list and agent_get_project_context; for "playable but unproven," go capture the required proof.
Status: stable — v1 MCP usage guide, pinned to engine v1.