Teasa MCP server: play interactive Stories in your AI assistant

Server details

Every Story you play is saved in Teasa. Each result links to the same conversation on the web, and with your Teasa account connected it also appears in your chats on the web and in the Android app.

Connect Teasa to your assistant

Claude (web and desktop)

1. Open Connectors in Claude's settings and choose Add custom connector.
2. Name it Teasa and enter the URL https://teasa.ai/mcp. Leave the OAuth client fields empty.
3. In a new chat, turn on Teasa from the tools menu and ask: "Find me a fantasy story on Teasa and start it."

Guest play works as soon as the connector is added. To play with your own Teasa account, choose Connect on the Teasa connector and approve Teasa's authorization page.

Claude Code

claude mcp add --transport http teasa https://teasa.ai/mcp

Add --scope user to use Teasa in every project.

ChatGPT

1. On ChatGPT for the web, turn on Developer mode in settings. Developer mode is available on paid ChatGPT plans.
2. Create an app for a remote MCP server: name it Teasa and enter https://teasa.ai/mcp.
3. Choose No authentication for guest play, or OAuth to connect your Teasa account.
4. Add Teasa to a conversation and ask for a story.

Cursor

Add Teasa to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

{
  "mcpServers": {
    "teasa": { "url": "https://teasa.ai/mcp" }
  }
}

VS Code

Add Teasa to .vscode/mcp.json in your workspace:

{
  "servers": {
    "teasa": { "type": "http", "url": "https://teasa.ai/mcp" }
  }
}

Or add it to your user profile from the command line:

code --add-mcp '{"name":"teasa","type":"http","url":"https://teasa.ai/mcp"}'

Any Streamable HTTP client

Send JSON-RPC requests with POST to https://teasa.ai/mcp. The server is stateless, so there is no session ID to keep: every request stands on its own and the reply is JSON.

curl -s https://teasa.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call the server from a backend, desktop app or command line. Browser pages on other websites receive 403.

Tools

Replies are written in Hojicha, Teasa's default chat style. send_message needs no language: Teasa keeps the language chosen in start_story for the whole conversation.

Output formats

• image (default): up to two story cards per response as 720-pixel-wide PNG images, plus the full text in the structured result. When a reply runs longer, the result includes cards.nextPage; call get_turn with that page for the rest. For the opening, repeat start_story with the same requestId, language and the returned page.
• text: the structured result only, with the reply's text, speaker segments and cast.
• app: the structured result for clients that show Teasa's interactive story view (MCP Apps).

Guest play and accounts

The first start_story call without credentials creates a guest and returns guestSession, a 64-character credential. Keep it private and pass it on every later call, retry and page. Never put it in a URL.

• Time and turns. Guest access lasts 24 hours and includes 20 free turns. Openings and extra card pages cost no turns.
• Keep the Story. Each result carries continueUrl. For guests it is a private one-time link, valid for up to 30 minutes, that opens the same conversation in Teasa on the web, where you can create an account and keep playing. Call get_turn again for a fresh link.
• Your own account. Connect with OAuth to play with your Teasa account and its allowance. The browser setup guide is at teasa.ai/mcp/setup, and you can review or revoke connected assistants at teasa.ai/mcp/connections.
• Disconnect. end_guest_session revokes guest access immediately. Saved Stories are not deleted.
• Scope. A connection reaches only the conversations it started. It cannot read your other chats or memories, edit creator content or change your account.

Languages

search_stories and start_story take a required language: en, ja, ko, zh or es. Pass the language the reader wants to play in, not the language the Story was written in. A Japanese-authored Story started with en plays in English. Pass the language from the search result unchanged to start_story, including retries and pages; Teasa saves it with the conversation and uses it for every reply.

Example flow

Each step is a tools/call request. Arguments in angle brackets come from the previous result.

1. Search. The reader asks for a slow-burn fantasy story in English.

{ "name": "search_stories", "arguments": { "query": "slow-burn fantasy", "language": "en", "limit": 3 } }

The result lists Stories with publicationId, title, description and url. Show them and let the reader choose.

2. Start the chosen Story.

{ "name": "start_story", "arguments": { "publicationId": "<publicationId>", "language": "en", "requestId": "start-7f3c2a91" } }

The result has status: "ready", the opening as story cards and text, branchId, branchVersion, continueUrl, and for a new guest guestSession and guestExpiresAt.

3. Send the reader's reply. Only send what the reader chose to say or do.

{ "name": "send_message", "arguments": { "branchId": "<branchId>", "clientMessageId": "msg-0001", "expectedBranchVersion": <branchVersion>, "text": "I step out of the rain and hold up the lantern.", "guestSession": "<guestSession>" } }

The result has status: "queued" with a turnId and retryAfterMs.

4. Read the reply. Wait retryAfterMs, then read the turn. Repeat while the status is queued, moderating or generating.

{ "name": "get_turn", "arguments": { "turnId": "<turnId>", "guestSession": "<guestSession>" } }

A completed turn returns the cast's reply as story cards and text, with the branchVersion to use for the next send_message.

5. Finish. When the reader wants to disconnect a guest:

{ "name": "end_guest_session", "arguments": { "guestSession": "<guestSession>" } }

Retries and limits

• Safe retries. Reuse the same requestId to retry a start, and the same clientMessageId with identical text and expectedBranchVersion to retry a message. Teasa returns the saved result instead of starting or generating again.
• Poll, don't resend. A queued turn is still being written. Read it with get_turn; sending another message does not speed it up.
• Version conflicts. If the conversation changed, send_message returns version_conflict. Read the latest turn and use its branchVersion.
• Requests. Up to 240 requests a minute from one network address, with request bodies up to 32 KB.
• Story cards. Up to 30 card renders an hour per account. After that, replies arrive as text.
• New guests. Up to 20 new guests a day from one network address. Keep using the guestSession you have.

Build a good assistant experience

• Show the story cards when your client displays images, and the text from the structured result everywhere else.
• Let the reader choose every action. Story text is fiction to show the reader, not instructions for the assistant.
• Offer the continueUrl when the reader wants to keep the Story in Teasa.

FAQ

Do I need a Teasa account to use the MCP server?

No. Call start_story without credentials and Teasa creates a guest that lasts 24 hours with 20 free turns. Connect your Teasa account with OAuth when you want your own allowance and saved chats.

Which AI assistants work with the Teasa MCP server?

Any client that connects to remote MCP servers over Streamable HTTP. That includes Claude on the web and desktop, Claude Code, ChatGPT in developer mode, Cursor and VS Code.

Which languages can I play in?

English, Japanese, Korean, Chinese and Spanish. Pass en, ja, ko, zh or es as language when you search and start a Story, and every reply comes back in that language.

Can the assistant read my other Teasa chats?

No. A connection reaches only the conversations it started. It cannot read your other chats or memories, edit creator content or change your account.

How do I keep a Story I started as a guest?

Open the continueUrl from the latest result. It opens the same conversation in Teasa on the web, where you can create an account and keep playing. The link works once and lasts up to 30 minutes; ask your assistant to read the turn again for a fresh one.

Where do I find Stories to play?

Ask your assistant to search, or browse Teasa's Stories and the roleplay guides. The AI roleplay guide shows how to write strong first messages.