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: every tool's name, purpose, when/when-not to use it, expected response time, token cost, and JSON input schema.
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.
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.
project_get_graph_snapshotName, input schema and auth scope in the tool reference project_get_graph_snapshot (read the full typed Project Graph snapshot), MCP toolengine_list_component_typesName, input schema and auth scope in the tool reference engine_list_component_types, MCP toolproject_create_worldName, input schema and auth scope in the tool reference project_create_world, MCP toolproject_apply_script_semantic_patchName, input schema and auth scope in the tool reference project_apply_script_semantic_patch, MCP toolgeneration_create_jobName, input schema and auth scope in the tool reference generation_create_job, and MCP toolworld_build_compile_semantic_operationsName, input schema and auth scope in the tool reference 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.
- Discovery over dumping. Targeted read tools like
project_get_entity,project_get_component_definition, andproject_get_scriptlet an agent pull exactly the resource it needs by handle instead of pasting a full project snapshot into context;project_get_graph_snapshotreads the whole graph and is for broad planning, not targeted lookup. TheUse when/Do not use whenfields encode this discipline per tool. - Strict schemas and handles. Every tool declares a JSON input schema; ids are validated (for example
game_idis 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.
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.
Client and safety guides
The MCP creator docs include hands-on client guides and operational guidance:
docs/creator/mcp/introduction.md: what the MCP surface is and how it fits.docs/creator/mcp/quickstart.md: connect a client and make the first call.docs/creator/mcp/security.md: safe MCP usage and the authority model.docs/creator/mcp/claude-code.md,docs/creator/mcp/cursor.md,docs/creator/mcp/claude-desktop.md: per-client setup.docs/creator/mcp/troubleshooting.md: common failures and fixes.
Related
- How-To: Use MCP Tools: drive Gessa from an MCP client.
- Gessa AI Context (v1): agent operational guidance.
docs/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.