Imagina MCP server

Imagina speaks MCP (Model Context Protocol), the open standard AI assistants use to talk to apps. Connect your client to discuss worlds, edit drafts, or investigate a playtest.

It runs on your existing account and your existing worlds. Nothing is exported into a separate project, and nothing leaves Imagina except what your assistant reads while you are talking to it.

What your agent can do

A connected agent can read your worlds, including drafts, version history, and world analytics. It can create a draft version of an existing world, edit fields or individual list entries, and attach images you already have. Journey tools let it inspect your own playtests, their debug turns, and the world snapshot each journey uses.

It cannot publish, generate images, spend your Imagina credits, or play turns. It cannot see another user's worlds or journeys. Publishing stays a deliberate act you do in the app.

Server URL and authentication

https://playimagina.com/api/mcp

Use an MCP client that supports Streamable HTTP, sending requests to this URL with POST.

There are two ways to connect. Your client normally uses one:

• Browser sign-in (OAuth). No key to configure. Your client opens Imagina, you sign in and approve the connection. Claude, ChatGPT, Cursor, and Antigravity use this flow.
• Personal API key. For scripts and clients without browser sign-in, generate or copy your key on the Integrations page. Send it in an x-api-key header or as Authorization: Bearer YOUR_API_KEY.

You have one key per account. Treat it like a password. Rotate key on the Integrations page cuts off every client still holding the old one, so it doubles as the panic button. Update the clients you want to keep. Browser sign-ins are revoked separately, with Sign out everywhere under Settings > Security.

The Integrations page carries your key and a copy button for every snippet below.

Connect your client

Claude

On claude.ai or the Claude desktop app:

1. Open Settings > Connectors.
2. Choose Add custom connector.
3. Name it Imagina and paste https://playimagina.com/api/mcp.
4. Click Add, then Connect, and sign in with your Imagina account.

In a conversation, enable Imagina from the tools menu. Custom connectors require a Claude plan that supports them.

Claude Code

Register the server from your terminal:

claude mcp add --transport http imagina https://playimagina.com/api/mcp

Then run /mcp inside Claude Code to sign in with your browser.

ChatGPT

Open the official Imagina app in ChatGPT, connect it, and sign in with your Imagina account when prompted.

Once connected, mention Imagina in a conversation or pick it from the apps menu.

Cursor

Add this to your project's .cursor/mcp.json or your global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "imagina": {
      "url": "https://playimagina.com/api/mcp"
    }
  }
}

Cursor shows a sign-in prompt for the server. Log in with your Imagina account.

Antigravity

The Antigravity editor and CLI share MCP configuration.

1. In the editor, open the … menu at the top of the agent panel, then MCP Servers > Manage MCP Servers.
2. Click View raw config, add the block below, and save. Antigravity requires serverUrl, not url.
3. Hit Refresh in the server list and sign in when the browser opens. If nothing happens, open the agent settings, go to Customizations, and click Authenticate next to imagina.

{
  "mcpServers": {
    "imagina": {
      "serverUrl": "https://playimagina.com/api/mcp"
    }
  }
}

You can also edit the file directly: ~/.gemini/config/mcp_config.json for global configuration, or .agents/mcp_config.json for a workspace. In the CLI, type /mcp to check the connection.

Any other MCP client

Many clients accept this configuration and handle browser sign-in themselves:

{
  "mcpServers": {
    "imagina": {
      "url": "https://playimagina.com/api/mcp"
    }
  }
}

If yours needs an API key, use:

