--- title: "Reference: MCP Tools" description: "Thin pointer to the generated MCP tool reference, how it is grouped, the contract its tools enforce, and where the client guides live." 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/reference/mcp-tools/ --- # Reference: MCP Tools The Model Context Protocol (MCP) surface is Gessa's agent-facing API: the set of tools an MCP client (Claude Code, Cursor, and others) calls to inspect and build worlds. This page is a **thin pointer**, it tells you where the tool reference lives, how it is organized, and the contract the tools enforce. It does **not** restate the tool tables or schemas. ## Canonical source The tool reference is a **Tier-2 generated artifact**. Read it directly; do not hand-edit it. - [`docs/creator/mcp/tool-reference.md`](../../../creator/mcp/tool-reference.md): every tool's name, purpose, when/when-not to use it, expected response time, token cost, and JSON input schema. {% generated-reference file="docs/creator/mcp/tool-reference.md" label="MCP tool reference" /%} The Tier-1 source of truth is code: the MCP server registry in `server/src/modules/mcp/server.ts`. The reference is produced by the **`scripts/gen-mcp-docs.ts`** generator (run via `npm run gen-docs`) and verified by `npm run gen-docs:check`. The coverage and parity gates `npm run check:mcp-coverage` and `npm run check:mcp-action-catalog-parity` keep the documented tools aligned with what the server actually exposes and with the [Action Catalog](./action-catalog.md). ## What the file contains The reference lists every tool (the count is pinned at the top of the generated file), grouped by domain under `H2` headings named after the tool-name prefix (for example `project`, `engine`, `world`); read the generated file for the current group set. Within each group, every tool has an `H3` entry with: - a one-line **purpose**; - **Use when** and **Do not use when** guidance: the load-bearing part for an agent choosing between tools; - **Expected response time** and **Token cost** hints; - a full JSON **Input schema** (draft-07); - an **Output** note describing the response envelope. Representative tools (verified names from the file): {% mcp-tool name="project_get_graph_snapshot" /%} `project_get_graph_snapshot` (read the full typed Project Graph snapshot), {% mcp-tool name="engine_list_component_types" /%} `engine_list_component_types`, {% mcp-tool name="project_create_world" /%} `project_create_world`, {% mcp-tool name="project_apply_script_semantic_patch" /%} `project_apply_script_semantic_patch`, {% mcp-tool name="generation_create_job" /%} `generation_create_job`, and {% mcp-tool name="world_build_compile_semantic_operations" /%} `world_build_compile_semantic_operations`. For the full inventory and schemas, read the generated file. ## The contract the MCP surface enforces The MCP surface is the **agent-facing projection over the same backend authority** the workbench uses, not a bypass of it. Several invariants follow: - **Write tools lower into the Action Catalog.** A tool that mutates state ultimately invokes a catalog verb (for example a world or component action), so MCP writes inherit the same authority, validation, exposure, and audit guarantees as every other surface. See [Reference: Action Catalog](./action-catalog.md). - **Discovery over dumping.** Targeted read tools like `project_get_entity`, `project_get_component_definition`, and `project_get_script` let an agent pull exactly the resource it needs by handle instead of pasting a full project snapshot into context; `project_get_graph_snapshot` reads the whole graph and is for broad planning, not targeted lookup. The `Use when` / `Do not use when` fields encode this discipline per tool. - **Strict schemas and handles.** Every tool declares a JSON input schema; ids are validated (for example `game_id` is a UUID with a strict pattern). Authoring is done against stable handles and selectors rather than raw graph offsets. - **Semantic authoring, not raw IR.** Behavior is authored through semantic operations and script semantic patches (for example `project_apply_script_semantic_patch`) that lower into Gessa services, rather than by emitting raw Project Graph transactions or full Script IR. {% ai-context audience="mcp" priority="avoid" %} Do not paste full project snapshots into context, and do not synthesize write tools from raw endpoint shapes. Read exactly the resources you need through the targeted `project_get_*` tools (for example `project_get_entity`, `project_get_component_definition`), read the generated tool reference for the canonical write-tool schemas, then author through semantic operations. {% /ai-context %} ## Version pinning The reference header records the **tool count** and names its Tier-1 source (`server/src/modules/mcp/server.ts`), and the gates above keep it in lockstep with the executable registry. Because the MCP write tools project the Action Catalog, the catalog's version coordinates and hash pin the semantics of those writes; see [Versioning Policy](../explanation/versioning-policy.md). ## Client and safety guides The MCP creator docs include hands-on client guides and operational guidance: - [`docs/creator/mcp/introduction.md`](../../../creator/mcp/introduction.md): what the MCP surface is and how it fits. - [`docs/creator/mcp/quickstart.md`](../../../creator/mcp/quickstart.md): connect a client and make the first call. - [`docs/creator/mcp/security.md`](../../../creator/mcp/security.md): safe MCP usage and the authority model. - [`docs/creator/mcp/claude-code.md`](../../../creator/mcp/claude-code.md), [`docs/creator/mcp/cursor.md`](../../../creator/mcp/cursor.md), [`docs/creator/mcp/claude-desktop.md`](../../../creator/mcp/claude-desktop.md): per-client setup. - [`docs/creator/mcp/troubleshooting.md`](../../../creator/mcp/troubleshooting.md): common failures and fixes. ## Related - [How-To: Use MCP Tools](../how-to/use-mcp-tools.md): drive Gessa from an MCP client. - [Gessa AI Context (v1)](../../../ai-context/v1/README.md): agent operational guidance. - [`docs/ai-context/v1/mcp-tool-use.md`](../../../ai-context/v1/mcp-tool-use.md): generic MCP-client orientation. Status: stable orientation page. The tool reference itself is generated; trust the generated file over any prose here.