In the Story MCP server

What it is

The In the Story MCP server links your AI assistant to your In the Story author account. MCP (Model Context Protocol) is an open standard for connecting AI assistants to other services. The server is remote, so there is nothing to install.

It is for authors. You need an author account on In the Story, and you sign in with it to connect. Readers don't need it.

Your assistant can look up your books, how readers move through them, what readers say and what you earn. It can also create and change drafts, and send a version to the In the Story team for review. You choose what each connection may do.

What you can ask

Ask in your own words. Your assistant picks the tools it needs. Some examples:

• How did my books do this month compared with last month?
• Where do readers stop reading my newest book, and which endings do they reach?
• Which choices in my book does almost nobody take?
• What are readers saying in their one- and two-star reviews?
• How much did I earn last quarter, by book and by store?
• What problems have readers reported in my latest book?
• Find every step in my draft that mentions the lighthouse keeper, and make sure her name is spelled the same way everywhere.
• Make a new draft of my latest book, find dead ends or steps no reader can reach, and fix them.

The last two change your drafts, so they need the Edit your books permission.

Set it up

You create an app in the authors portal, add the server to your MCP client, then approve the connection. It takes a few minutes.

1. Create an app in the authors portal

   • Sign in to the authors portal at authors.inthestory.app.
   • Open the user menu and choose Integrations.
   • Choose Create app and give the app a name.
   • Choose what it may do. Insights (read only) covers reading and analytics. Editing adds changing your drafts. To let your assistant send a draft for review, also tick Submit for review. Each permission is explained below.
   • Leave Confidential client on for a hosted client that keeps a secret on its server. Turn it off for a client that runs on your own computer. That kind gets no secret and uses PKCE instead.
   • Copy the Client id, and for a confidential app the Client secret. The secret is shown only once. If you lose it, create a new app.

2. Add the server to your MCP client

   Any MCP client

   1. Add a remote MCP server with this URL:

      https://api.inthestory.app/mcp

      Copy
   2. Enter the client id, and the client secret if the app is confidential. The server has no dynamic client registration, so your client needs a place to enter them.
   3. Connect. Your browser opens In the Story for step 3.

   Your client must meet the technical details at the end of this section. A client on your own computer works if it uses a loopback redirect. Of the hosted clients, only Claude's callback is accepted today.

   Example: claude.ai and the Claude desktop app

   1. Create the app with Confidential client on.
   2. In Claude, open Settings, then Connectors, then Add custom connector, and paste the server URL.
   3. Open Advanced settings and paste the client id and the client secret.
   4. Connect. Your browser opens In the Story for step 3.

   Example: Claude Code

   1. Create the app with Confidential client off.
   2. Run this in a terminal, with your client id in place of YOUR_CLIENT_ID. The app's row in Integrations has a button that copies it with your client id filled in.

      claude mcp add --transport http --client-id YOUR_CLIENT_ID inthestory https://api.inthestory.app/mcp

      Copy
   3. Then run this. Your browser opens In the Story for step 3.

      claude mcp login inthestory

      Copy

3. Approve the connection

   In the Story asks you to sign in. Check the app name, the client id and what it asks for, then choose Approve. Only approve a connection you just started yourself. You land back in your client, connected.

Change or remove it later

• To change what an app may do, choose Edit permissions on its row in Integrations. A new permission works after you reconnect in your client and approve it.
• To disconnect, choose Revoke app on its row.

Technical details

Server URL

https://api.inthestory.app/mcp

Transport

Streamable HTTP, POST only. The server is stateless: it keeps no sessions and opens no server-sent stream, so GET and DELETE answer 405.

Protocol versions

2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26.

Sign-in

OAuth 2.1 authorization code flow with PKCE (S256 only), refresh tokens and RFC 8707 resource indicators.

Discovery

https://api.inthestory.app/.well-known/oauth-protected-resource (also at /.well-known/oauth-protected-resource/mcp) and https://api.inthestory.app/.well-known/oauth-authorization-server

Endpoints

/oauth/authorize, /oauth/token and /oauth/revoke on https://api.inthestory.app

Client registration

No dynamic client registration. Create the client in Integrations. Public clients without a secret are supported.

Token endpoint auth

client_secret_basic, client_secret_post or none

Redirect URIs

An HTTP loopback address (127.0.0.1, localhost or [::1]) on any port, or Claude's hosted callback, https://claude.ai/api/mcp/auth_callback. Nothing else is accepted.

Browser origins

A request that carries an Origin header is refused unless that origin is on the server's allow list.

Permissions

Each app has its own permissions, and there are five. The Insights (read only) preset turns on the first three, for reading and analytics. Editing turns on the first four, so your assistant can also change drafts. Submit for review is in neither preset. Tick it if you want your assistant to send drafts for review.

• Some clients ask for every permission when they connect. They get only the ones you ticked on the app, and the approval screen lists exactly those.
• A permission is a limit, not a pass. Every call is still checked against your own access to the author profile it touches. If you can only read someone else's author profile in the portal, your assistant can only read it too.
• No permission lets an app manage collaborators. Who can work on your books is decided in the portal.

Security and your data

This section is for anyone deciding whether to allow the server, including IT admins. The protocol details are at the end of the setup section.

Sign-in and tokens

