Connect an AI Agent to Your Book Over MCP.

Three Ways In

Choose by where the book lives.

	shiro mcp	Desktop local API	Cloud
Works on	One project folder	The project open in the app	Cloud projects the writer can reach
Transport	stdio	Streamable HTTP	Streamable HTTP
Address	None	http://127.0.0.1:7341/mcp/<key>	https://api.meetshiro.com/mcp
Authentication	None, it runs as you	One key per client	OAuth 2.1
Edits	Proposals, or --auto	Proposals, or Auto per client	Proposals, within the writer’s role
Needs	Node and a build from source	The app running, with the API turned on	A Shiro account

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

The Command Line: shiro mcp

The shiro command is built from source, so you need Node 22 and pnpm 10.

git clone https://github.com/Quentin967/shiro
cd shiro
pnpm install
pnpm --filter shiro build
node apps/cli/dist/cli.js 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:

• --auto lets edits land, with Undo, instead of waiting as proposals.
• --client <name> is the agent’s name on its proposals and in history. The default is Agent.
• --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"
      ]
    }
  }
}

Proposals are saved as JSON in the project’s .shiro/proposals/ folder, and the manuscript files don’t change. The writer applies or rejects them in the Shiro panel.

The Desktop App: Local API

This is off by default.

1. In the app, open You › Agents and turn on “Let agents on this computer connect”.
2. Under “Connect a tool”, 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 Code, Cursor, Codex, Claude Desktop 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 has its own Manual or Auto setting.

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

Request	Returns
GET /project	The project’s title, type, language and word count
GET /outline	The outline
GET /world	World entries, as JSON
GET /scenes/<id>	One scene
GET /tools	The 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. Dynamic client registration is at /oauth/register. Redirect URIs must be https or loopback.
• 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.
• Tokens. Access tokens last an hour. Refresh tokens rotate on every use, and the old pair stops working when a new one is issued. 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 role	What the agent can do
Owner or co-author	Edit, as proposals
Editor	Propose only
Commenter	Comment only
Viewer	Read only

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

What Needs the Writer’s Say-So

In Manual, every edit waits as a proposal. Auto lets edits land at once, with Undo. Some things ask in either mode: deleting, large replacements, Publish actions, moving and merging scenes, and a replace_all of more than 50 changes. The tool answers with a question instead of acting. Once the writer has agreed in the chat, the agent calls the same tool again with the same input and "confirmed": true.

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

There are about 30. The full reference, with every parameter, is in the repository.

Group	Tools	What they do
Read only	read, search, count, check, skill	Read 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.
Text	edit, replace_all, write, alternatives, snapshots	Change a scene by exact quote, find and replace with a preview, keep named takes of a scene, take and restore snapshots.
Structure and revision	structure, labels, whiteboard, passes, comments, note, inbox, memory, goals	Create, 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 Research	entries, folders, media, maps, style_sheet, language	Handle entries and their links, folders, media boards, maps with pins and routes, the style sheet and invented languages.
Output	translations, adapt, publish, compile, export, beta_reads	Write 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.
Project	project, book	Read the project card, list, open and create projects, read the book’s settings.

write generates prose with Shiro’s own Write model, and answers “No Write model is set” over the shiro mcp command. 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, 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 code behind all of it is open source.

The Questions People Ask

Can an agent change my book without my seeing it?

Not by default. In Manual, edits wait in the Shiro panel as proposals you apply or reject. If you choose Auto, they land at once with Undo. Deleting, large replacements and Publish actions ask you first in either mode.

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.