{
  "mcpServers": {
    "imagina": {
      "url": "https://playimagina.com/api/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your personal key. For Antigravity's key-based setup, keep the same headers block but use serverUrl in place of url.

How to talk to it

Ask in plain language and name the world. Your agent finds the IDs itself. World and journey IDs differ: a world is your reusable definition, a journey is one playthrough.

Before writing world content, tell your agent to call get_authoring_guide. Before writing anything a player will read, have it call get_markdown_guide too. The guides explain what each field is for and which formatting works on each surface.

Read only what the task needs

Start with get_world_outline, a compact view of fields, sizes, and list entries. Then use get_world with fields, such as ["npcs", "generalInstructions"], to read the relevant sections. Reads default to the latest version, or the agent can request a specific version.

Whole-world tool results waste conversation space. For a full read, ask an agent with terminal access to fetch the short-lived _restApi.url returned by get_world or get_world_outline, save it, and search the file with grep or jq:

curl -s 'PASTE_THE_RESTAPI_URL_HERE' -o world.json
jq '.npcs[].name' world.json

The URL works for about five minutes. If it expires, read again for a fresh one.

Make targeted edits

Check the latest version first. Reuse an existing unpublished draft. If the latest version is published, call create_world_version to open a draft cloned from it. You can also explicitly ask for a fresh version.

Use upsert_world_list_item or delete_world_list_item for one NPC, lore entry, or beat. Editing one entry costs less and preserves edits to sibling entries. Use update_world for scalar fields, such as the description, or an intentional whole-field replacement. Arrays sent through update_world replace the entire list.

Ask your agent to check _authoringDiagnostics on world reads. These flag references left behind when a tracker or beat was renamed or deleted, such as a setting still pointing to an old tracker. They are advisory, and some tracker-creation hints may be intentional. Fix stale references rather than recreating obsolete trackers just to silence a warning.

Review in the editor, then publish yourself.

Prompts to try

Read the authoring and Markdown guides, then critique the opening of The Glass Harbor. Does it give the player a concrete choice? Suggest changes without saving anything yet.

In The Glass Harbor's draft, change Mara's description so she distrusts the harbor master but still depends on his work. Read the authoring guide first and edit only Mara's entry.

In my latest Glass Harbor playtest, the lighthouse beat never happened. Compare the recent debug turns with the journey's frozen world and explain which condition was missing.

Attach the transparent PNG I provided as Mara's neutral sprite in The Glass Harbor's draft. Check the image requirements first, then tell me which character and slot you updated.

Drafts and publishing

MCP writes only touch versions that have never been published. Once published, a version is frozen to this connection, even if you later unpublish it. An agent cannot change your live world under its players.

To change a published world, work in a new draft. Review and publish in Imagina, where content review also happens.

Endings use one mode at a time. When update_world switches simple endings to multiple endings, it converts the existing pair. Switching back or turning endings off removes the current endings and requires an explicit clearing confirmation in the update. Ask your agent to explain that loss before changing modes.

Tool reference

Your agent reads the input schemas itself. Write tools change drafts or uploads in progress. Replacements and deletions are destructive, even within a draft.

Guides and account

Worlds

Images

Journeys

Attaching images

You can attach existing art as a title card, background, character portrait, character gallery image or sprite, or location image. Call get_image_requirements first so you choose the right size and shape.

JPEG, PNG, and WebP are accepted, and everything is stored as WebP. An image is scaled to fit the slot box with its proportions kept, never cropped and never enlarged, so send the right shape when framing matters. A sprite needs a transparent cutout. Generating new images stays in the app.

Debugging your journeys

Journey tools are for debugging worlds you wrote. They only reach journeys you played on your own worlds, never someone else's playthrough, even on your world.

A journey freezes the world at its start. Later draft edits do not rewrite that snapshot. If the storyteller behaves like the old version, get_journey_world shows what it is actually reading for that journey.

By default, it returns journey information and an _restApi URL. Request fields for a small read, or download the snapshot. Compare it with get_journey_debug to check which trackers changed, which beats fired, and what lore was revealed.

Troubleshooting

• Connection refused or 401: check the URL and reconnect. Your sign-in may have expired, or your client may still hold an old key after a rotation. Use whoami once connected to confirm the account.
• Method not allowed: a client that only tries GET will not work. The MCP endpoint answers POST.
• Claude connector unavailable: check that your plan supports custom connectors.
• Browser sign-in unavailable: use your API key in a client that accepts headers.
• Published-version write refused: use an existing unpublished draft or create a new version.

Still stuck? Email [email protected].

Return to Integrations for connection details, or the creator guide for help shaping your world.