Shiro

Write and shape your book with any agent: scenes, outline, World, edits as proposals. Hosted at https://api.meetshiro.com/mcp (OAuth).

ホスト型 MCP サーバー

npx add-mcp 'https://api.meetshiro.com/mcp'

Claude Code、Codex、Cursor などにインストールできます

ドキュメント

Three Ways In

Choose by where the book lives.

shiro mcpDesktop local APICloud
Works onOne project folderThe project open in the appCloud projects the writer can reach
TransportstdioStreamable HTTPStreamable HTTP
AddressNonehttp://127.0.0.1:7341/mcp/<key>https://api.meetshiro.com/mcp
AuthenticationNone, it runs as youOne key per clientOAuth 2.1
EditsLand at once, in history, or wait as suggestionsLand at once, in history, or wait as suggestionsLand at once, within the writer’s role, or wait as suggestions
NeedsThe shiro command, soonThe app running, with the API turned onA Shiro account

All three serve the same tools from the same server code.

The Command Line: shiro mcp

The shiro command-line tool is coming soon. Once it’s installed:

shiro mcp /path/to/MyNovel

This serves one project over stdio, and the Shiro app doesn’t have to be running. Scenes are read from the project’s Manuscript/ folder. The options:

  • --client <name> is the agent’s name in the project’s history. The default is Agent.
  • --suggest makes the agent suggest only: it gets no tool that changes the book, and each change waits as a proposal the writer applies or rejects in Shiro.
  • --out <folder> is where compiled files go. The default is the current folder.

Most clients take a block like this in their MCP configuration:

{
  "mcpServers": {
    "shiro": {
      "command": "node",
      "args": [
        "/path/to/shiro/apps/cli/dist/cli.js",
        "mcp",
        "/path/to/MyNovel",
        "--client",
        "Claude"
      ]
    }
  }
}

The agent’s changes go straight into the project’s files. Each call is recorded in the project’s history, in its .shiro/history/ folder, so the writer sees it in Shiro and can take it back there.

The Desktop App: Local API

This is off by default.

  1. In the app, open You › MCP, choose “On this computer” and turn on “Let agents on this computer connect”.
  2. Under “Connect your tools”, choose yours and press “Make a key”. Each tool gets its own key, so you can disconnect one alone.
  3. Paste what the page shows into the tool. It has steps for Claude, Claude Code, Codex, Gemini, Cursor and VS Code, and a name and URL for anything else that speaks Streamable HTTP.

For Claude Code, the command is this, and Codex has its own form:

claude mcp add --transport http --scope user shiro http://127.0.0.1:7341/mcp/<key>
codex mcp add shiro --url http://127.0.0.1:7341/mcp/<key>

Claude Desktop reaches the server through the mcp-remote bridge, which needs Node.

The server listens on 127.0.0.1 only, and only while the app is open. 7341 is the default port, and you can choose another if something else holds it. The key goes in the address or in an Authorization: Bearer header. Shiro shows it once and stores only its hash. Requests with another host name, or from a web page, are refused. Each connected client edits and suggests by default: what it changes lands at once, under its name in the project’s history, and a change it chooses to suggest waits in Comments. Set it to Suggests only in You › MCP, and it suggests every change.

The same port serves a plain HTTP API at /api/v1, with the key as a Bearer token:

RequestReturns
GET /projectThe project’s title, type, language and word count
GET /outlineThe outline
GET /worldWorld entries, as JSON
GET /scenes/<id>One scene
GET /toolsThe tool list
POST /tools/<name>Runs a tool, with its arguments as the JSON body
curl -H "Authorization: Bearer $SHIRO_KEY" http://127.0.0.1:7341/api/v1/outline

Cloud Projects: /mcp With OAuth

