had3d MCP docs
Worldly for agents

Build a world
with a conversation.

Worldly MCP connects an AI partner to your projects and scenes. It can inspect a scene, enter the editor as a named collaborator, and move its camera in realtime.

Get started → Explore the tools ↓
01

Your project access

The connection sees the same projects and scenes your Worldly account can open.

02

Collaborative by default

Each agent is a distinct peer with a visible camera, colour, and name tag.

03

Scoped authoring

Read and presence grants stay limited. Explicit authoring scopes unlock project creation and transactional generation.

Start here

Connect an MCP client

Add an endpoint to a remote-MCP client. The client opens Worldly in your browser, where you sign in and approve its read and presence permissions.

Hosted endpoint

Use https://mcp.had3d.app/mcp. Authentication is discovered by the client and completed through the Worldly editor; no API key is copied into a prompt.

Developer preview

Connect in three steps

  1. 1
    Add the server

    Enter https://mcp.had3d.app/mcp in a client that supports remote MCP.

  2. 2
    Approve access

    Sign in at the Worldly editor and review the requested read, presence, and optional authoring scopes.

  3. 3
    Connect a partner

    Choose a name—or use Agent—then enter a scene and move its camera.

VS Code

VS Code ships a full MCP client with OAuth support, so a workspace mcp.json is the whole setup. Add this file, trust the workspace, and Worldly’s tools appear in Copilot Chat.

Workspace file — .vscode/mcp.json (VS Code format):

{
  "servers": {
    "worldly": {
      "type": "http",
      "url": "https://mcp.had3d.app/mcp"
    }
  }
}

For a portable config that other MCP-aware tools also read, use .mcp.json at the project root with a top-level mcpServers object instead. On first connection VS Code opens the Worldly editor in your browser, where you sign in and approve the requested scopes; no API key is stored in the file. With the stack running locally, use http://localhost:8799/mcp and the local editor instead.

Architecture

Agents are collaborators,
not a second write path.

MCP uses Worldly membership data and the existing per-project room. Scene reads come from the same stored document the editor opens, while camera presence is broadcast through the same peer channel used by people.

Why this matters

A city generated by an agent uses the same validation, conflict handling, run attribution, and undo stack as a city generated from the editor.

Developer preview

Tool catalog

61 tools

Inspect scenes, connect a visible partner, or create a game through generation scripts. Authoring checks OAuth scopes, project roles, generator schemas, and scene versions.

Authoring5
list_generators

Read the available generator schemas, including characters.create.

create_project

Create an owned project and its first scene with worldly:projects:write.

create_scene

Create another scene with worldly:scenes:write and an editor or owner role.

save_generation_script

Save one script at an expected scene version with worldly:scenes:write.

run_generation_script

Run a saved script without an open editor. Requires worldly:scripts:run and worldly:scenes:write; commits only a validated result at the expected version.

Games15
create_scope

Create a game: one save across many worlds. Optionally put a project that is in no game yet into it. Requires worldly:projects:write.

add_world

Add a world key before its scene exists, as planned, so travel can name it. Requires worldly:projects:write and the editor role.

set_world_access

Set planned, private, coming_soon, live or closed, with a note and an opening date. Never republishes. Requires worldly:projects:write and the owner role.

publish_scope

Run the game’s scope script and publish its document, with the compatibility report. A breaking change is a new scope, which means fresh saves, and is refused. Also requires worldly:scripts:run.

publish_scene

Publish a project’s saved scene as a new version of its world and return the version and play URL. Never changes access. Requires worldly:projects:write, the editor role and a verified email address.

attach_world_project

Build a planned world in a project that is in no game yet, so its first publish lands on that world. Requires worldly:projects:write and the owner role.

list_scopes

Every game you can see, with your role and its universe membership. Requires worldly:read.

get_scope

One game’s worlds, access, play URLs, projects and published scope version; full adds the saved script and published document. Requires worldly:read.

travel_map

How the game’s worlds connect: travel out and entries in, dead ends, unreachable worlds, and links whose destination or entry is missing. Requires worldly:read.

scope_numbers

Players, returning players and play time per world. Requires worldly:read.

rename_scope

Change the name players see. Requires worldly:projects:write and the owner role.

delete_scope

Delete a game that has published nothing and is in no universe; its projects stay. Requires worldly:projects:write and owning the game.

list_testersadd_testerremove_tester

Who may enter the game’s private worlds besides its members. Requires the owner role; adding and removing also require worldly:projects:write.

Universes12
create_universe

Create a universe: a set of games that agree to let players carry value between them. You become its steward. Requires worldly:projects:write.

publish_charter

Run a charter script (must call universe.charter exactly once) and publish the document it declares: tier rates and needs, headroom, idle income, the border and exchange sinks, what may cross, and import defaults. expectedVersion defaults to the current charter version. Requires worldly:projects:write, worldly:scripts:run and being the steward.

apply_to_universe

Apply one of your games to join a universe. Auto-approved when you are the steward; otherwise the steward reviews it. Requires worldly:projects:write and being the game’s publisher.

approve_universe_member

Activate a game that applied, after core re-checks it against the current charter. Requires worldly:projects:write and being the steward.

list_universes

The universes you steward, with their ids. Requires worldly:read.

get_universe

Any universe and its latest charter, to read before declaring universe.join. Requires worldly:read.

suspend_universe_member

Stop crossings into and out of a member game until it is approved again. Requires worldly:projects:write and being the steward.

