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 by surface prefix; read the generated reference for the current groups and count. For world-building you mostly touch engine_* and the targeted project_get_* reads (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

1. 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.
   • project_get_entity, project_get_component_definition, project_get_script: read one resource by handle; world_build_get_operation_catalog returns the intent-level world-build operation algebra. Read exactly what you need instead of dumping a full project snapshot into your context window, and use project_get_graph_snapshot only for broad planning. These names are illustrative; confirm them against the generated tool reference.
2. Dry-run, then mutate. Where a dry run is offered (for example world_build_compile_semantic_operations, which previews the lowered operations and diagnostics without mutating), run it before applying. Then call the mutating tool for the surface you need: project_* for graph edits, project_apply_script_semantic_patch for behavior, generation_create_job for assets, world_build_compile_semantic_operations / world_build_from_spatial_asset for prompt-to-world builds.
3. Prove, don't assume. Use qa_capture_observer_frame, qa_capture_renderer_viewport, and simulation_run to produce proof. Backend acceptance and proof receipts are the truth, not local state; missing proof is not_run, not pass.

Prefer canonical surfaces

• Author behavior through Script Semantic Patch (project_apply_script_semantic_patch), never by hand-writing full Script IR. project_create_script only 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

• 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 project_search_entities; for "playable but unproven," go capture the required proof.

Status: stable, v1 MCP usage guide, pinned to engine v1.