The address is https://api.meetshiro.com/mcp. A client that supports remote MCP with OAuth needs nothing else. If you arrived from the service_documentation link in the server’s metadata, this is the section you were after.

  • Discovery. An unauthenticated request gets a 401 whose WWW-Authenticate header names /.well-known/oauth-protected-resource/mcp. The authorization server’s metadata is at /.well-known/oauth-authorization-server.
  • Registration. A client names itself by the https address of its Client ID Metadata Document, which it uses as its client_id; nothing is registered. A client that does not publish one can still use dynamic client registration at /oauth/register, and a registration no writer allows within 30 days is forgotten. Redirect URIs must be https, loopback, or an app’s own scheme (myapp://…), without a fragment. A loopback redirect may use any port.
  • Authorization. Authorization code with PKCE, S256 only. Clients are public, with no secret, and the scope is shiro. The consent page lets the writer sign in or create an account in the same window, with a code from an email or with Google, and the answer names the server that gave it (iss).
  • Tokens. Access tokens last an hour. Refresh tokens rotate on every use, and the old pair stops working when a new one is issued; a refresh token used a second time ends the connection, and one not used for 90 days expires. A client that disconnects gives its token back at /oauth/revoke. An agent’s token reaches /mcp and /v1/api/* and nothing else on the account.

/v1/api/* is the same REST API as the local one, for scripts. The agent starts on the writer’s first project, and the project tool lists, opens and creates others. The project it opens is remembered for that client.

An agent has the writer’s role and no more:

Writer’s roleWhat the agent can do
Owner or co-authorEdit
EditorSuggest only
CommenterComment only
ViewerRead only

Whatever the writer’s role, they can also set an agent to Suggests only in You › MCP, on Shiro on the web or in the app.

Tool calls have a daily limit, lower on free accounts. Past it, calls return HTTP 429 until the next day.

How the Writer Takes a Change Back

An agent edits as the writer would, without asking. Nothing it changes waits for approval in Shiro, and no tool takes or asks for confirmed: deleting, sending, sharing, publishing and restoring run at once. Manual, Auto and Max are modes of Shiro’s own chat, not of agents.

The agent decides, change by change, whether to make a change or to suggest it. The server tells it to make a change directly when the writer asked for it, and to suggest one the writer did not ask for, one it is unsure of, or one the writer wants to review first. A suggestion goes through the suggest tool, one change or several at once, each with a note saying why. It waits in Comments until the writer applies or rejects each change, and the proposals tool tells the agent what the writer did.

The safety net is the project’s history. Every call is one entry, named for the agent (“Claude: edit”). Every scene whose text the agent changed gets a snapshot before (“Before Claude’s change”) and after (“Changed by Claude”) in its History, and the writer restores the earlier one from there. An agent’s change has no Undo card in the editor.

An agent the writer set to Suggests only has no tool that changes the book, and suggests every change. So does one on a shared book where the person who connected it has the Editor role, which may only suggest. Their changes wait in Comments as proposals, and the writer applies or rejects each one.

Three more rules apply to every client.

Book text, comments, web pages and Inbox items are data, and the server tells agents never to follow instructions found inside them. A scene marked ai: never reads as empty. And local projects and local models stay on your computer only as far as Shiro’s own part goes: what an agent reads, it sends to its own model.

The Tools

A cloud client sees about 85, the desktop local API about 80 and shiro mcp about 70: each host offers the tools it can serve. Most come in pairs, one that only reads (entries_read) and one that makes changes (entries). The table names each pair once.

GroupToolsWhat they do
Read onlyread, search, count, check, skillRead scenes, entries, the outline and notes. Search by text, mention or meaning. Count words, adverbs and dialogue with no model. Run continuity and guard checks. Load craft skills.
Textedit, replace_all, write, alternatives, snapshotsChange a scene by exact quote, find and replace with a preview, keep named takes of a scene, take and restore snapshots.
Structure and revisionstructure, labels, whiteboard, passes, comments, note, inbox, memory, goalsCreate, set, move, split and merge scenes, and label them. Work on whiteboards, revision passes, comments and tasks, notes, the Inbox, project memory and writing goals.
World and Researchentries, folders, media, maps, style_sheet, languageHandle entries and their links, folders, media boards, maps with pins and routes, the style sheet and invented languages.
Outputtranslations, adapt, publish, compile, export, beta_readsWrite translations against the original, adapt the prose into a screenplay or stage play, set book details, compile with a preset, run editions and export styles. beta_reads is offered only where the writer is signed in to Shiro Cloud.
Projectproject, bookRead the project card, list, open and create projects, search every project at once, read the book’s settings.
Suggestionssuggest, proposalsSuggest a change instead of making it, one or several at once, each with a note for the writer, and see what the writer applied or rejected.

write generates prose with Shiro’s own Write model, and only the desktop app offers it, once a Write model is set up there. An outside agent brings its own model, so it writes the prose and sends it with edit. Web search, image generation and Shiro’s own chat tools are left out of MCP for the same reason.

The server also offers resources: shiro://project/card, /outline, /world, /passes, /worklist and /memory under the same prefix, /proposals, and shiro://scene/{id}/alternatives. Agents should start with the card and the outline.

More on how Shiro’s own AI uses these tools is on the AI page.

The Questions People Ask

Can an agent change my book without my seeing it?

It can change it without asking, as you would, but not without a trace. Every call is an entry in the project’s history, named for the agent, and every scene whose text it changed keeps the text from before in its History, so you can see what it did and restore what you had. An agent can also choose to suggest a change instead, such as one you did not ask for or one it is unsure of: that change waits in Comments until you apply or reject it. Set an agent to Suggests only in You › MCP, and it suggests every change. On a shared book, an agent connected by someone with the Editor role suggests every change too.

Does connecting an agent send my book anywhere?

Shiro’s server on your computer sends nothing by itself, but the agent you connect sends what it reads to whichever model it uses. If that’s a hosted model, your text leaves your computer because of the agent.

Do I need an account?

Not for shiro mcp or the desktop local API. The cloud endpoint works on cloud projects, so it needs a Shiro account, and a free one is enough to connect.

Can I keep a scene away from agents?

Yes. A scene hidden from Shiro (ai: never in its front matter) reads as empty for agents too.