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 185 tools, grouped by domain under H2 headings. The current domain groups are: agent, asset, engine, generation, model, project, qa, runtime, script, simulation, spatial, warehouse, workspace, and world. 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): agent_get_project_context agent_get_project_context (compact Project Graph packet for model context), engine_list_component_types engine_list_component_types, project_create_world project_create_world, project_apply_script_semantic_patch project_apply_script_semantic_patch, generation_create_job generation_create_job, and 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.
- Discovery over dumping. Tools like
agent_get_project_contextexist so an agent can fetch a compact, handle-based packet instead of pasting a full project snapshot into context. 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.
Do not paste full project snapshots into context, and do not synthesize write tools from raw endpoint shapes. Call agent_get_project_context for a compact packet and agent_get_tool_contract for the canonical write-tool schemas, then author through semantic operations.
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.