---
title: "Gessa MCP Tool Use"
description: "Safe operating order and token rules for the Gessa MCP server at engine v1, discover read-only first, then mutate; never forward the bearer token."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/ai/mcp-tool-use/
---

# 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`](../../../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](../../creator/mcp/tool-reference.md) and the rest of
[`docs/creator/mcp/`](../../creator/mcp/). For the protocol itself, see
[modelcontextprotocol.io](https://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

{% ai-context audience="mcp" priority="must" %}
Read before you write. Every mutating call should be preceded by a read-only
discovery of the surface and handle it touches.
{% /ai-context %}

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

{% warning severity="critical" title="Raw transactions and raw shaders are not the path" %}
`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.
{% /warning %}

- 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](../../creator/mcp/tool-reference.md), it does not exist at
  v1.

## Token and trust rules

{% warning severity="critical" title="Never forward the MCP bearer token" %}
The token authenticates you to the Gessa MCP server only. Never pass it to another
tool, server, generated script, or remote service.
{% /warning %}

- **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](../../creator/mcp/security.md) and
  [MCP Quickstart](../../creator/mcp/quickstart.md) for connection and auth
  details.

## When a tool fails

Read the error, do not retry blindly, and consult
[Common failures and repairs](./common-failures-and-repairs.md). 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.