leave_universe

Take your game out of its universe. Requires worldly:projects:write and being the game’s publisher.

resume_universe_exports

Undo the kill switch once the steward has reviewed the anomaly. Requires worldly:projects:write and being the steward.

universe_report

The validator report for one game’s live worlds against its universe charter: every task’s tier, which needs are met, and issues like tier_unmet and no_time_bound, so an agent can fix what it names. Requires worldly:read.

quote_crossing

Customs without a player: price holdings in one member game carried into another, against both games’ latest published documents and the latest charter. Requires worldly:read.

universe_overview

The steward’s dashboard: the charter, every member and its status, and crossing totals in, out and overall. Requires worldly:projects:write and being the steward.

Publishing3
list_publishes

Every published version, which one is live, and whether any is held for review. Requires worldly:read.

rollback_publish

Make an earlier version live again. Requires worldly:projects:write, the editor role and a verified email address.

take_world_offline

Stop the address serving anything; nothing is deleted. Requires worldly:projects:write and the editor role.

Project settings7
update_project

Rename a project, or change its description or slug. Requires worldly:projects:write and the owner role.

delete_project

Delete a project for good. Requires worldly:projects:write and being its owner.

update_scenedelete_scene

Rename, reorder or delete a scene; a project keeps at least one. Requires worldly:scenes:write.

get_scene_screenshot

The editor’s last picture of a scene, as an image. Requires worldly:read.

list_assetsupload_asset

The project’s files, and adding one from base64 or a public URL (images, models, audio; 25 MB). Uploading requires worldly:scenes:write.

People5
list_members

Members, their roles, and for an owner the pending invitations. Requires worldly:read.

invite_memberrevoke_invite

Email an invitation to edit or view, or withdraw one. Requires worldly:projects:write, the owner role and a verified email address.

set_member_roleremove_member

Change a member’s role, remove them, or leave yourself. Requires worldly:projects:write.

Arcade6
get_arcade

Your arcade: its games, featuring, visibility, theme and invitations. Requires worldly:read.

update_arcade

Rename it, or set its visibility or theme. Requires worldly:projects:write.

set_arcade_entryremove_arcade_entry

List, feature, pin or unlist one of your games. Requires worldly:projects:write.

invite_to_arcadeuninvite_from_arcade

Get the arcade’s link, or name or un-name an invited account. Requires worldly:projects:write.

Project access5
list_projects

List every project the connected account can access.

list_scenes

List the scenes in one project.

inspect_scene

Read scene structure with paged entities.

map_scene

A compact spatial summary: boxes for solids, triggers and spawns, travel gates and entries, paths and areas as simplified lines, every action at the point it is done, and a top-down character grid. A few kilobytes for a city.

review_gameplay

Check that what a scene tells the player matches what its quest objectives and logic rules actually do, and that stated odds, prices and currencies match the game’s drop tables, shops and currencies. Advisory; read claims to tell “all agreed” from “nothing to check”.

Editor presence3
connect_agent

Enter a scene with an optional name, defaulting to Agent.

move_camera

Move its position, look target, and lens in realtime.

disconnect_agent

Remove it from the project room immediately.

Shared editor

A partner you can see.

Connecting an agent publishes a synthetic camera through the project room. Every editor on that scene sees the same frustum and name tag update.

Visible presence “Scout is looking here”
  • Distinct agent identity
  • Realtime camera updates
  • Scene-specific name tag
Not exposed Scene mutations
  • No raw entity writes
  • No whole-document overwrite
  • No bypass around project membership
Next phase

Scene editing comes
through collaboration.

Generator and scene-editing tools are intentionally not exposed in the first phase. They will arrive after collaborative operations can attribute, validate, and undo an agent change through the project room.

generator.ts

const cityGrid = {
  id: "roads.cityGrid",
  description: "Create a seeded city road network…",
  params: z.object({
    seed: z.number(),
    blockSize: z.number().default(120),
  }),
  run(params, context) { /* emit entities */ },
};

registry.registerGenerator(cityGrid);
Example

Tool schema

Tools have stable names, descriptions written for a client that may not see the viewport, and strict JSON Schema inputs.

tools/list

{
  "name": "move_camera",
  "description": "Move a connected agent camera…",
  "inputSchema": {
    "type": "object",
    "properties": {
      "position": { "type": "array", "minItems": 3 },
      "target": { "type": "array", "minItems": 3 }
    },
    "required": ["position", "target"]
  }
}
defaults

Up and lens have useful editor defaults.

vectors

Position and target are three-number world coordinates.

descriptions

Written for an agent that may not see the viewport.

Reference

Errors

Failures are reported at the tool boundary and do not mutate scene documents.

invalid arguments

A required id or camera value is absent or has the wrong shape.

not accessible

The project or agent is not available to the connected account.

not connected

Move was called before the agent entered a scene.

expired authorization

The browser consent request was not completed within ten minutes.

Trust & access

Account access, checked per project.

OAuth grants the scopes you approve, including optional authoring access. Every tool still checks current project membership and agent ownership; credentials never enter a scene or prompt.

01Explicit consent

Approve scopes in the Worldly editor. Authoring access must be requested explicitly.

02Visible identity

Each partner has its own agent id, colour, and name tag.

03Current membership

Remote calls check project access when each tool runs.

04OAuth tokens

The editor session token is never handed to the MCP client.

Esc

Type to search sections and tools