How AI integration works

Orbismo exposes every world through the Model Context Protocol (MCP). Any MCP-aware AI tool — Claude, Cursor, ChatGPT, custom agents — can connect to your world over HTTP, see the same entities and lore your team browses in the portal, and, depending on permissions, make changes that show up in the portal as soon as you refresh. Connecting an AI tool is also how you create and edit your world’s content.

The mental model

A world has two front doors onto the same database:

The web portal — where your team browses the canon and manages the world, its settings, and its collaborators.
The MCP server — where content gets authored: AI agents you direct create, edit, and link entities and lore.

Both work against the same data. Whatever your agent creates is visible in the portal on refresh; whatever changes in the portal is visible to the agent on its next query.

Connecting an AI tool

How you connect comes down to two choices.

1. One world, or all of them?

A world URL points a tool at a single world, fixed in the address:
```
https://app.orbismo.com/api/v1/worlds/{world_id}/mcp
```
The connector URL is one URL for every world you grant it. The tool stays connected while the agent switches between worlds on the fly:
```
https://app.orbismo.com/api/v1/mcp
```
See The connector for how switching and access work.

Sign in with Orbismo (OAuth) — the tool sends you to Orbismo to log in, and you approve its access. No secret to copy or store. This works with either URL, and is required for the connector.
API key (oc_live_…) — a per-world token you paste into the tool. This works with a world URL only. See Generate an API key.

Putting it together

Most people — add the connector URL and sign in once, then reach every world you grant. Start with The connector.
Scripts and bearer-only tools that can’t do a sign-in flow — use a world URL with an API key.
Want a tool pinned to one world without managing a key? Use a world URL and sign in.

You’ll find both URLs in the portal: a world’s URL under World Settings → API Connections, and the connector URL on the Connected apps page.

Permissions

What a connected tool can do is governed by your role on each world:

Read-only access — the agent can query, search, and read lore but can’t make changes.
Read-write access — the agent can create, update, and delete entities, lore, and relationships.

With an API key, you set the key’s permission when you create it (a viewer can only create read-only keys). When you sign in, the agent acts with your role on whichever world is active. Either way, the agent only sees the tools its permission allows — if a tool is missing, the connection probably doesn’t have the permission for it.

Try these prompts

Once you’re connected, paste any of these into your AI tool. The agent figures out which MCP tools to call — you just describe what you want in your world’s vocabulary. Read-only prompts work with any connection; the ones that create or link entities need read-write access.

Get oriented in an unfamiliar world.

Give me a full briefing on the entity "Maria Santos" — relationships, lore, and any connected entities I should know about.

Trace a connection you’d forgotten about.

Find every person who is a member of the group "Northside Book Club", and tell me which of them have attended the same events together.

Spot the gaps.

What entities in this world don't have any lore attached yet? Group them by entity type so I can see where I should focus.

Catch contradictions.

Look for chronological conflicts in this world — someone in two places at once, events out of sequence, or dates that don't add up.

Build from a draft.

I just sketched three new places in this note: <paste your text>. Create them as place entities, link each one to the group that meets there, and tag any that are outdoors.

Turn prose into a graph.

Read the lore attached to "Summer Reunion 2025" and create relationships between every person and group mentioned in it.

Transport

Both endpoints speak Streamable HTTP — the modern MCP transport. Most MCP clients support it natively. For clients that only speak stdio, see Other MCP clients for the bridge pattern.

Setup guides

If a connection isn’t working, start with Troubleshooting.