Chat clients (MCP)

You can connect Obscura to a chat client you already use: Claude Desktop, Claude Code or Codex. The chat reads a scene's plan, cards, memory and texts, writes a draft with its own model and saves it in Obscura. You need no API key of your own: the model runs under the chat client's account, and Obscura calls no model itself.

The link is storygen-mcp, a small program the chat client starts by itself. It talks to the Obscura running on your computer and nowhere else.

What the chat can do

The chat gets twenty-six tools:

The chat cannot delete stories or scenes, move them to the trash, reorder scenes, run generation, synopsis suggestions or the evaluator, or change prompts, the evaluator, the budget and keys.

Installation

storygen-mcp is part of the regular installation. If you installed Obscura earlier, repeat the two install commands in the application folder to add the new dependencies:

./.venv/Scripts/python.exe -m pip install -r requirements-lock.txt
./.venv/Scripts/python.exe -m pip install --no-deps -e ".[web,publication]"

storygen-mcp.exe then appears in .venv/Scripts/. The examples below use C:\Obscura as the application folder; use your own.

Connecting

The button in the library

The easiest way to connect is from the Obscura library: expand the “Connect to Claude” block.

The chat cannot connect or restart Claude by itself: only you do this, in Obscura.

By hand

Start Obscura as usual before you work. The chat client connects to http://127.0.0.1:8765. If Obscura runs on another port, add the arguments --url http://127.0.0.1:<port>.

If you start Obscura without a console through storygen-desktop (installation), add the arguments --data-dir <stories folder> instead of --url (by default %USERPROFILE%\Obscura). Then you do not need to start Obscura beforehand: on the chat's first request the bridge finds it on any port and, if it is not running, quietly starts it in the tray without a browser. Obscura stays in the tray after you close the chat; you can quit it from the tray icon.

Claude Code. In a terminal:

claude mcp add --scope user obscura -- C:\Obscura\.venv\Scripts\storygen-mcp.exe

--scope user makes the server available in any folder. Without it, Claude Code sees the server only in the folder where you ran the command.

Claude Desktop. Add the server to the settings file claude_desktop_config.json. Where the file is depends on how Claude Desktop was installed:

The file may already hold the application's own settings: keep them and add an mcpServers section next to them. While Claude Desktop runs, it rewrites this file itself, so first quit the application completely, including its icon in the notification area. Then save the file and start Claude Desktop again. A file with only this server looks like this:

{
  "mcpServers": {
    "obscura": {
      "command": "C:\\Obscura\\.venv\\Scripts\\storygen-mcp.exe"
    }
  }
}

For another port add "args": ["--url", "http://127.0.0.1:8770"]. In the claude mcp add and codex mcp add commands the arguments go after the program path: … storygen-mcp.exe --url http://127.0.0.1:8770.

Codex. In a terminal:

codex mcp add obscura -- C:\Obscura\.venv\Scripts\storygen-mcp.exe

Or add a [mcp_servers.obscura] section with the line command = 'C:\Obscura\.venv\Scripts\storygen-mcp.exe' to ~/.codex/config.toml.

Browser chat clients (claude.ai, chatgpt.com) do not support local servers.

Writing with the chat

  1. Discuss the idea, the plan and the characters with the chat.
  2. Ask it to import the plan and the characters into the story. The chat can create the story itself (see below), or you create it in Obscura beforehand. The import adds materials the same way as the form and is never retried on its own.
  3. Ask it to read the first scene's context and write a draft. The chat saves it as the scene's current draft.
  4. To extend or rewrite an existing draft, ask the chat to read it first. The chat writes over the text it has read, so the edits you made in Obscura are not lost.
  5. Open the scene in Obscura from the link in the chat. The previous draft, if there was one, stays in the version history.
  6. Rewrite the draft in your own words in rewriting from memory, approve the prose and update the scene's memory. Ask the chat for a rewriting link: it opens the mode right away, without looking for the scene and the button.
  7. Move on to the next scene.

Start a story from the chat

Ask the chat to create a story: a title, a language (Ukrainian or English) and, if you like, an age rating. The chat then takes the plan and character templates, fills them in with you and imports them. After that it can add scenes, rewrite a scene plan, and change the story's title, language or rating.

A draft from the chat is labelled "External client: <name>" in the version history and in the status row above the editor. If the chat named its model, the model is shown too. This is the client's claim: Obscura cannot check which model actually wrote the text. Once you save your own edit, the label leaves the status row; in the history it stays next to the chat's version.

You can keep Obscura open next to the chat. When you return to the Obscura window, the page checks on its own whether the chat wrote anything. If the editor has no unsaved edits, you see the new draft right away. If it has, your text stays, and "The scene was changed elsewhere" appears above the editor with an "Open the newer version" button; it asks for confirmation before replacing the text.

Publishing from the chat

The chat can fill in the publication card, add an author signature, set a cover and export the book.

Settings from the chat

The chat can change the genre, tone, point of view, style rules and story length, choose a provider and a model for a role, change the context, temperature or editor mode, and apply a saved role preset.

Who writes the texts

Each story has a mode: The chat writes or Obscura writes. A story created by the chat has the The chat writes mode by default; the new story form in Obscura has Obscura writes selected by default. The story list and the story details in the chat show the mode.

Obscura runs from the chat

In a story with the Obscura writes mode the chat can ask Obscura to run one scene stage — the scene brief, the draft, editing or memory — or to suggest a publication card. This is an ordinary Obscura run: your role models, the story budget and the same readiness check as for the buttons.

Scene stages from the chat

The chat can go through every stage of a scene itself: write the scene brief, write the draft, edit it and update the memory. For each stage it gets the same instructions as an Obscura model: the standard prompts or your own, the role settings, the story language, the rating and the memory of earlier scenes. For the draft, the writer's instructions come with the scene context.

Start a story with one request

The chat client sees the “Start a story” prompt (start_story). It leads the chat from an idea to a story: create the story in the “chat writes” mode, fill in the plan and the characters, write the scenes and finally give a link to read and edit the story in the Obscura window.

The Microsoft Store version

The Microsoft Store version includes the MCP bridge: there is nothing to install separately, and the “Connect to Claude” button in the library is expanded right away. A new story in it uses the “chat writes” mode by default. If Obscura is not running, Claude quietly starts it in the tray when it is needed; you can quit it from the tray icon.

The free version does not write long prose (books, parts, arcs), series or scenes above the rating limit. When the chat meets such a limit, it explains that this is a feature of the paid version and gives the waitlist link.

Limitations