Claude Desktop

This guide connects Claude (Desktop or web) to Orbismo over MCP. Once connected, Claude can read your entities and lore, search your world, and — with write access — create and edit content that shows up in the portal when you refresh.

There are two ways to connect:

• The connector (recommended) — add one URL, sign in with Orbismo, and Claude can reach every world you grant it and switch between them in conversation.
• A single world with an API key — pin Claude to one world using the mcp-remote bridge.

Connector (recommended)

1. In Claude, open Settings → Connectors and click Add custom connector.

2. Fill in:

   • Name: Orbismo
   • URL: https://app.orbismo.com/api/v1/mcp

3. Click Add. Claude opens Orbismo in your browser to sign in and choose which worlds this connector may access. Approve, and you’re returned to Claude.

4. Start a new chat and ask “what tools do you have?” — you should see Orbismo’s tools. If no world is active yet, ask Claude to list your worlds and switch to one.

Note

On the free Claude plan you can add one custom connector; paid plans allow more. The connector is signed-in access — there’s no key to copy or rotate, and you manage which worlds it can reach (or revoke it) from the portal’s Connected apps page. See The connector.

Single world (API key)

Claude Desktop’s connector UI doesn’t accept a static token, so to pin Claude to one world with an API key you use mcp-remote, which bridges a remote HTTP MCP server to the stdio transport Claude Desktop expects. It runs npx mcp-remote … under the hood, so you’ll need Node.js 18+ installed.

You’ll need your world’s ID (the UUID in the portal URL when you’re inside a world) and an API key for that world. Use a read-only key for your first connection so Claude can’t change anything while you test.

1. Open Claude Desktop’s config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   Create it if it doesn’t exist.

2. Add an orbismo entry under mcpServers (merge into any existing servers — don’t replace them):

   {
     "mcpServers": {
       "orbismo": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://app.orbismo.com/api/v1/worlds/<world_id>/mcp",
           "--header",
           "Authorization: Bearer oc_live_<your_key>"
         ]
       }
     }
   }

   Replace <world_id> with your world’s UUID and oc_live_<your_key> with your full key.

3. Fully quit Claude Desktop (on macOS, ⌘Q — closing the window isn’t enough), then reopen it.

4. Start a new chat and ask “What MCP tools do you have access to?” You should see tools like search_entities and get_entity_briefing. If not, see Troubleshooting.

To connect more than one world this way, add a separate entry per world (orbismo-realm-a, orbismo-realm-b, …), each with its own world URL and API key. Keys are scoped to a single world. (Or use the connector, which handles multiple worlds with no extra config.)

Using Claude with your world

Once connected, talk to your world directly — Claude picks the right tool for each request:

• “Search this world for anyone connected to the Northside Book Club.”
• “Give me a full briefing on the entity named ‘Maria Santos’ — relationships, lore, everything.”
• “Create a place called ‘Riverside Café’ and link it as a spot the group ‘Northside Book Club’ meets at.” (write access required)

On the connector, you can also say “switch to my Family History world” to move between worlds mid-conversation.

Next steps

• The connector — switching worlds and managing access.
• Generate an API key — for the single-world method.
• Troubleshooting if something isn’t working.