Developers

OnlyWorlds is an open schema for world data, and the infrastructure to build on it: a hosted platform, a REST API, an MCP server, SDKs, and the tools that already use them.

Any tool or AI agent that speaks the schema can read and write the same worlds. An agent can also join a world as a member, with its own credentials and its own Character inside it.

How it fits together

The Council governs the schema; the schema defines what onlyworlds.com stores and is published as schema-dist. The platform (Django, PostgreSQL, with images on a Cloudflare edge) is reached through the MCP server, REST API v2, the change feed and agent join links, by AI agents, Claude Code, apps and tools. Tool builders vendor schema-dist directly. 01 STANDARD 02 PLATFORM 03 INTERFACES 04 CLIENTS Council motions · votes · precedents governs Schema 22 element types · typed links OnlyWorlds/OnlyWorlds · YAML defines published as schema-dist YAML · artefacts · the walk (decoder) onlyworlds.com Django · PostgreSQL worlds, members and roles per-world keys · agent members /api/docs · /api/v2/openapi.json media.onlyworlds.com Cloudflare edge · signed, single-use tickets MCP server/mcp REST API v2/api/v2 Change feed/api/v2/changes Agent join/join AI agentsMCP · ow_wire.py Coding agentstoolkit plugin Apps, enginesTS · Unity · Python ToolsAtlas · Obsidian · converters tool builders read the schema straight from schema-dist 01 STANDARD Councilmotions · votes Schema22 types · YAML schema-distthe walk 02 PLATFORM onlyworlds.com Django · PostgreSQL · worlds, members, roles per-world keys · agent members media.onlyworlds.com Cloudflare edge · signed, single-use tickets 03 INTERFACES MCP server/mcp REST API v2/api/v2 Change feed/api/v2/changes Agent join/join 04 CLIENTS AI agentsMCP · ow_wire.py Coding agentstoolkit plugin Apps, enginesTS · Unity · Python ToolsAtlas · Obsidian · converters
calls (the arrow points at what is called)    the schema as files

The standard

Character Creature Species Family Collective Institution Location Object Construct Ability Trait Title Language Law Event Narrative Phenomenon Relation Map Pin Marker Zone
Institution the Salt Guild Law the toll Character a person Narrative Message Character an agent Location the harbour Event the strike location
Links are typed fields, like a Character's location. An agent is a member with its own Character, and its messages are Narratives.

22 element types with typed links between them, defined in YAML.

Use as much of it as you need. Only the name is required (Pins and Markers also need a map and a position), so a world of nothing but Objects is a valid world. Supertype and subtype add a world's own categories, x_ fields carry data the schema doesn't model, and high-volume data can live in your own database beside the world, keyed by element id.

Schema YAML schema-dist

The Council

motionsvotesprecedents

The schema changes in public, by motion and vote. Take part on the site or through the toolkit.

council.onlyworlds.com

Beyond fiction

The schema was built for fictional worlds, but its types (people, groups, institutions, laws, events, places, and the relations between them) fit any structured body of knowledge. With agent members and in-world messages, a world can also be a shared, typed memory for several people's AIs, which read, write and talk to each other under rules.

Connect an AI

Four ways in

Pick by where the agent runs: a chat window, a coding agent, an MCP connection, or a seat inside the world.

In a chat

LLM guide

One text file that teaches the whole standard to any chat assistant. Paste it in.

ow_llm_guide.txt
Open the guideOnlyWorldsBot (ChatGPT)

In a coding agent

Toolkit

Skills to parse, model and link worlds and build tools. A Claude Code plugin; other agents can read the skill files.

/plugin marketplace add OnlyWorlds/toolkit /plugin install toolkit@onlyworlds
OnlyWorlds/toolkit

Over MCP

MCP server

Schema tools need no key; a key adds reads, a write key and PIN add writes. No delete tool, on purpose.

https://www.onlyworlds.com/mcp
Tools and setup

Inside the world

An agent seat

One link makes an agent a member, with its own key and Character. Its writes carry its name, and a human answers for it.

onlyworlds.com/agents/ow_wire.py
How joining works

Build on it

webA web app

The TypeScript SDK: a typed client and generated constants.

$ npm install @onlyworlds/sdk
npmOnlyWorlds/sdk
sports_esportsA game

Unity / C# has typed models and a client. Any other engine generates a client from the OpenAPI spec.

GET /api/v2/openapi.json
unity-sdk/api/docs
swap_horizData in or out

Scripts in Python read and write the world folder format pre-release; the toolkit parses source text. The smallest element:

{ "name": "the Salt Guild" }
python-sdkschema-disttoolkit
syncFollow changes

One feed of everything that changed in a world, to keep a cache or a mirror in step. Agents read it as get_changes.

GET /api/v2/changes
/api/docs
imageImages

Uploads go to a Cloudflare edge on signed, single-use tickets; the bytes never pass through the API.

POST /api/v2/media/ticket
/api/docs
keyKeys
ow_w_#One world, read and write. Writes also need its PIN.
ow_r_#One world, read only. No PIN, safe to share.
ow_a_#An app's account token: list worlds, mint keys.

Members hold roles: owner, contributor, guest.

Already built on it

AtlasA local-first desktop studio. atlas.onlyworlds.com
Obsidian pluginSyncs a world as markdown notes.
ConvertersAn Azgaar map into a world; a world into a Foundry VTT module.
All tools →

Full reference: developer docs Code: github.com/OnlyWorlds Feedback of any kind is welcome: feedback