• Sign-in uses OAuth with PKCE. Every client must use the S256 method.
• A client id and secret grant nothing on their own. The author signs in to In the Story and approves each new connection.
• Access tokens last one hour. Refresh tokens are replaced each time they are used.
• Tokens are issued for this server only. The rest of the In the Story API refuses them.

How access is cut off

• Revoking the app in Integrations stops the connection on its next call.
• Removing a permission from the app takes effect on the next call.
• If the author loses author access, or the account is disabled or deleted, every connection stops at its next token refresh.
• The author must approve the connection again every 90 days, however often it is used.

What every call goes through

• The server reads and changes data only through the same public In the Story API the authors portal uses, with the same per-author permission checks. It has no direct access to book, reader or sales data.
• Nothing is cached. Every answer is read live.
• No permission grants admin access, and admin routes refuse the server.
• Every change is checked against a fixed list of allowed actions. Anything not on the list is refused.

How changes are kept safe

• Book content changes only in drafts. The API refuses to edit a published version or one waiting for review. To revise a published book, your assistant starts a new draft, and readers keep the published book until you publish the new version.
• Importing a character profile you already have saves a new version of it right away. Your books keep the version they were built from, so readers see the change only when you publish a book built from the new one. Earlier versions can't be read back, so keep a copy of the old file.
• Publishing stays with you. With Submit for review, an app can send a draft to the In the Story team, and nothing more. Putting a book on the store is done by a person, in the portal.
• Tools that change something are marked as such, so your client can ask you before each change.
• At any permission level, an app can't delete a story, a version or an author profile, change who can work on your books, transfer ownership, or change the account itself. That includes creating another connection.

Series are the exception. A series has no draft, so with Edit your books, renaming a series or adding, removing or reordering its books shows to readers right away, even for published books. The portal works the same way.

What your assistant sees

• Whatever a tool returns becomes part of your conversation with your AI assistant. Most tools return summaries. Exporting a version returns the full text of the book.
• Analytics never identify a reader and can't be filtered by reader. Reviews include the reviewer's name, as the store shows it.
• Text written by readers, such as reviews and reported issues, is marked as untrusted: it is data to report on, not instructions to follow.

Tools

The server has 41 tools. Your client only sees the tools your app's permissions allow.

Reports, readers and earnings

Needs Read reader insights. The two reports and step traffic also need Read your books.

its_get_book_report

Everything about one book in one call: size, difficulty, readers, where reads stop, endings reached, reviews, sales, royalties, issues and health.

its_get_author_report

Your dashboard in one call: royalties, sales, books sold, readers, completion, ratings and the reader funnel, each compared with the previous period.

its_analyze_sessions

Reading-session analytics by author, story, version or tag. On one book, it can group by final step or by ending.

its_analyze_purchases

Purchase analytics, with the same filters plus store.

its_analyze_step_traffic

How readers moved through one book, step by step: how many reached each step, how many stopped there and where they went next.

its_list_reviews

What readers wrote about one book: a star breakdown, then the reviews, newest first. Can filter by stars.

its_list_issues

Problems readers reported on a story.

its_get_statement

What you earned: your balances, then a statement for a period, row by row or summed by book, store or month.

Your books

Needs Read your books.

its_get_me

The account this connection acts as, and the author profiles it can use.

its_list_authors

Author profiles you can work on, with your permission on each.

its_get_author

One author profile: details, social links and collaborators.

its_list_stories

Stories under an author. Can add each released book's reads, finish rate, rating and sales.

its_get_story

One story, with a summary of each version.

its_list_story_versions

A story's versions, with tag, status, language, price and step count.

its_get_story_version

One version: its details, the size of the book and, if asked, its modules.

its_list_steps

An index of a version's steps, without the text.

its_get_step

One step in full, or up to ten steps by reference.

its_search_steps

Finds steps whose text, title or choice labels contain the words you ask for.

its_get_version_map

The shape of a book: counts, the main path, unreachable steps, dead ends, key decisions and endings. Or one step with its links in and out.

its_list_series

Series under an author.

its_get_series

One series and its books in reading order.

Public catalog

Needs Read the public catalog.

its_search_catalog

Searches the public store.

its_get_catalog_item

A published book as a reader sees it.

Editing

Needs Edit your books. Story changes apply to drafts only. Series changes are live right away.

its_create_story

Starts a new story and its first draft.

its_create_version

Starts a new draft from the current version.

its_update_version

Changes a draft's title, web address, description, categories, first step or price.

its_create_step

Adds a step to a draft.

its_update_step

Changes a step's text or settings.

its_delete_step

Removes a step from a draft.

its_create_series

Creates a series.

its_update_series

Renames a series and sets its web address.

its_add_series_book

Adds a story to a series.

its_set_series_book_number

Sets a book's place in the reading order.

its_remove_series_book

Takes a story out of a series.

Submitting for review

Needs Submit for review.

its_submit_version

Sends a draft to the In the Story team for approval.

Export and import

Import needs Edit your books. The others need Read your books.

its_export_version

Reads a whole version out as .ist text, one part at a time.

its_import_version

Replaces a draft with a complete .ist document.

its_get_import_status

Says whether an import worked, and what failed.

its_list_character_profiles

Lists an author's character profiles.

its_export_character_profile

Reads a character profile out as text.

its_import_character_profile

Creates a character profile from a document, or saves a new version of one you have.

Help

Questions, or something not working? Write to authors@inthestory.app.

See also: Privacy Policy · Terms of Service