---
title: "How-To: Use MCP Tools"
description: "Task recipe for driving Gessa from an MCP client, connect, discover read-only, then mutate through canonical tools."
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/how-to/use-mcp-tools/
---

# How-To: Use MCP Tools

{% version engineVersion="v1.0.232" coordinate="docs-public.v0" /%}

Drive a Gessa world from an MCP-capable client (a coding agent, an MCP-aware desktop app, or a remote MCP client). The MCP tools are the agent-facing projection over the **same backend authority** the workbench uses. They are not a side door around it: every mutation routes through the same canonical actions and mutation-authority model as the editor, so an agent that respects this contract produces the same authoritative state a human would.

This page describes the **canonical flow** for using the tools: connect, discover, mutate through typed authoring tools, then read back receipts. A capability claim is only as strong as the proof or generated reference it links to.

{% proof class="docs.mcp" registry="docs/cycles/v1-engine-readiness-loop/PROOF_REGISTRY.json" status="pending" %}
This page is verified against the generated MCP tool reference and AI-context docs. Tool availability and schemas are generated from server code.
{% /proof %}

> Media placeholder: add a capture of Claude Code or Codex discovering component schemas, applying a semantic script patch, and reading back the authoritative result.

## The canonical tool list is generated

The authoritative MCP tool catalog is **Tier-2 generated** from `server/src/modules/mcp/server.ts` by `scripts/gen-mcp-docs.ts`; it declares the tool count and pins it at the top of the file. Always read the count, names, descriptions, and input schemas from the generated reference, never trust a copy, and never infer a tool's shape from an endpoint:

- Generated reference: [`docs/creator/mcp/tool-reference.md`](../../../creator/mcp/tool-reference.md)
- Connection quickstart: [`docs/creator/mcp/quickstart.md`](../../../creator/mcp/quickstart.md)
- Security and scopes: [`docs/creator/mcp/security.md`](../../../creator/mcp/security.md)
- Thin pointer page: [Reference: MCP Tools](../reference/mcp-tools.md)

{% generated-reference file="docs/creator/mcp/tool-reference.md" label="MCP tool reference" /%}

## Connect a client

The remote transport is Streamable HTTP at `/mcp/rpc`; local subprocess clients use `@gessa/mcp-server`, a thin stdio proxy to that endpoint. The full client configuration lives in the generated [quickstart](../../../creator/mcp/quickstart.md); the shape is:

<!-- example:verbatim source=docs/creator/mcp/quickstart.md -->

```json
{
  "mcpServers": {
    "gessa": {
      "command": "npx",
      "args": ["-y", "@gessa/mcp-server"],
      "env": {
        "GESSA_API_KEY": "mcpkey_xxx",
        "GESSA_API_URL": "https://api.gessa.ai"
      }
    }
  }
}
```

Create the API key in the workspace **Settings → MCP** panel. Remote clients use `https://api.gessa.ai/mcp/rpc` and complete the OAuth 2.1 (PKCE S256) authorization flow instead of a stdio key.

## Scopes

MCP credentials are scoped. Request the narrowest scope that covers your task:

- `mcp:read`: read-only tools (discovery, context, inspection).
- `mcp:write`: mutating creator tools (entities, components, scripts, prefabs).
- `mcp:admin`: destructive and live-ops tools (deployments, room control, bans).
- `mcp:platform`: platform-staff operations.

A read-only agent should hold only `mcp:read` so it physically cannot mutate. See [security](../../../creator/mcp/security.md).

{% warning severity="critical" title="MCP bearer tokens are never forwarded downstream" %}
The MCP credential is validated **once**, at the resource-server boundary. Gessa derives an internal principal and calls canonical services with it, your MCP bearer token is **never** forwarded to downstream APIs. Never embed the MCP token in a tool argument, a script, or a request body in the hope of reaching another service; that is not how authority flows here, and it will not work. The token authenticates you to the MCP surface and nothing else.
{% /warning %}

## Discovery-first: read before you write

The defining discipline of MCP authoring is **read-only discovery first**. Establish a small, accurate picture of the world and the available operations before issuing a single mutation. This keeps token cost low, avoids guessing at handles, and means every write is grounded in current authoritative state.

