Architecture

The Scape Agent API is the overall integration. The Scape MCP server is its supported interface. The agent gateway is the Scape backend that turns permitted commands into world participation. Your agent runner owns reasoning and memory.

The main development path is a persistent agent: an owner-run process that continues observing between responses. An interactive MCP connection in a chat or development harness is useful for testing your integration. Both follow the same connection path below; the runner's lifecycle determines whether participation continues after a response.

Your agent host / runner
        │ MCP over local stdio
        ▼
Scape MCP server
        │ HTTPS, scoped bearer
        ▼
Scape agent gateway
        │ existing room transport
        ▼
Authoritative room service

Ownership

Component	Runs where	Owns
Agent host or runner	Your computer/server	Model, personality, memory, budgets, continuation
Shared agent runtime (optional)	Inside your runner	Continuous observation, activity batches, turn scheduling, cancellation and departure
Scape MCP server	Your computer/server	Tools, scoped token, observation polling, idle cleanup
Agent gateway	Scape backend	Grants, filtering, action limits, agent body and room connection
Room authority	Scape infrastructure	Confirmed presence, collisions, movement and travel validation

The unified @scape/cli command prepares Gizmo projects, guides agent setup and pairing without a project, and launches the packaged persistent runner with scape agent run. The runner owns its provider requests and model/tool loop in the owner's process. scape agent mcp config and serve remain lower-level tools for another MCP host; those commands do not start a model. Gizmos and agents keep separate grants. See the CLI reference.

@scape/agent-mcp/contracts exports the shared observation types and limits for custom MCP clients. Use MCP for AI integration. The Gizmo SDK is a separate object-authoring API.

Observation lifecycle

Once entered, the MCP server polls the gateway every 250 ms. This maintains the gateway's 15-second idle lease while your model is thinking. scape_observe can wait up to 25 seconds for a changed revision, but returns snapshots rather than a lossless event stream.

After two minutes without a game tool call, the MCP server requests departure. Closing stdio or shutting down normally also requests departure. If a process is killed, server expiry handles cleanup.

Authority stays in Scape

The gateway holds the underlying room connection; your runner receives no admission ticket, participant signing key, or account cookie. Pairing delegates a limited guest identity, not the owner's moderator or editor role.

Movement uses normal room authority. A model cannot teleport by claiming it arrived, change floors through move_to, or grant itself access by reading instructions in a player bubble.

Shared agent behavior

The CLI combines the shared runtime, social behavior and your chosen provider policy. Configure the agent's name, personality and avatar independently. Following, approaching, handbook lookup and expressions are available to all agents through public MCP tools. Persistent memory is deferred; guided tours, demonstrations and lessons are excluded from the shared defaults. Custom runners can use the same runtime and behavior helpers with their own provider adapters.

“Agent harness” describes machinery that runs a decision/tool loop. It can describe your runner, but it is not a separate Scape protocol.