{% recipe id="mcp-discovery-first" goal="Discover the world and the operations, then mutate through canonical tools" audience="both" %}

1. **Find the workspace.** Call `workspace_list` to enumerate workspaces, then `project_list_games` (or `project_list_recent_games`) to find the game you intend to edit.
2. **Read what you need, narrowly.** There is no compact context-packet tool; pull exactly the resources you need, by stable handle, with the targeted reads `project_get_entity`, `project_get_component_definition`, `project_get_script`, and `project_get_world`. Reach for `project_get_graph_snapshot` only for broad planning; it reads the whole graph and is not for targeted lookup. *Do not* paste a full project snapshot into context.
3. **Discover the operations and schemas.** Use the `engine_*` discovery tools to learn the contract surface before writing: `engine_list_component_types` and `engine_get_component_schema` for ECS components, `engine_list_script_nodes` / `engine_get_script_node` and `engine_list_script_patterns` for behavior, and `engine_get_capability_graph` for what the engine exposes. These are `mcp:read` and cheap.
4. **Mutate through canonical tools.** Only now issue mutating calls: `project_add_component` to author a component value, `project_apply_script_semantic_patch` to author behavior, `project_create_entity` / `project_create_prefab` to build structure. Each routes through the same canonical actions the workbench uses.
5. **Re-read to confirm.** Call `project_get_entity` or `project_get_graph_snapshot` again. The response you render is a **projection** of authoritative state: trust the receipt, not your local model of what you sent.

{% /recipe %}

### Why discovery-first matters

{% ai-context audience="mcp" priority="must" %}
Read narrowly with the targeted `project_get_*` tools (stable handles) instead of dumping a full project snapshot into the model. Use the `engine_*` read tools to confirm component and node contracts *before* mutating. Choose the semantic tool that exists for the edit (`project_add_component`, `project_apply_script_semantic_patch`) rather than reaching for the low-level transaction path.
{% /ai-context %}

The targeted read tools are deliberately cheap precisely so an agent can stay grounded between writes. Skipping discovery means guessing at entity handles and component shapes, which produces invalid mutations the authority layer rejects.

## Mutating tools route through canonical actions

A mutating MCP tool is a typed front door onto a canonical action. For example, authoring a component value through `project_add_component` lowers to the action `project.entity.component.set`; applying a script change through `project_apply_script_semantic_patch` lowers to `project.script.patch.apply`. The MCP layer adds strict schemas, stable handles, and idempotency on top of the same authority the editor uses, see [Explanation: Backend Authority](../explanation/backend-authority.md) and the [Action Catalog](../reference/action-catalog.md).

There is a privileged low-level escape hatch (`project_apply_transaction` (action `project.transaction.apply`)) but it requires a `privileged_authoring_reason` and exists for import/test paths, not normal authoring. If a semantic tool exists for your edit, use it.

{% warning severity="caution" title="Do not reach for the raw transaction path" %}
`project_apply_transaction` is a privileged Project Graph escape hatch, not the normal write path. For component, script, prefab, or entity authoring, use the semantic tool: `project_add_component`, `project_apply_script_semantic_patch`, `project_apply_smart_asset_package`. Choosing the raw path bypasses the typed authoring contract and is the wrong default.
{% /warning %}

## Related

- [Reference: MCP Tools](../reference/mcp-tools.md): the thin pointer into the generated catalog.
- [How-To: Edit Components](edit-components.md): the component-authoring recipe these tools serve.
- [How-To: Write GessaScript](write-gessascript.md): authoring behavior via the semantic patch.
- [Explanation: Backend Authority](../explanation/backend-authority.md): why MCP is a projection of one authority, not a bypass.
- [Gessa AI Context (v1)](../../../ai-context/v1/README.md) and [MCP tool-use guidance](../../../ai-context/v1/mcp-tool-use.md): operational guidance for agents.

Status: this page documents the canonical MCP authoring flow for v1. The generated tool reference is authoritative for tool names, schemas, and scopes.